2416

Teradata Director Program
Reference
Release 06.09.00
B035-2416-122A December 2002
The product described in this book is a licensed product of NCR Corporation. BYNET is an NCR trademark registered in the U.S. Patent and Trademark Office. CICS, CICS/400, CICS/600, CICS/ESA, CICS/MVS, CICSPLEX, CICSVIEW, CICS/VSE, DB2, DFSMS/MVS, DFSMS/ VM, IBM, NQS/MVS, OPERATING SYSTEM/2, OS/2, PS/2, MVS, QMS, RACF, SQL/400, VM/ESA, and VTAM are trademarks or registered trademarks of International Business Machines Corporation in the U. S. and other countries. DEC, DECNET, MICROVAX, VAX and VMS are registered trademarks of Digital Equipment Corporation. HEWLETT-PACKARD, HP, HP BRIO, HP BRIO PC, and HP-UX are registered trademarks of Hewlett-Packard Co. KBMS is a trademark of Trinzic Corporation. INTERTEST is a registered trademark of Computer Associates International, Inc. MICROSOFT, MS-DOS, MSN, The Microsoft Network, MULTIPLAN, SQLWINDOWS, WIN32, WINDOWS, and WINDOWS NT are trademarks or registered trademarks of Microsoft Corporation. SAS, SAS/C, SAS/CALC, SAS/CONNECT, and SAS/CPE are registered trademarks of SAS Institute Inc. SOLARIS, SPARC, SUN and SUN OS are trademarks of Sun Microsystems, Inc. TCP/IP protocol is a United States Department of Defense Standard ARPANET protocol. TERADATA and DBC/1012 are registered trademarks of NCR International, Inc. UNICODE is a trademark of Unicode, Inc. UNIX is a registered trademark of The Open Group. X and X/OPEN are registered trademarks of X/Open Company Limited. YNET is a trademark of NCR Corporation. 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 NCR CORPORATION (NCR) 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 NCR intends to announce such features, functions, products, or services in your country. Please consult your local NCR 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. NCR may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please e-mail: teradata-books@lists.ncr.com or write: Information Engineering NCR Corporation 17095 Via Del Campo San Diego, California 92127-1711 U.S.A. Any comments or materials (collectively referred to as Feedback) sent to NCR will be deemed non-confidential. NCR 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, NCR 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-2002, NCR Corporation All Rights Reserved
Preface
Purpose
This book provides an understanding of the client software, which is the portion of the Teradata software that resides in a mainframe client. It describes the operation of the Teradata Director Program (TDP) and includes syntax for TDP commands. TDP is intended for use with any of the NCR servers.
Supported Release
This book was printed in conjunction with: Teradata Utilities Foundation 07.00.00 Teradata Director Program (TDP) 06.09.00
Changes to This Book

This book includes the following changes to support the current release:
Date Description
December 2002
Added new IE Preface Added COMMENT command Added SET USERCS command Added ExtendedResponse Added ExtendedKeepResponse Added rejection threshold Added Track/trap implicit restart Added Trap unsolicited response Added support for LATIN1252_0A Added non-EBCDIC encoding charsets
Audience
This book is intended for the following channel-attached client users: System and application programmers System administrators Database administrators and relational database developers
Teradata Director Program Reference
Preface
Prerequisites
This book is a reference document. There is no prerequisite reading, but you should be familiar with basic computer technology, database management systems, and utilities that load and retrieve data. You should also be familiar with system programming functions for MVS, VM, or VOS3, depending on the operating system that you are using to interface to the Teradata RDBMS. Read the current Release Definition for any additional information that may not have been available at the time this document was completed.
Product Related Publications

Other publications associated with TDP include:
B035-2417-122A Teradata Call-Level Interface Version 2 for Channel-Attached Systems Reference
Teradata Tools and Utilities Release Definition

The Teradata Tools and Utilities Release Definition gives you any additional information received late in the release process that may not have been included in this document. You can also find a list of: Operating systems and Teradata RDBMS versions that the Teradata Tools and Utilities release are certified to work with Product release version numbers Documentation that supports the current release Training and support centers
ii
Preface
Technical Information on the Web

For technical support, additional information, or the latest versions of Teradata publications, you may access online information through the following NCR Web sites:
http://www.info.ncr.com/ A direct link to NCR Information Products Publishing library where you can view, download, or order technical documentation and CD-ROMs. You can also find a Documentation List link for each Teradata Tools and Utilities release. The Documentation List identifies all publications released in support of the current Teradata RDBMS and the Teradata Tools and Utilities release. http://www.ncr.com/ The NCR home page provides links to numerous sources of information about Teradata. Among the links provided are sites that deal with the following subjects: Technical support Customer education courses Case studies of customer experiences with Teradata Third party industry analyses of Teradata data warehousing products White papers Online periodicals
List of Acronyms
The following acronyms are used in this book.
DBA DBS DBW DDL DML GDO ODBC PC QCD Database Administrator Database System or Database Software Database Windows Data Definition Language Data Manipulation Language Globally Distributed Object Open Database Connectivity Personal Computer Query Capture Database
iii
Preface
QCF RAS RDBMS SQL SSO TLE TSET WinCLI
Query Capture Facility Random AMP Samples Relational Database Management System Structured Query Language Single Sign On Target Level Emulation tool Teradata System Emulation Tool Windows Call-Level Interface
iv
Contents
Preface Purpose ............................................................................................................................ i Supported Release .......................................................................................................... i Changes to This Book..................................................................................................... i Audience .......................................................................................................................... i Prerequisites ................................................................................................................... ii Product Related Publications.......................................................................................ii Teradata Tools and Utilities Release Definition........................................................ ii Technical Information on the Web.............................................................................iii List of Acronyms ..........................................................................................................iii
Chapter 1: Client Software Overview Installing Client Software......................................................................................... 11 Teradata Server .......................................................................................................... 11 Client Software........................................................................................................... 11 Communicating with the Teradata Server ................................................................. 13 How TDP Returns Results ............................................................................................. 16 Sessions ............................................................................................................................. 19 Definition ................................................................................................................... 19 Sessions Are Logged On and Off ........................................................................... 19 Session Identification ............................................................................................... 19 Session Pools ................................................................................................................. 110 Introduction.............................................................................................................. 110 Logging Pool Sessions on to the Teradata Server .............................................. 110 Multiple Simultaneous Session Pools .................................................................. 110 Session Logoff Process ........................................................................................... 112 Requests ......................................................................................................................... 113 Introduction.............................................................................................................. 113 Messages .................................................................................................................. 113 Parcels........................................................................................................................ 113 Call-Level Interface ...................................................................................................... 114 Introduction.............................................................................................................. 114 How the Teradata Preprocessor Uses CLI ........................................................... 114
Contents
How Other Languages Can Use CLI .................................................................... 114 More Information About CLI................................................................................. 114 Teradata Director Program .......................................................................................... 115 Introduction.............................................................................................................. 115 Session Logon Source and Messages ................................................................... 115 Parcels and Messages.............................................................................................. 116 Channel Processor and Session Processor Definitions....................................... 116 Resource Allocation Control ....................................................................................... 117 Introduction.............................................................................................................. 117 Why Schedule Session Priorities?.......................................................................... 117 Session Protocol ............................................................................................................. 118 Introduction.............................................................................................................. 118 Characteristics of the Session Protocol ................................................................. 118 Using an Externally Coordinated Commit ................................................................ 119 Introduction.............................................................................................................. 119 Two-Phase Commit Protocol ................................................................................ 119 In-Doubt Session Resolution ................................................................................. 119
Chapter 2: Communications Routines Operating Systems Supported................................................................................. 21 CLI Routines..................................................................................................................... 22 Introduction ............................................................................................................... 22 How CLI Routines Are Used .................................................................................. 22 The CLI Library ......................................................................................................... 22 For More Information ............................................................................................... 23 UTC Routines .................................................................................................................. 24 Introduction................................................................................................................ 24 Routines Under MVS and VOS3 ............................................................................. 24 Routines Under VM/CMS ....................................................................................... 24 HSIT Routines ................................................................................................................. 25 Introduction................................................................................................................ 25 Request Initiation....................................................................................................... 25 Valid Request Types.................................................................................................. 25 Request Completion .................................................................................................. 25 Session Status ............................................................................................................. 26 HSIU Routines ................................................................................................................ 27 Introduction................................................................................................................ 27 Global Memory Management (SVC Mode) .......................................................... 27 Inter Address Space Services .................................................................................. 27 Address Space Termination .................................................................................... 28 End of Memory Cleanup ......................................................................................... 28
vi
Contents
Operator Command Interface.................................................................................. 28 Job Wait Timeout Prevention .................................................................................. 29 SRB Services ............................................................................................................... 29 UTC Communication Techniques............................................................................... 210 Introduction.............................................................................................................. 210 MVS Communication Techniques ........................................................................ 210 Communication Using the SVC Technique ........................................................ 210 Communication Using the Program Call Technique ........................................ 211 VM Communication Technique ........................................................................... 211 Job Wait Timeout for VM ....................................................................................... 211
Chapter 3: Performance Measurement DBCAREA Fields ...................................................................................................... 31 DBCTSTMP ................................................................................................................ 31 DBCTIME.................................................................................................................... 31 TDP User Transaction Collection Exit.......................................................................... 33 Introduction................................................................................................................ 33 Types of Calls Processed by TDPUTCE ................................................................ 33 Parameters Passed ..................................................................................................... 33 Developing Collection Applications ...................................................................... 34 Customizing TDPUTCE .......................................................................................... 34 Installing a Customized TDPUTCE Under MVS or VOS3 .................................. 35 Installing a Customized TDPUTCE Under VM ................................................... 35 General Tuning Options................................................................................................. 36 Introduction................................................................................................................ 36 TDP Options .............................................................................................................. 36 Monitoring Performance and TDP Cells ............................................................... 36 Tuning TDP Cells to Optimize Performance ........................................................ 37 Scenario ....................................................................................................................... 39 Example of How to Analyze Cell Usage Optimization .................................... 310 Observations............................................................................................................. 311 Procedure ................................................................................................................. 311 System Options ....................................................................................................... 311 MVS and VOS3 Performance Measurement ............................................................. 312 Introduction.............................................................................................................. 312 SMF/SMS Records ................................................................................................. 312 CP Shutdown Record ................................................................................................... 313 Logoff Record ................................................................................................................ 314 Security Violations Record .......................................................................................... 315 TDP Shutdown Record ................................................................................................ 316 Structure-protocol Termination Record..................................................................... 317
vii
Contents
MVS and VOS3 Tuning With the HSI System Parameter Block ........................... 318 MVS Tuning With I/O Mode Options ....................................................................... 319 VM Performance Measurement ................................................................................. 320 VM Tuning With Operator Commands .................................................................... 321 SET QDROP OFF .......................................................................................................... 322 SET QDROP OFF USERS ............................................................................................ 323 SET FAVOR ................................................................................................................... 324 LOCK PAGE .................................................................................................................. 325 SET RESERVE TDP ...................................................................................................... 326 Other VM Tuning Options .......................................................................................... 327 Channel Processor Device and Channel Error Logging ......................................... 329
Chapter 4: Security Features Under MVS and VOS3 Hardware Security Functions .................................................................................. 41 Software Security Functions..................................................................................... 41 Sending a Request ..................................................................................................... 41 Validity Checking When Returning a Response................................................... 42 Security Features Under VM ........................................................................................ 43 Introduction................................................................................................................ 43 Security Process ......................................................................................................... 43 User Logon Exit Interface............................................................................................... 44 Introduction................................................................................................................ 44 TDPLGUX Operation ............................................................................................... 44 Customizing TDPLGUX .......................................................................................... 45 Installing a Customized TDPLGUX ....................................................................... 46 User Security Interface.................................................................................................... 48 Introduction................................................................................................................ 48 TDPUSEC Operation ................................................................................................ 48 Customizing the TDPUSEC .................................................................................... 48 Installing a Customized TDPUSEC ..................................................................... 410 User Address Space Exit .............................................................................................. 411 Introduction.............................................................................................................. 411 TDPUAX Operation ............................................................................................... 411 Customizing TDPUAX .......................................................................................... 412 Installing a Customized TDPUAX ....................................................................... 413 External Security Manager Interface .......................................................................... 414 Introduction.............................................................................................................. 414 Security Logon Operation ...................................................................................... 414 Using Security Logon With TDPLGUX................................................................ 415 Bypassing Security Logon ...................................................................................... 416 Enabling/Disabling Security Logon ..................................................................... 416
viii
Contents
Using Security Logon With Session Pools ........................................................... 416 Using Security Logon With The Validated Logon Function............................. 416 Security Logon Setup Procedure........................................................................... 417
Chapter 5: TDP Operation Starting a TDP Under MVS or VOS3 ........................................................................... 52 Starting a TDP Under VM ............................................................................................. 53 Initializing a TDP............................................................................................................. 54 Introduction................................................................................................................ 54 Entering Initialization Commands From TDPPARM ......................................... 54 TDPPARM for MVS and VOS3 ............................................................................... 54 TDPPARM for VM/CMS ......................................................................................... 55 Creating Your Own TDPPARM ............................................................................. 55 TDP Internal Sessions for Two Phase Commit .................................................... 55 Entering TDP Commands .............................................................................................. 57 Entering TDP Commands on MVS and VOS3 ........................................................... 58 Introduction................................................................................................................ 58 Entering TDP Commands from the MVS or VOS3 Console ............................... 58 Entering TDP Commands From MVS/TSO or VOS3/TSS................................. 58 Using a TSO CALL Command ................................................................................ 58 Using the DBCCMD CLIST...................................................................................... 59 Invoking DBCCMD From a Program..................................................................... 59 DBCCMD Return Codes......................................................................................... 510 Viewing Command Responses.............................................................................. 510 Entering TDP Commands on VM .............................................................................. 511 Introduction.............................................................................................................. 511 Entering TDP Commands from the VM Console ............................................... 511 Entering TDP Commands From VM/CMS ......................................................... 511 Viewing Command Responses.............................................................................. 512 Using the TDP Communication Character ......................................................... 512 Entering TDP Commands from CLIv2 Applications .............................................. 514 Types of TDP Command Responses ......................................................................... 515 Introduction.............................................................................................................. 515 Immediate Response Commands.......................................................................... 515 Process-Oriented Commands ................................................................................ 515 TDP Operator Message Character Set ........................................................................ 516 Shutting Down a TDP .................................................................................................. 517 Introduction.............................................................................................................. 517 Canceling a TDP Under MVS or VOS3 ................................................................ 517 Regulating Authority to Issue TDP Commands....................................................... 518 Introduction.............................................................................................................. 518
ix
Contents
Levels of Command Issuing Authority ............................................................... 518 AUTHORIZ Command ......................................................................................... 518 User Validation ....................................................................................................... 518
Chapter 6: TDP Commands TDP Operator Commands ............................................................................................. 62 How to Issue TDP Operator Commands ............................................................... 62 TDP Operator Command Descriptions.................................................................. 62 ADD CELLS/XMSCELLS ............................................................................................. 67 ATTACH IFP ................................................................................................................... 69 AUTHORIZ ................................................................................................................... 611 COMMENT .................................................................................................................... 613 COMMIT ........................................................................................................................ 614 DETACH IFP ................................................................................................................. 616 DISABLE IRF ................................................................................................................. 617 DISABLE LGUX ............................................................................................................ 618 DISABLE LOGONS ...................................................................................................... 619 DISABLE POOL ............................................................................................................ 620 DISABLE SECLOGON.................................................................................................. 621 DISABLE SESSION DETAIL........................................................................................ 622 DISABLE SESSION RESERVE..................................................................................... 623 DISABLE SESSION STATUS ....................................................................................... 624 DISABLE SMF ............................................................................................................... 625 DISABLE TDPSTATS.................................................................................................... 627 DISABLE TEST .............................................................................................................. 628 DISABLE TIME ............................................................................................................. 629 DISABLE TMON .......................................................................................................... 630 DISABLE TRAP ............................................................................................................. 631 DISABLE UAX .............................................................................................................. 632 DISABLE USEC ............................................................................................................. 633 DISPLAY CCU ............................................................................................................... 634 DISPLAY CELLS ........................................................................................................... 635 DISPLAY CHECKSUM ................................................................................................ 638 DISPLAY CP .................................................................................................................. 639 DISPLAY IFP ................................................................................................................. 645 DISPLAY INDOUBT .................................................................................................... 647 DISPLAY JOB ................................................................................................................ 649 DISPLAY MODULE...................................................................................................... 651 DISPLAY POOL ............................................................................................................ 652 DISPLAY QUEUES ...................................................................................................... 654 DISPLAY SERVER......................................................................................................... 655
Contents
DISPLAY SESSIONS .................................................................................................... 657 DISPLAY SMF ............................................................................................................... 661 DISPLAY SP .................................................................................................................. 662 DISPLAY STORAGE..................................................................................................... 665 DISPLAY TDP ............................................................................................................... 666 DISPLAY TDPSTATS.................................................................................................... 669 ENABLE IRF ................................................................................................................. 670 ENABLE LGUX ............................................................................................................ 671 ENABLE LOGONS ...................................................................................................... 672 ENABLE POOL ............................................................................................................. 673 ENABLE SECLOGON .................................................................................................. 674 ENABLE SESSION DETAIL ........................................................................................ 676 ENABLE SESSION RESERVE .................................................................................... 677 ENABLE SESSION STATUS........................................................................................ 678 ENABLE SMF ................................................................................................................ 679 ENABLE TDPSTATS .................................................................................................... 681 ENABLE TEST .............................................................................................................. 683 ENABLE TIME .............................................................................................................. 684 ENABLE TMON ........................................................................................................... 685 ENABLE TRAP .............................................................................................................. 686 ENABLE UAX ............................................................................................................... 688 ENABLE USEC ............................................................................................................. 689 LOGOFF ......................................................................................................................... 690 LOGOFF POOL ............................................................................................................ 692 MODIFY POOL ............................................................................................................ 694 MODIFY SECLOGON .................................................................................................. 695 ROLLBACK ................................................................................................................... 696 RUN ................................................................................................................................ 698 SET CHARSET .............................................................................................................. 699 SET CHECKSUM......................................................................................................... 6101 SET COMCHAR ......................................................................................................... 6102 SET MAXSESS ............................................................................................................. 6103 SET STORAGE ............................................................................................................. 6104 SET USERCS................................................................................................................. 6105 SET USERID ................................................................................................................ 6107 SHUTDOWN .............................................................................................................. 6109 START IFP ................................................................................................................... 6111 START POOL .............................................................................................................. 6113 STOP IFP ...................................................................................................................... 6121 STOP POOL ................................................................................................................. 6123 TDP INITIAL Commands .......................................................................................... 6124 INITIAL CCU............................................................................................................... 6126
xi
Contents
INITIAL DLYTIME .................................................................................................... 6127 INITIAL IACMODE ................................................................................................... 6128 INITIAL IOBUFS ........................................................................................................ 6130 INITIAL IOMODE ...................................................................................................... 6131 INITIAL JOBWAIT ..................................................................................................... 6133 INITIAL LSQA ............................................................................................................ 6134 INITIAL MSGPREF .................................................................................................... 6135 INITIAL OSSISUFX .................................................................................................... 6136 INITIAL PCSUFX ....................................................................................................... 6137 INITIAL TRUNCRSP .................................................................................................. 6138
Appendix A: Channel Processor Device and Channel Error Log Sample EREP Record ..................................................................................................... A2 Record Format................................................................................................................. A3 For CPs That Require the CCU Operand in the START Command ................. A3 For CPs That Do Not Require the CCU Operand in the START Command ... A4 Sense Data........................................................................................................................ A6 For CPs That Require the CCU Operand in the START Command ................. A6 For CPs That Do Not Require the CCU Operand in the START Command ... A6
Appendix B: Parcel Flavors What is a Parcel?..............................................................................................................B2 Parcel Structure ..........................................................................................................B2 Flavor Field.................................................................................................................B3 Length Field................................................................................................................B4 Parcel Body .................................................................................................................B5 Parcel Types .....................................................................................................................B6 Request Parcels: Overview.............................................................................................B7 Response Parcels: Overview ..........................................................................................B9 Parcel Descriptions........................................................................................................B12 Abort................................................................................................................................B13 Abrt2PC...........................................................................................................................B14 Cancel ..............................................................................................................................B15 Cmmt2PC........................................................................................................................B16 FMRunStartup ...............................................................................................................B17 IVRunStartup .................................................................................................................B18 KeepRespond .................................................................................................................B19 ExtendedKeepRespond ................................................................................................B20 ExtendedRespond .........................................................................................................B21
xii
Contents
Logoff ..............................................................................................................................B22 Logon...............................................................................................................................B23 Multi-TSR .......................................................................................................................B25 Options............................................................................................................................B26 Respond ..........................................................................................................................B28 Rewind ............................................................................................................................B29 Run ..................................................................................................................................B30 RunStartup .....................................................................................................................B31 SessionOptions...............................................................................................................B32 UserNameRequest.........................................................................................................B34 UserNameResponse ......................................................................................................B35 VoteRequest ...................................................................................................................B36 VoteTerm ........................................................................................................................B38 XIVRunStartup ..............................................................................................................B39
Appendix C: How to Read the Syntax Diagrams Notation Conventions.............................................................................................. C1 Paths ........................................................................................................................... C2 Required Items.......................................................................................................... C3 Optional Items........................................................................................................... C3 Abbreviations............................................................................................................ C3 Loops .......................................................................................................................... C4 Excerpts...................................................................................................................... C4
Appendix D: Overview of SET USERCS Defining a Character Set................................................................................................ D2 Directives ......................................................................................................................... D3 Syntax ......................................................................................................................... D4 Usage Notes............................................................................................................... D4 Example...................................................................................................................... D4 Syntax ......................................................................................................................... D5 Usage .......................................................................................................................... D5 Example...................................................................................................................... D5 Syntax ......................................................................................................................... D5 Usage Notes............................................................................................................... D5 Example...................................................................................................................... D5 Syntax ......................................................................................................................... D6 Usage Notes............................................................................................................... D6 Example...................................................................................................................... D7
xiii
Contents
Syntax ......................................................................................................................... D7 Usage Notes............................................................................................................... D7 Example...................................................................................................................... D8 Syntax ......................................................................................................................... D9 Usage Notes............................................................................................................... D9 Example.................................................................................................................... D10
Index.......................................................................................................................... Index1
xiv
List of Figures
Figure 1-1 Figure 1-2 Figure 1-3 Figure 1-4 Figure 1-5 Figure 1-6 Figure 1-7 Figure A-1 The Teradata Server Serves Various Clients....................................... 12 Communicating With TDP Using SVC............................................... 14 Communicating With TDP Using PC ................................................. 15 Communicating With TDP Using IUCV ............................................ 15 Returning a Response Using SVC ....................................................... 17 Returning a Response Using PC.......................................................... 17 Returning a Response Using IUCV ..................................................... 18 Sample EREP Record............................................................................ A2
xv
List of Figures
xvi
List of Tables
Table 6-1 Table 6-2 Table B-1 Table B-2 Table B-3 Table D-1 Table D-2 TDP Operator Commands.................................................................... 62 TDP INITIAL Commands ................................................................ 6124 Parcel Flavors..........................................................................................B3 Request Parcels Flavor Definitions......................................................B7 Response Parcels Flavor Definitions ...................................................B9 Directives................................................................................................ D3 Syntax Definitions................................................................................. D4
xvii
List of Tables
xviii
Chapter 1:
Client Software Overview

This chapter presents an overview of the client software, which is the portion of the Teradata Relational Database Management System (Teradata RDBMS) that is installed on an IBM- or Hitachi-compatible mainframe computer under the MVS, VM or VOS3 operating systems. The client software provides the interface that your applications use to communicate with the Teradata server. The intention of this chapter to provide you with the vocabulary and background necessary to understand the information in subsequent chapters. This chapter describes the following: Communication of a users Teradata SQL request to the Teradata server for processing, and return of a result Sessions and requests Call-Level Interface (CLI) Teradata Director Program (TDP) Mechanisms for controlling traffic flow
The user-to-TDP communication modes are described in Chapter 2.
Installing Client Software

For details on installing the client software, refer to the appropriate book for your Teradata server: Teradata Client for MVS Installation Guide Teradata Client for VM Installation Guide
Teradata Server
The Teradata server is the database server for a variety of clients, which can be attached either through a mainframe channel or over a LAN. The clients communicate with the Teradata server to perform queries on the data that it holds. This book describes the software interface for channel-attached clients.
Client Software
Client software is also known as the Host System Communication Interface (HSCI) and consists of the following: Call-Level Interface (CLI) Teradata Director Program (TDP)
11
Chapter 1: Client Software Overview
User-to-TDP Communication Modes: SVC (MVS or VOS3 only) Program Call (PC) (MVS only) Inter-User Communication Vehicle (IUCV) (VM only)
Figure 1-1 shows the general concept of the Teradata server and some of the clients that can be attached to it. It also shows which HSCI modules are installed on various clients.
Figure 1-1 The Teradata Server Serves Various Clients
Teradata Server LAN-Attached Clients Mainframe Channel
LAN
MVS Client: - MVS Operating System - CLIv1, CLIv2 - TDP - UTC (SVC or PC)
VM Client: - VM Operating System - CLIv1, CLIv2 - TDP - UTC (IUCV)
FZAPB075
12
Chapter 1: Client Software Overview Communicating with the Teradata Server
Communicating with the Teradata Server

The client software allows you to communicate with the Teradata server through a session on the mainframe client. Within a session, a user communicates with the Teradata server through an application such as BTEQ (supplied with the Teradata RDBMS) or through a user application program written in COBOL, Assembler, PL/I, Pascal, FORTRAN, or another language available on the client. The communication process is as follows:
Stage Process
The application load module calls CLI routines, which format an output buffer, as shown in Figure 1-2, Figure 1-3, and Figure 1-4. CLI routines communicate with the routines that comprise the appropriate user-to-TDP communication mode to pass the request to TDP. The following information is passed: Request type Input and output buffer addresses and sizes TDP associated with the request Session and request numbers associated with the request
TDP transforms the header and parcels into one or more channel blocks and sends the channel blocks over the block multiplexer channel to the Teradata server.
13
Chapter 1: Client Software Overview Communicating with the Teradata Server Figure 1-2 Communicating With TDP Using SVC
Common Storage
Request Parcels User Address Space Output Buffer TDP Address Space Request Parcels Other Request Other Request
Application
Input Buffer Channel Block
CLI
Routines
Teradata Server
FZAPB076
14
Chapter 1: Client Software Overview Communicating with the Teradata Server Figure 1-3 Communicating With TDP Using PC
User Address Space Output Buffer
TDP Address Space Request Parcels Other Request Other Request
Application
CLI
Routines
Teradata Server
FZAPB077
Figure 1-4 Communicating With TDP Using IUCV
User Virtual Machine Output Buffer
TDP Virtual Machine Request Parcels Other Request Other Request
Application
CLI
Routines
Teradata Server
FZAPB078
15
Chapter 1: Client Software Overview How TDP Returns Results
How TDP Returns Results

When a result is available from the Teradata server, the following events occur:
Stage Process
The Teradata server creates a success parcel or failure parcel to notify the application of the success or failure of the request. The success parcel contains statistics about the result (for example, the number of records found).
The success parcel and, if appropriate, the first parcels of result data (for example, the rows that are to be returned as the result of a SELECT request) are packaged into a response message. The response message and a message header are sent within a channel block over the block multiplexer channel to TDP. TDP reassembles the channel block into a message, extracts the response parcels from the message, and moves the parcels to the input buffer in the users address space using the appropriate user-to-TDP communication mode. (See Figure 1-5, Figure 1-6, and Figure 1-7.). If the application program does not receive all the response parcels needed to satisfy its request in the first response message from the Teradata server, the application requests additional response parcels by sending a continue request. The respond parcel in the continue request contains information for the Teradata server on the maximum number of bytes to transmit in the response message.
3 4
Upon receiving a continue request, the Teradata server sends the next set of response parcels to TDP.
16
Chapter 1: Client Software Overview How TDP Returns Results Figure 1-5 Returning a Response Using SVC
Common Storage
Application
TDP Address Space Input Buffer Request Parcel
CLI
Routines
FZAPB079
Figure 1-6 Returning a Response Using PC
Application
TDP Address Space Input Buffer Request Parcel
CLI
Routines
FZAPB080
17
Chapter 1: Client Software Overview How TDP Returns Results Figure 1-7 Returning a Response Using IUCV
User Virtual Machine Output Buffer
Application
TDP Virtual Machine Input Buffer Request Parcel
CLI
Routines
FZAPB081
18
Chapter 1: Client Software Overview Sessions
Sessions
Definition
A session is a logical connection between a user, communicating through BTEQ or another application program, and the Teradata server. A session permits a user to send one request to and receive one response from the Teradata server at a time. That is, a session can have only one request outstanding at any time. A user may be communicating through one or more active sessions concurrently.
Sessions Are Logged On and Off

A session is explicitly logged on and off. The session is established when the Teradata server accepts the user name and password of the user. When a session is logged off, the user name and password are discarded and no additional Teradata SQL statements are accepted from that session.
Session Identification
Each session is identified to the client and to the Teradata server by a session number and a logical host number. A session number uniquely identifies the work stream of a session for a given TDP. A logical host number uniquely identifies each TDP within a server.
19
Chapter 1: Client Software Overview Session Pools
Session Pools
Introduction
A session pool is a number of sessions that are logged on to the Teradata server as a unit using the same logon string. Unlike ordinary sessions, pool sessions are automatically assigned to applications that initiate a logon using the same logon string as that established for the pool.
Logging Pool Sessions on to the Teradata Server

The sessions in a pool are logged on to the Teradata server once using the START POOL operator command (for details see Chapter 6: TDP Commands) and remain logged on until they are explicitly logged off by the STOP POOL (or STOP POOL and LOGOFF POOL) operator commands. When a pool is first established, all pool sessions are not in use. When an application sends a logon request whose logon string matches that of the session pool, as described below, the application is assigned an available session from the pool. This results in a quick logon, because the applications logon request does not have to be sent to the Teradata server. The session assigned to the application is marked in-use and cannot be reassigned to another application until the current application logs off. The logoff returns the session to the pool, where it becomes available for use by another application.
Multiple Simultaneous Session Pools

Many session pools may exist at the same time, each having a unique logon string. The logon string contains a logon id, password, and, optionally, an account identifier. Several pools may be established using the same logon id and password, but with different accounting information. The same logon string may be used to establish a number of pools, each devoted exclusively to the applications that belong to a different job. For example, a logon string might be used to establish one session pool for a CICS job, another pool for another job. Thus, each pool would be considered to have specific job or session attributes.
1 10
When an application logs on, the following verification process occurs:

Stage Process
The logon string of the application is checked to determine whether it matches that of any established pool.
IF TDP . . . THEN it . . .
detects a matching logon string
checks the pool to determine whether there is are specific job or session attributes.
IF there is . . . THEN the . . .
are specific job or session attributes that match that of the application are no specific job or session attributes
application is assigned a session from the pool if there is a session available. search continues to determine whether any other existing pool has both the logon string and specific job or session attributes that match the application.
If no pool is found, and if there is an available pool, then TDP assigns a session from the pool with the matching logon string and no specific job or session attributes. does not detect a matching logon string TDP sends the logon for the application to the Teradata server.
1 11

Stage Process
TDP assigns a session pool.

IF a matching pool is found and . . .
THEN TDP . . .
there is no session available in the pool to satisfy the applications logon request sessions are available it has a specific job or session attributes and no available sessions or the pool is disabled
rejects the request with an error message.
assigns the application a session. rejects a logon request with a matching logon string and job.
This is true even if there exists another pool with the same logon string and available sessions, but no specific job or session attributes.
Session Logoff Process

The following process occurs when the application logs off the session.
Stage Process
1 2
The Teradata server is not notified that the session has been logged off. TDP removes the session from the in-use category and returns it to the notin-use category. If a STOP POOL command (or a MODIFY POOL command to reduce the number of pool sessions) is entered while the session is in use, the session is logged off of the Teradata server. If the database to be used by the application differs from the database associated with the logon string of the pool, the application must either change the default or fully qualify all table references.
If an application either abends or a session logs off from a session pool, the system does a clean up as follows: Deletes all spool files Releases all locks Reestablishes the default database
1 12
Chapter 1: Client Software Overview Requests
Requests
Introduction
The work stream of a session consists of a series of requests, identified by unique request numbers. There are two kinds of requests: Start request, which contains one or more Teradata SQL statements and associated parameters Continue request, which asks for more response data from the Teradata server for a previous start request
A start request contains request and respond parcels. A continue request contains a respond or a cancel parcel. Each request is completed by receipt of a response. Once a request is completed, the user is free to issue another request. A request either succeeds or fails. If any part of a data definition or data manipulation request fails, the request is backed out and no change is made to the database. If a SELECT request fails, no result, other than a failure response, is returned to the user.
Messages
Requests are communicated between the client and the Teradata server in the form of messages. These messages are sent to logical addresses, or mailboxes, in the client or the Teradata server through a Message Subsystem. Because the recipient of a message typically returns a response to the originator by return mail, communication normally takes the form of message pairs. The Message Subsystem buffers and queues the messages that are passed over the channel between the client and the Teradata server. Each message passed over the interface during a session contains a header that identifies the session and request numbers.
Parcels
A message contains one or more parcels. A parcel may contain Teradata SQL statements, processing results, and so on. As described previously, a request starts with a request parcel containing one or more Teradata SQL statements and a respond parcel specifying the maximum number of bytes the Teradata server can use to return in the first response message. Once TDP receives result data from the Teradata server, TDP converts the data into parcels and returns the parcels to the originating application.
1 13
Chapter 1: Client Software Overview Call-Level Interface
Call-Level Interface
Introduction
An application on the client communicates with the Teradata server through the Teradata library of Call-Level Interface (CLI) routines. By using CLI routines, an application avoids manipulating underlying parcel and message structures. CLI routines provide advanced functions used at the parcel level. CLI routines take the form of entry points that may be called by BTEQ and other applications.
How the Teradata Preprocessor Uses CLI

When a COBOL application program is processed by the Teradata COBOL Preprocessor, or a PL/I program is processed by the Teradata PL/I Preprocessor, the preprocessor adds calls to CLI service routines. After the program is compiled, it is link-edited with the service routines, which convert the calls into Teradata SQL request messages for Teradata server databases.
How Other Languages Can Use CLI

Applications written in Assembler, FORTRAN, C, and other languages that have a CALL statement and use standard OS linkage conventions (including COBOL and PL/I) may call CLI routines directly through CLI entry points. After the program is compiled, the called routines are link-edited or dynamically called to create a load module.
More Information About CLI

For complete information about CLI, see: Teradata Call-Level Interface Version1 for Channel-Attached Systems Teradata Call-Level Interface Version2 for Channel-Attached Systems
For information about the COBOL preprocessor and the PL/I preprocessor, refer to Teradata Application Programming With Embedded SQL for C, COBOL, and PL/I.
1 14
Chapter 1: Client Software Overview Teradata Director Program
Teradata Director Program

Introduction
The Teradata Director Program (TDP) resides in the client. TDP provides a high-performance interface for messages communicated between the client and the Teradata server. It provides the data communications component of the Teradata RDBMS. Every channel-attached client system connected to a Teradata server has at least one TDP associated with it. Therefore, a client system connected to more than one Teradata server has more than one TDP running. Each TDP is identified by a tdpid. On MVS and VOS3, a tdpid corresponds to a Subsystem id, and consists of four characters, the first three of which are 'TDP', and a fourth that uniquely differentiates TDPs on that system. On VM, the tdpid is the userid of the virtual machine in which that TDP is executing, and is usually named in the same manner as the MVS tdpid.
Session Logon Source and Messages

When a session is established, information is added to the LogonSource column in various views (such as dbc.LogOnOff and dbc.SessionInfo) by the Teradata RDBMS. If the application uses Connect mode to establish the session, TDP provides system-dependent information in the LogonSource column, consisting of the following series of eight-character values, each left-justified and padded on the right with blanks: Operating System Name (MVS or VM) TDPid Jobname (MVS jobname or VM Userid) Environment Name (blank for VM; either BATCH, TSO, IMS, or CICS for MVS) Userid from Security Product (blank if VM or if no such product) Group from Security Product (blank if VM or if no such product) Program Name (blank if VM) Coordinator name (blank if not for CICS or IMS) Transaction identifier (blank if not for CICS or IMS) Terminal identifier (blank if not for CICS) User/operator identifier (blank if not for CICS) Jobid (MVS Job ID or VM userid) A format identifier that may be used to parse the previous information.
If the information ends with the four characters ' LSS' (note the blank), then the format identifier and Jobid values are present.
1 15
Chapter 1: Client Software Overview Teradata Director Program
The first two characters of the format identifier indicate the number of values present before the Jobid (currently either 07 or 11). The next two characters indicate the version of format identifier, currently 01. The format identifier, while cryptic, allows new information to be added after what were originally trailing optional values. If the format identifier is not present, then Jobid is not present, and only the first seven or eleven fields will be present.
Parcels and Messages

TDP generally handles messages, not parcels. Although it generates certain parcels itself and interprets responses to those parcels, TDP does not look at or modify parcels passed to or from an application program.
Channel Processor and Session Processor Definitions

While the Teradata server is a complex system, two aspects are of primary concern to TDP: A Channel Processor (CP) is a pair of devices on the server that are attached to a mainframe channel and used by TDP to communicate with the server. Many CPs may be used for communication between a server and a TDP. The implementation of a CP may vary on different servers, but the behavior of all CPs is the same. For example, on a DBC/1012, an IFP implements a CP, while on a System 3600, an MCCA on an AP implements a CP. The devices composing a CP are known to the operating system. Because the original implementation of an IFP embodied the functions of a CP, the pair of devices were referred to as an IFP. For compatibility, this usage continues, especially in the existing TDP command syntax. A Session Processor (SP) is the component on the server that provides for the allocation of sessions, which is the logical connection between an application and the server. Each SP allows a fixed number of sessions, but many SPs may be used by a TDP. The implementation of an SP may vary on different servers, but the behavior of all SPs is the same. For example, on a DBC/1012, an IFP implements an SP, while on a System 3600, a PE implements an SP. No aspect of an SP is known to the client operating system. As mentioned above, compatibility considerations require continued use of the term IFP, but only as an equivalent to CP. The SP aspects of the original IFP are not implied by this use of IFP.
1 16
Chapter 1: Client Software Overview Resource Allocation Control
Resource Allocation Control

Introduction
The Teradata server resources are managed so as to maintain efficient operation of the system while providing equitable service to many clients and users. In keeping with this goal, one of the following priority-level prefixes may be attached to a user account string in a CREATE USER or MODIFY USER statement: $L (Priority 0, low) $M (Priority 2, mediumthis is the default if no priority is assigned) $H (Priority 4, high) $R (Priority 6, rush)
A session is assigned the priority level of the user who is logging on.
Why Schedule Session Priorities?

The specific intent of this priority scheduling policy is to ensure that: Any session that is assigned a given priority receives the same portion of Teradata server resources as any other session having the same priority. Any session that is assigned a given priority receives a larger portion of Teradata server resources as a session having lower priority.
1 17
Chapter 1: Client Software Overview Session Protocol
Session Protocol
Introduction
Session protocol controls the rate at which data is transferred between an interactive user or application program and the Teradata server.
Characteristics of the Session Protocol

The protocol has the following characteristics: It operates in request-response mode. For each user request, TDP sends a single message to the Teradata server, and the Teradata server returns a single response message to TDP. (However, an application may be logged on to more than one session at a time.) It is half duplex. The user cannot issue a new request for a session (other than an abort for the current request) until the Teradata server has processed the previous request and returned a response.
Because the user can specify the maximum amount of result data to be returned in a response message, the user can control the amount of buffer space needed in the users address space.
1 18
Chapter 1: Client Software Overview Using an Externally Coordinated Commit
Using an Externally Coordinated Commit

Introduction
It is possible for a single application to update multiple databases. For example, in a transfer of funds, an application could withdraw money from a bank account on one database and deposit it into another account on a different database. As an option, an application can use an externally coordinated commit process to ensure that updates are applied consistently to all affected databases. One of the methods used to accomplish this process is the two-phase commit (2PC) protocol, supported by the Teradata RDBMS.
Two-Phase Commit Protocol

With the 2PC protocol, an application can update multiple databases in the same logical unit of work, with a coordinator such as IMS or CICS controlling the process. The coordinator uses the 2PC protocol to ensure that all the updates for all the participants in the logical unit of work either commit or roll back. Within a Teradata server session that is using the 2PC protocol, there is an instant when it is in an in-doubt state, awaiting final instructions from the coordinator on whether to commit or roll back the updates. If a failure in TDP or another part of the system occurs during this in-doubt period, the Teradata server cannot unilaterally decide to commit or roll back the updates. In the event that automatic in-doubt resolution is not possible because of an extended coordinator outage, manual resolution of the in-doubt sessions may be necessary. This is because these in-doubt sessions may hold locks on data base objects that block the progress of other applications that are trying to access those objects. Warning Manual resolution of in-doubt sessions must be done with care. Incorrect manual in-doubt resolution causes a loss of data integrity between the participating databases.
In-Doubt Session Resolution

If manual in-doubt resolution is necessary, you can use either of the following: TDP commands DISPLAY INDOUBT, COMMIT, and ROLLBACK. For details see Chapter 6: TDP Commands. the TPCCONS utility on the RDBMS console. For details see: Teradata RDBMS for UNIX Utilities Reference Teradata DBS Utilities Reference Manual
1 19
Chapter 1: Client Software Overview Using an Externally Coordinated Commit
The following TDP commands are affected and/or used by the 2PC protocol: AUTHORIZ COMMIT DISABLE IRF DISPLAY INDOUBT ENABLE IRF ROLLBACK INITIAL USERID
1 20
Chapter 2:
Communications Routines
This chapter discusses the routines that enable an application to communicate with the Teradata Director Program (TDP) and the Teradata server. The discussion is provided as background information for the system programmer, as well as to assist you and NCR support personnel in problem determination.
Operating Systems Supported

TDP operates in any of the subject operating system environments. The client software provides the following communication routines that serve both environments: Call-Level Interface (CLI) routines User-to-TDP Communication (UTC) routines
CLI routines provide a logical, consistent protocol for communicating requests to TDP and the Teradata server and for receiving the responses. CLI routines and TDP communicate using the UTC routines.
21
Chapter 2: Communications Routines CLI Routines
CLI Routines
Introduction
CLI routines may logically be compared with IBM input/output routines. CLI routines provide functions for the following: Invoking logon services Managing buffers Sending requests to the Teradata server Receiving responses from the Teradata server Aborting requests Providing logoff services
How CLI Routines Are Used

CLI routines are designed so they can be directly called either from high-level languages (for example, COBOL, PL/I, and FORTRAN) or from assembler language routines. Each CLI routine must be called in the proper order using some common parameters. Depending on function, a routine also may expect a number of additional parameters.
The CLI Library

The CLI library contains all routines, including the proper memory and event management subroutines. The routines use standard operating system services (for example, GETMAIN, FREEMAIN, and WAIT). CLI routines may either be statically linked with an object module or invoked dynamically at execution time. Invoking the routines dynamically may be more efficient than linking them for the following reasons: It is much simpler to update routines in an application (for example, to fix an error, to enhance function, or to provide new services). In an MVS or VOS3 environment, the user need only replace old routines in the MVS or VOS3 LPA, rather than re-link all modules using the routines. In a VM/CMS environment, the user need only replace old routines in the appropriate CMS library. Overhead for dynamically loaded routines is encountered only once for any module actually loaded by each active session. The address of a loaded module is retained in CLI control blocks. If the Teradata server is used by a number of jobs or tasks, the routines may be placed in the MVS or VOS3 LPA, thereby reducing the overall paging rates and sizes of modules.
22
Chapter 2: Communications Routines CLI Routines
CLI routines use information such as the default tdpid and other settings that are contained in the system parameter blocks, HSISPB and HSHSPB. Whether CLI routines are dynamically invoked or statically linked, the HSISPB and HSHSPB modules must be available at execution time.
For More Information

For detailed information about each CLI routine, its parameters, returns, and error conditions, refer to the following manuals: Teradata Call-Level Interface Version1 for Channel-Attached Systems Teradata Call-Level Interface Version2 for Channel-Attached Systems
23
Chapter 2: Communications Routines UTC Routines
UTC Routines
Introduction
The User-to-TDP Communication (UTC) routines physically manage the communication of requests between TDP and BTEQ, or another application. The UTC routines consist of the following: Host System Interface to TDP (HSIT) - all clients Host System Interface Utility (HSIU) - MVS and VOS3 only
Routines Under MVS and VOS3

In the MVS or VOS3 environment, the UTC routines consist of the HSIT and the HSIU. The HSIU routines reside in common storage.
Routines Under VM/CMS

In the VM environment, the UTC routines include the HSIT only, and are packaged together as a nucleus extension.
24
Chapter 2: Communications Routines HSIT Routines
HSIT Routines
Introduction
CLI invokes the Host System Interface to TDP (HSIT) routines to accomplish the following: Initiate communication with TDP and the Teradata server Pass requests for the Teradata server to TDP Build session control tables and status blocks
The topics that follow describe the HSIT routines.
Request Initiation
An application initiates each request by passing the HSI control block (HSICB) to the HSIT. The HSICB contains the following information: Type of request Input and output buffer addresses and sizes TDP associated with the request Session and request numbers associated with the request, if any
Valid Request Types

The following requests can be made: A new logon An existing session A logoff for a particular session A logoff for all sessions under the current task A logoff for all sessions within the address space
The HSIT rejects a request for any other function (for example, a request for a nonexistent session) and returns an appropriate error code. Each valid request is passed to TDP and, if necessary, to the Teradata server.
Request Completion
The HSIT initializes an OS event control block (ECB) in the callers HSICB. Posting of this ECB within the HSICB signals the completion of the request. All requests are asynchronous. That is, if session A sends a request before session B sends a request, there is no guarantee that session A will receive a response before session B receives a response. The HSIT, TDP, and the Teradata server enforce a protocol that requires a session to receive a response to an outstanding request before it can enter a
25
Chapter 2: Communications Routines HSIT Routines
subsequent request. The only exceptions to this rule are the immediate functions ABORT, LOGOFF, and enable/disable logon requests, which may be entered at any time. If the request is successful, the ECB is posted with an X40000000. Other return codes and error codes are found in: Teradata RDBMS for UNIX Messages Reference Teradata DBS Messages Reference Manual
Session Status
The status of a session can be one of the following: Not Logged On: After logoff and before logon Idle: After logon and before the first request is initiated After a response to a request is returned and before a subsequent request is initiated Response Pending: After a request is issued and before a response is returned
26
Chapter 2: Communications Routines HSIU Routines
HSIU Routines
Introduction
The Host System Interface Utility (HSIU) routines are included in the UTC routines for the MVS or VOS3 environment only. The HSIU does not apply to the VM environment. The HSIU consists of subroutines that reside in common storage and are used by the HSIT, TDP, and interfaces to the OS/MVS JES management services. Accordingly, the module must be available to the Teradata RDBMS software modules in the LPA. The HSIU contains routines for managing the following: Global memory management (SVC only) Inter-address-space services Address space termination End-of-memory cleanup Operator command interface Timer/re-drive routine SRB services
The topics that follow describe the HSIU routines.
Global Memory Management (SVC Mode)

The global memory management routine within the HSIU provides a common allocation/de-allocation routine for the Common Storage Area (CSA).This is the only available option for VOS3 clients. The CSA is used by the SVC communication technique, described in this chapter. The amount of CSA required by TDP is 130 hex bytes plus an additional 800 hex bytes if IOSDRIVR is used. Every request for global memory (by TDP, HSIT, or other functions within the HSIU itself) is processed by this routine. All requests for global memory come through the CSA. Global memory is obtained in protection key 7, and is fetch-protected only if it contains data. Thus, non-privileged programs may examine the chain of high-storage control blocks. Global memory for data storage is acquired in blocks large enough to accommodate the transfer of large blocks of data without running out of storage. The block size selected depends on the direction of the request.
Inter Address Space Services

The Inter-Address-Space routines of the HSIU consist of the cross memory queueing routine and the IAS POST routine. Using standard multiprocessing
27
queueing concepts, the cross memory queueing routine places a completed request on a queue for TDP to process. This option is not available for VOS3 clients.
Address Space Termination

When a task ends and no tasks in other sessions are active in the application address space, the normal JES interface routine is invoked to terminate the address space. The routine issues the logoff all tasks function to TDP and cleans up (unchains and deletes) protected control blocks for any session opened by the task just ended. If no sessions were opened in the application address space, the routine exits. If sessions were opened, the routine deletes session status control blocks in both application and TDP address spaces. The master chain pointer in the application address space is reset to indicate that there are no sessions in this address space.
End of Memory Cleanup

When an address space is terminated, the end-of-memory cleanup function is invoked. This function does the following: Issues logoff all address spaces and enable logon requests to TDP. (Enable logons is issued to ensure that a subsequent job in the same address space can issue LOGON requests without needing special-case programming to enable logons.) Indicates to TDP that there are no active sessions in the terminated address space.
Operator Command Interface

During SVC 34 (MGCR) processing of an operator command request for a TDP, the JES interface passes control to the HSIU operator command interface. This routine, invoked for every active or previously started TDP, examines the text of the command and the state of TDP to which the command is directed. Processing by the operator command interface depends on the condition of TDP, as follows: If TDP was or is active and the command communication character (comchar) matches the character that identifies commands directed to TDP (or the first four non-blank characters contain the tdpid), the interface routine processes the request. If not, the routine returns an error code to MVS and exits. If the operator command is for a particular TDP, the TDP Active flag is checked. If TDP is not currently active, the routine returns the unable to process error code to MVS and exits.
28
If TDP is active, the routine places the request on the queue for TDP. This process removes leading and trailing blanks, translates the command to uppercase, and generates console id and other information for use by the TDP command processor. The routine returns a this command was processed code to MVS and exits.
Job Wait Timeout Prevention

MVS provides for abnormal termination of jobs that have been in a continuous WAIT state for an installation-specified time interval. This interval is specified using the SMF Job Wait Time (SMFJWT) value. However, a job may sometimes need to wait longer for a response than the SMFJWT allows (for example, when the job is issuing lengthy or very complex Teradata SQL requests). To prevent a system 522 abnormal termination of such a job, TDP at the option of the installation schedules busy work to take place under the waiting jobs Task Control Block (TCB). When assembling the HSISPB, the installation may select this option by specifying a value for the keyword JWT (in the macro HSISPB) that is less than the installation-specified value for SMFJWT. This can also be accomplished via the INITIAL JOBWAIT command.
SRB Services
To remove an application from a waiting condition, the System Resource Block (SRB) scheduling and action routines invoke the HSIU cross memory move services to move data from CSA to the user buffer and then to issue a branch entry to POST. An SRB routine revalidates all user control blocks and data areas. The SRB routine deletes all CSA buffers and work areas and terminates without posting the user in either of the following cases: The users copy of the HSICB reflects a request or session number that is different from that of the HSICB in the CSA. The users copy of the HSICB is not valid, or has been unusually modified.
If the users copy of the HSICB is valid, the routine attempts to validate and update the input buffer using the cross memory move routine. If this is successful, the CSA buffers are deleted and the ECB in the HSICB is posted via branch-entry to POST. The HSASIB is then deleted and the SRB is terminated. If the input buffer is not valid, the CSA buffers are deleted and an abnormal return code is posted to the application. The HSASIB is then deleted and the SRB is terminated.
29
Chapter 2: Communications Routines UTC Communication Techniques
UTC Communication Techniques

Introduction
User-to-TDP communication (UTC) techniques are used for all client environments. CLI routines determine the operating system environment and make the appropriate calls to the HSIT routines. When TDP is executing in the MVS environment, either of the following two communication techniques are employed: A user SVC routine and the MVS Common Storage Area (CSA) A Program Call (PC) routine (only if the MVS system is at least SP release 1.3)
When TDP is executing in the VM/CMS environment, the communication technique used is the IBM Inter-User Communication Vehicle (IUCV). In the VOS3 environment, only the SVC is available.
MVS Communication Techniques

In the MVS environment, the HSIT uses the SVC or PC routines. Only SVC is available in the VOS3 environment. At installation time, your site chooses whether to use SVC or PC for communication between the user applications and TDP. For both SVC and PC techniques, routines that reside in common storage (LPA) are invoked by both CLI and TDP to provide utility functions needed to complete the UTC interface.
Communication Using the SVC Technique

For the SVC technique, the communication process is as follows:
Stage Process
1 2
CLI invokes the SVC. The SVC handles the initialization functions for establishing logged-on sessions with TDP and the Teradata server, and serves as the basic interface between applications and TDP. In the CSA, the HSIT creates the inter-address-space control blocks and builds protected buffers. The data to be transferred is then placed in these buffers and passed to TDP via the PC routine in the HSIU.
3 4
To validate sessions and to lower the overhead of inter-address-space functions, the HSIT also builds protected control blocks in the user address
2 10
space. These control blocks contain status information about each active session, as well as information that may be used to re-drive requests in the event of system delay or Teradata server recovery. To minimize the possibility of invalid requests, the HSIT validates all control block information before passing it to TDP. The HSIT builds user-address-space control blocks in protection key 7. The control blocks themselves are not fetch-protected, although the data buffers are. All inter-address-space control blocks and data are placed in the CSA in protection key 7. This minimizes the need to switch keys for normal access. At the same time, it maximizes access control to potentially privileged data.
Communication Using the Program Call Technique

There are two major differences between the PC and SVC techniques: PC techniques do not use the CSA, SVC techniques do. For PC, buffers and control blocks are moved directly from the address space of the user to the address space of TDP. With PC techniques, CLI invokes a non-space switch routine instead of the SVC to perform SVC functions. This is done via a program call (PC).
VM Communication Technique
The VM/CMS environment uses the IUCV communication technique. CLI establishes a nucleus extension that contains the UTC routines needed to communicate requests to TDP. After determining the operating system environment, CLI routines invoke the nucleus extension to: Build session control tables and status blocks Initiate communication with TDP and the Teradata server Pass requests for the Teradata server to TDP Establish IUCV connections Terminate IUCV connections Detect end-of-command
In addition to providing SVC and PC functions, the nucleus extension handles all IUCV interrupts presented to the user.
Job Wait Timeout for VM

The VM operating system provides for abnormal termination of jobs that have been in a continuous wait state for an installation-specified time interval. This interval can be specified via SMART. However, because a transaction using the Teradata server can run for a longer time, this interval can be overridden by specifying a value less than the timeout value for the JWT keyword in the HSISPB macro. This can also be accomplished via the INITIAL JOBWAIT command.
2 11
2 12
Chapter 3:
Performance Measurement
To evaluate Teradata server performance, you can use the optional Host System Interface (HSI) time stamps. When you use this option, the Host System Interface to TDP (HSIT) forwards time stamps from various parts of the client system. The information is returned in the CLIv2 DBCAREA. For details on DBCAREA, see Teradata Call-Level Interface (CLIv2) for Channel-Attached Systems.
DBCAREA Fields
The following DBCAREA fields may contain timing information for various portions of the HSI-to-TDP-to-Teradata server interfaces, and may be accessed using code written in Assembler or another high level language: DBCTSTMP DBCTIME1 through DBCTIME5
DBCTSTMP
DBCTSTMP contains the time-of-day clock time that is stored when a request is actually started by the HSIT. This time differs slightly from the time the HSIT is actually issued because of initialization processing.
DBCTIME
DBCTIME time stamps contain information on when the following occurred: The request was received by TDP. The request was queued to the Teradata server. The response was received from the Teradata server. The response was queued to the Host System Interface Utility (HSIU) cross memory task. The response was returned to the user input buffer.
Each of the DBCTIME fields is 4 bytes long, shifted right 20 bits. The actual elapsed time, in microseconds, spent by a request in each of the major TDP sections may be determined using the following technique:
L LM SRDL Rz,DBCTIMEx Rx,Ry,DBCTSTMP Rx,20
31
Chapter 3: Performance Measurement
SL
Rz,Ry
(delta time in 256 mics)
HSI time-stamping is initiated and controlled by setting a flag in the DBCAREA. Under normal operating conditions, time-stamping is performed only when absolutely necessary (for example, in a dump).
32
Chapter 3: Performance Measurement TDP User Transaction Collection Exit
TDP User Transaction Collection Exit

Introduction
TDP User Transaction Collection Exit (TDPUTCE) is a routine that allows the user to collect statistics about all of the requests and responses that traverse TDP. The exit can be enabled when TDP is started if the enabling command is included in the TDPPARM data set or by executing the TDP operator command ENABLE TMON.
Types of Calls Processed by TDPUTCE

TDPUTCE processes four types of calls: Initialize Request Response Terminate
The exit is initialized when TDP is initialized or when an ENABLE TMON command is executed. During initialization, TDPUTCE performs activities such as obtaining a work area and opening files.
Parameters Passed
When a request or a response call is made, the exit is passed parameters containing the following information: Input parameters to the TDPUTCE TDP information Requestor information Session or request information Time stamps Function code (request type) Request or response data Enlarged parcel usage support Character set information
A terminate call is sent to the exit at TDP termination time or when a DISABLE TMON command is executed. If the TDPUTCE fails, TDP disables the exit. The exit can be re-enabled by executing the ENABLE TMON command. For information on using TDP commands, refer to Chapter 6: TDP Commands.
33
When the TDPUTCE is enabled, TDP calls the user data collection routine via a BALR 14,15, with register R1 pointing to the parameter list. The parameter list is described by the TDPMNPRM macro, which is distributed with the product.
Developing Collection Applications

Your site is responsible for developing applications that process and analyze the data collected by TDPUTCE.
Customizing TDPUTCE
Because TDPUTCE runs as part of TDP, it is privileged. If it is improperly coded, TDPUTCE may cause errors or even destroy TDP. When you customize a TDPUTCE module, consider the following points: TDPUTCE may only access data supplied by TDP in data control blocks described in MACLIB and SAMPLIB, on a release tape of Teradata software. It is not permitted access to other TDP components. The TDPUTCE module may directly use most normal OS services. If TDPUTCE is abnormally terminated, TDP error recovery disables TDPUTCE and allows logon requests to continue. On MVS or VOS3, a dump is written to the virtual printer. If the exit attaches tasks and a subtask abnormally terminates, TDP does not process the error. That is, the exit is not disabled and no dump is written by TDP. However, the operating system may record the dump if the standard resources are available (a SYSUDUMP DD statement on MVS, for example). It is the exits responsibility to properly manage its subtasks so that such failures do not impact its operation. TDPUTCE runs under TDP as a single-threaded routine, and may process only one request at a time. Consequently, the routine must be at least serially reusable or re-enterable in order to be compatible with the rest of TDP. TDPUTCE may keep its own tables. As part of the parameter list between TDPUTCE and TDP, a single word is always passed. Use of this word, which may be used to point to a block of storage containing information required across calls, is completely under the control of TDPUTCE. As a subroutine of TDP, TDPUTCE must save and restore registers in the standard OS format when it is called. If other services besides TDPUTCE also are called, the routine must provide its own save area. Finally, TDPUTCE must return to the address passed in general register 14.
Control is passed to the TDPUTCE routine with general register 1 pointing to the TDPMNPRM control block. This control block contains a user word, the request/response string, and pointers to fields containing information about the requestor. When invoked to process a TDP command, any userids, passwords, and account names may consist of characters from the character set passed to the
34
exit. When supported by this character set (or, for the START POOL command, in the command itself), each contiguous group of EBCDIC double-byte characters is preceded by the Shift-out control character, X0E and followed by the Shift-in control character, X0F. Neither commas nor blanks may be specified as EBCDIC double-byte characters. When invoked to process requests and responses, data (including object names) may contain EBCDIC double-byte characters if double byte characters are valid in the session character set passed to the exit.
Installing a Customized TDPUTCE Under MVS or VOS3

You can install a customized TDPUTCE in the MVS environment during normal TDP operation. Follow these steps to install a customized TDPUTCE under MVS or VOS3, where <dbcpfx> is your sites prefix for MVS client modules:
Step Action
Rename the current version of TDPUTCE (either as originally supplied on the release tape or as modified by your site) and retain it in the <dbcpfx>.TDPLOAD library. (This allows the installation to back out erroneous load modules.) Compile and link-edit the customized TDPUTCE module into the <dbcpfx>.TDPLOAD library as TDPUTCE with the options RENT,REUS. Install the customized TDPUTCE with SMP as a USERMOD to prevent overlaying the customized module with a replacement TDPUTCE module supplied in a later software release.
2 3
Installing a Customized TDPUTCE Under VM

You can install a customized TDPUTCE in the VM environment during normal TDP operation. Follow these steps to install a customized TDPUTCE under VM:
Step Action
1 2
Invoke TDPUTCE EXEC to assemble the modified TDPUTCE ASSEMBLE. Replace the TDPUTCE entry in TDP LOADLIB.
35
Chapter 3: Performance Measurement General Tuning Options
General Tuning Options

Introduction
All client software may be tuned using options provided by TDP and the Teradata server.
TDP Options
To provide for memory acquisition during system operation without incurring the high overhead associated with the GETMAIN/FREEMAIN memory services, TDP acquires units of main memory, or cells, from its own, more efficient memory manager. During startup, the memory manager pre-allocates a number of cells in sizes that are convenient for use by TDP. The sizes of the cells are internal constants. The initial number of cells is an internal default.
WHEN a . . . THEN the . . .
TDP subtask requests a cell from the memory manager, but all available cells are being used by other TDP subtasks
memory manager does one of the following: Obtains a single cell using a GETMAIN call to the operating system Places the requesting subtask into a wait for memory
requester is placed into a wait
wait ends when another TDP subtask releases a cell. The decision to use GETMAIN or wait is based on the cell size and the identity of the requesting subtask.
Monitoring Performance and TDP Cells

A system programmer can use the TDP DISPLAY CELLS command to monitor the performance of the TDP cell system. TDP will display the following cell system statistics in response to the DISPLAY CELLS command: Size of cells in use Number of each size of cell allocated to TDP Number of each size of cell currently in use Maximum number of each size of cell used at any one time Number of times GETMAIN was used to satisfy requests because all cells allocated were in use Number of cross memory cells initially in use
36
Number of times that a TDP subtask was placed into a wait because all cells of that size were in use
You can view final statistics in the following records: In MVS, the SMF shutdown record In VOS3, the SMS record
If this information indicates that the number of cells currently allocated is not adequate for certain kinds of processing, more cells may be provided to the memory manager. Cells can be added during TDP startup via the ADD CELLS operator command, which may be executed from the TDPPARM data set, or from the system console. For example, if the statistics indicate problems in any client performance for FastLoad operations, a systems programmer may decide to add cells of data buffer size before running the next FastLoad.
Tuning TDP Cells to Optimize Performance

Follow the tips in the following table to ensure that your TDP cells are tuned for optimum performance.
Question Answer
How do I know whether to add regular cells or PC cells when I experience a cell shortage?
The following messages indicate a shortage of PC cells. TDP1520 WAITS FOR INITIAL XMS CELLS: 0 TDP1521 WAITS FOR ADDITIONAL XMS CELLS: 0
IF the counts in the message are . . .
THEN add this kind (kinds) of cells . . .
0 anything else
regular. PC, either in addition to, or instead of, regular.
When can I use the ADD CELLS command?
You can use the ADD CELLS command in the following circumstances: While TDP is running As a TDPPARM dataset parameter You cannot use ADD CELLS as a TDPPARM dataset parameter if you want to add 12,272 byte cells; instead, you should use INITIAL IOBUFS.
37

Question Answer
When can I subtract cells?
You cannot subtract cells. Whenever you start TDP, cell allocations return to the TDP defaults unless the TDPPARM dataset parameters have one of the following commands: ADD CELL ADD XMSCELL INITIAL IOBUFS
How do I change the number of Input/Output buffers?
Use the INITIAL IOBUFS command to specify the number of Input/Output data buffers. Note: IOBUFS are not used for CPs requiring the CCU operand on the START command. These CPs automatically manage their I/O buffers. 6 per CP. This is true both for 480 byte and 12,272 byte cells. More highly stressed CPs should be allocated more cells. To do this, use either ADD CELLS (while TDP is running) or INITIAL IOBUFS (in the TDPPARM dataset). Note: IOBUF cells (12,292 byte cells) are not used for CPs requiring the CCU operand on the START command. Exclude these CPs when considering the default cell size.
What is the default number of cells used for Input/Output?
38

Question Answer
What are the most important cell sizes and what are they used for?
There are four common cell sizes. The 480 and 12,272 byte sizes (also known together as I/O buffers or IOBUFS) are both needed for I/O. Common uses are explained in the following table.
Cell size (bytes) Usage
240
1 cell is required per session. 1 cell is required per interface processor.
992 480
Request and response buffers Move requests and responses across the channel between the client and the server. For CPs started without the CCU operand on the START command, move requests and responses across the channel between the client and the server.
12,272
Scenario
Suppose a customer has been getting TDP0021 warnings for 992 byte cells (data buffers), for example:
TDP0021 **WARNING** 100% OF 992 BYTE CELLS IN USE
The maximum number of data buffers required is equal to the product of the number of sessions and the amount of data transferred divided by 992:
((number of sessions)(amount of data transferred))/992
The amount of data transferred applies to both requests and responses. For all but the most unusual cases, you should not need this maximum number of data buffers. Cell usage can push the maximum in cases where the ratio of interface processors to AMPs on the system is very low (for example, 8:104). In this case, data transfer through the interface processor is a bottleneck because each session sends a request into TDP, and those requests become enqueued within TDP because the bottleneck restricts TDPs ability to dispatch the requests to the server in a timely way. This creates a producer-consumer relationship in which the sessions produce requests (up to 32K each in the case of FastLoad) that are buffered in TDP until the server can consume them. The interface processor bottleneck represents
39
slow consumption, and more data ends up buffered in TDP than would normally occur. More commonly, the sessions communicating through TDP might, at any given instant, be in one of several states. These states include: Request inside TDP waiting for I/O to the server (Requires TDP cells) Request active on the server (Does not require cells) Response received in TDP but not yet sent to the application (Requires cells) Response sent to the application, but next request has not yet arrived (Does not require cells)
At any given moment, the number of sessions whose request is within TDP but has not yet been sent to the server is less than or equal to the total number of sessions logged on. You should set the number of cells above the average, but below the peak. Average and peak are functions of the configuration and the workload. For example, running five FastLoad jobs and several BulkLoad jobs on a server with eight interface processors and 104 AMPs produces a much higher average percent of sessions with requests/responses passing through TDP than would a sixteen interface processor, 104 AMP server. The optimal way to handle standard use is to set the number of cells just above the average and then let TDP memory management algorithm deal with peak activity periods because it is generally neither practical nor beneficial to give TDP the number of cells required to handle peak requests. Generally, it is better to let requests back up in the application address space instead. Such an approach should provide equal or better throughput while at the same time ensure better usage of CPU and real storage consumption by the operating system. The message noted at the beginning of this section, the TDP0021 message, indicates the percentage of available cells that are in use. Peaks of 100% are not cause for alarm, though an average of 100% indicates that you should add more cells. In general, assume that somewhere between 20 and 30 percent of the sessions active are inside TDP at any given moment.
Example of How to Analyze Cell Usage Optimization

For the purpose of this example, assume the following things: A system with 8 IFPs and 100 AMPs 5 FastLoads running using 100 sessions 5 BulkLoads running using 100 sessions Each FastLoad or BulkLoad request is 32K (this produces approximately 33 992 byte cells, for a total of 31 Mbytes) System is running with the default initial cell values, resulting in TDP0021 messages of 100% plus very high getmain/wait/waits for XMS counts.
3 10
10% of the sessions have requests in transit through TDP simultaneously at any given moment.
Observations
The theoretical maximum of cells is (number of jobs) (sessions per job) (number of cells), or (10)(100)(33) = 33,000 992-byte cells. Given the assumptions, there should be about 3300 cells (.10)(33,000) = 3300.
Procedure
Follow this procedure to optimize cell usage.
Step Action
1 2 3 4
Issue an ADD CELLS command to bring the 992 byte cells up to a total of 3300. Run the workload again (5 FastLoads and 5 BulkLoads). Issue a D CELLS command at regular intervals to determine the number of available and in use cells. Use the results of the D CELLS query as follows.
IF . . . THEN . . .
the system is still at 100% utilization cells are always available
add more cells. reduce the number of cells.
Remember to aim for slightly more than average, not for the peak.
System Options
System performance is affected by the load on the block multiplexer channel, which is connected to the Teradata server. For the best system performance, a channel that is used by the Teradata server should be dedicated to devices to that server. However, if research at your site indicates that a channel is not overloaded, you can share that block multiplexer channel with other devices, such as disk or tape devices. It is the responsibility of your site to monitor channel utilization to determine if it is high enough to degrade the performance on the Teradata server. Note that an overloaded channel will result in I/O delays for other devices on that channel.
3 11
Chapter 3: Performance Measurement MVS and VOS3 Performance Measurement
MVS and VOS3 Performance Measurement

Introduction
In addition to HSI time stamps described previously, MVS and VOS3 client software generate records to provide performance data, as follows: In MVS, SMF records In VOS3, SMS records
The contents of the records are described by the TDPSMFR macro, which is distributed with the product.
SMF/SMS Records
SMF/SMS is a standardized mechanism that provides accounting and performance information. As an option, the TDP subsystem generates an installation-specified SMF/SMS record type. The SMF/SMS record ID is the record number where TDP accounting and performance data is recorded. The record ID is specified in the Host System Interface System Parameter Block (HSISPB). The HSISPB is delivered with a default ID. The SMF/SMS record type may be one of the following subtypes:
SMF Record Subtype Description
CP shutdown Logoff
Statistical information about the processing activity of a CP, recorded at shutdown. General information about a session being logged off and details about the sessions use of MVS or VOS3 client and Teradata server resources. Logon violations information provided by the User Logon Exit Interface and security violations information reported by the Teradata server. Statistical information about the processing activity of TDP, recorded at shutdown. Information about the communication protocol for a CP started with the CCU operand.
Logon violations and security violations TDP shutdown Structure-protocol termination
All the SMF/SMS record subtypes are described in further detail in the following sections.
3 12
Chapter 3: Performance Measurement CP Shutdown Record
CP Shutdown Record
Introduction
Shutdown of a CP generates SMF statistical records about the normal processing capability of that CP.
Usage Notes
Shutdown information may be used to determine optimum table sizes and numbers of cells (units of main memory) to be implemented through the TDPPARM data set.
Record Contents
The shutdown record for a CP contains the following information: Channel Processor number Total number of messages, blocks and bytes sent and received CP start and stop times
3 13
Chapter 3: Performance Measurement Logoff Record
Logoff Record
Introduction
During the logoff process, normal or abnormal, the TDPSESS module (the general session control interface) generates an SMF record. This record contains general information about the session being logged off, as well as details about the overall use of MVS or VOS3 client and Teradata server resources.
Record Contents
The logoff record includes the following information: Session start and end times Session number, session processor number Teradata server logoff completion code Session termination status (why the session ended, for example, because of command, end of task, user request) Session idle time (time spent waiting for applications to issue requests, in .01-second units) Session busy time (time spent waiting for the Teradata server to complete requests, in .01-second units) TCB, job name, job start time Total number of start, continue, and other requests Thousands of bytes sent and received
All times are recorded in SMF/SMS date/time format: Date: in packed decimal cyydds Time: in 0.01-second units
3 14
Chapter 3: Performance Measurement Security Violations Record
Security Violations Record

Definition
An SMF record of security violations reported by the Teradata server or logon violations reported by the User Logon Exit Interface (TDPLGUX) is optionally written to the SMF data set.
Usage Notes
This information may be correlated with the logoff record to identify users who are violating installation standards and security procedures. To simplify correlating these records with other job- and step-related records, security records contain the standard SMF job identification: job name, step number, and date/time the reader recognized the job card. For details about the User Security Interface (TDPUSEC) and the User Logon Exit Interface (TDPLGUX), refer to Chapter 4: Security Features Under MVS and VOS3.
Record Contents
The security violations record contains the following information: Job name and TCB of the violator Type of violation: logon or Teradata server security violation Session and request number Session processor used Type of request causing the violation Action taken by the user security exit (TDPUSEC)
3 15
Chapter 3: Performance Measurement TDP Shutdown Record
TDP Shutdown Record

Introduction
Shutdown of TDP generates SMF statistical records about the normal processing capability of TDP.
Usage Notes
As with CP shutdown information, TDP shutdown information also may be used to determine table sizes and numbers of cells to be implemented through the TDPPARM data set.
Record Contents
The shutdown record for a TDP contains the following information: Total time TDP was active Size of session control tables Size and number of cells Number of times the GETMAIN or FREEMAIN memory services of MVS or VOS3 were invoked to obtain needed cells
3 16
Chapter 3: Performance Measurement Structure-protocol Termination Record
Structure-protocol Termination Record

Introduction
Termination of a CP that was started with the CCU operand records information about the communication protocol. Since the information is normally most useful to NCR customer support people, this record is disabled by default and is not further documented here.
Usage Notes
Since the protocol is terminated when the CP is shut down, every record of this type will be followed by a CP Shutdown Record. However, since the protocol is reinitialized after each server restart, there may be more records of this type than CP Shutdown records.
3 17
Chapter 3: Performance Measurement MVS and VOS3 Tuning With the HSI System Parameter Block
MVS and VOS3 Tuning With the HSI System Parameter Block
Introduction
You can change the size and number of TDP memory cells in the HSI System Parameter Block (HSISPB) to control the timing and performance of the HSI/TDP interfaces.
Size, Number of TDP Memory Cells

If use of the DISPLAY CELLS command indicates that the GETMAIN memory service has been used too many times to satisfy TDP requests for main memory, the ADD CELLS command may be used to improve TDP performance by adding cells of a specified size to main memory.
3 18
Chapter 3: Performance Measurement MVS Tuning With I/O Mode Options
MVS Tuning With I/O Mode Options

Introduction
System performance can also be tuned using the EXCPVR or IOSDRIVR options of the INITIAL IOMODE command (described in Chapter 6: TDP Commands). The INITIAL IOMODE command sets the input and output mode that TDP uses for communicating with the Teradata server.
EXCPVR Option
To make TDP I/O operations more efficient, you can use the EXCPVR option instead of the default EXCP option to eliminate any address translation of channel programs by the MVS I/O supervisor (IOS) each time the channel program supervisor call is invoked. With EXCPVR, the data areas involved in the I/O operation and the area containing the channel program are page-fixed. Therefore, address translation for the Channel Control Words (CCWs) that make up the channel programs is done only once, during TDP initialization.
IOSDRIVR Option
In the MVS environment, the IOSDRIVR option can be used instead of EXCP or EXCPVR to reduce CPU utilization. The IOSDRIVR option directs the MVS TDP to call IOS directly through the STARTIO macro interface to request that I/O be done on its behalf. To make TDP invoke the IOS driver routine (TDPIODVR) instead of invoking EXCP or EXCPVR, In the TDPPARM data set, include the TDP INITIAL command:
INITIAL IOMODE IOSDRIVR
In a heavily loaded TDP, the IOSDRIVR option reduces CPU utilization when compared to EXCP, and somewhat lower (11%-16%) than EXCPVR. Also, where TDP I/O queue lengths are consistently greater than 0, the I/O path lengths are reduced because the disabled interrupt exit (DIE) will fetch the next I/O request and submit it to IOS. Whenever the I/O completes successfully, post status processing (back-end IOS) also is avoided, thus cutting the number of instructions even further. Since the TDP address space is nonswappable, and the I/O related control blocks are in fixed storage, Teradata server-bound I/O will be re-driven out of any address space. That is, this occurs wherever the I/O interrupt is fielded for the previous I/O, thus avoiding address-space swapping to handle the interrupt and subsequent re-drive of new I/O.
3 19
Chapter 3: Performance Measurement VM Performance Measurement
VM Performance Measurement
Introduction
You can use resident modules to measure VM performance.
Resident Modules
TDP makes frequent use of the IUCV modules DMKIUA, DMKIUE, and DMKIUL, which are part of the pageable nucleus supplied by VM/SP. Because resident modules are less costly to invoke than pageable modules, your site should make the IUCV modules resident by moving these modules above DMKCPE in the CP loadlist (CPLOAD EXEC) and regenerating the nucleus.
3 20
Chapter 3: Performance Measurement VM Tuning With Operator Commands
VM Tuning With Operator Commands

Introduction
The following VM operator commands may be used to help the TDP machine(s) operate more efficiently: SET QDROP OFF SET QDROP OFF USERS SET FAVOR SET FAVOR Percent Option LOCK PAGE SET RESERVE TDP
Each command is described in more detail in the following subsections.
3 21
Chapter 3: Performance Measurement SET QDROP OFF
SET QDROP OFF

Introduction
TDP operation is characterized by frequent, short uses of the processor followed by idle states in which an enabled wait PSW is loaded. At this time, CP may QDROP TDP, thus invalidating all resident pages. Under heavy paging conditions, these pages are placed on the flush list. When VM/SP needs a real page frame to satisfy a user request, flush pages are selected. When TDP again becomes ready (for example, when it receives a new user request or response data from the Teradata server), CP adds TDP to the active queue and places it in the dispatch list. TDP must then reclaim the pages that comprise its working set. This results in many page faults, which must be resolved by revalidation and/or page-ins. This process of page invalidation/revalidation may occur frequently, incurring heavy operating system overhead and causing poor interactive response time and throughput delays for Teradata users.
Usage Notes
Executing the SET QDROP OFF command can eliminate some page invalidation processing (although the less active resident pages of TDP still are subject to the page-stealing mechanism). However, indiscriminate use of this command, especially in a storage-constrained system, may increase page flushing and page stealing. This, in turn, may cause core scan time reductions and compromise the effectiveness of VM page buffering (especially the q1 buffer). Ultimately, this too degrades system throughput and interactive response time.
3 22
Chapter 3: Performance Measurement SET QDROP OFF USERS
SET QDROP OFF USERS

Introduction
An application that has sent a request to TDP and is awaiting a response has an IUCV message outstanding. If the application generates frequent requests of relatively short duration, repeated QDROPS and QADDS (and resulting page invalidation/revalidation) may increase operating system overhead and degrade performance for the application.
Usage Notes
For TDPs that are running such applications, executing the SET QDROP OFF USERS command extends the benefits of the SET QDROP OFF command, described previously. QDROP OFF status is in effect for TDP only while an IUCV message is outstanding with TDP. However, if an applications requests are of relatively long duration, use of this command may have a negative effect on management of real storage and, therefore, on system performance.
3 23
Chapter 3: Performance Measurement SET FAVOR
SET FAVOR
Introduction
The VM scheduler maintains a list of machines that are eligible to be added to an executable queue. A machine is placed on the eligible list under either of the following conditions: It becomes ready after being idle It was executing, but was dropped from its queue because it used up its time allotment
An eligible machine must wait until sufficient real storage is available to hold its projected working set pages. Then it is added to the dispatch queue. Any wait for storage may delay TDP access to the processor and thus degrade Teradata server system performance in servicing a user request or handling a response from the Teradata server.
Usage Notes
If VMAP (an IBM virtual machine analysis program) indicates that TDP is experiencing undesirable waiting-for-storage delays, consider using the SET FAVOR(BASIC) command to designate TDP as a basic favored machine. Such a machine bypasses the eligible list and is added directly to the dispatch queue, regardless of storage availability. Thus, TDP may process each user request or Teradata server response as it is received. Because the processor time needed to service a request or a response is relatively short, as a favored machine TDP is able to use the processor in frequent bursts of short duration. As a result, Teradata server response time is improved. However, note that TDP is more efficient per request when processing a queue of work. Before using SET FAVOR for TDP, consider the combined storage requirements of all virtual machines against system performance reports and workload objectives. If these requirements exceed real storage availability, performance problemsincreased page stealing, higher auxiliary paging rates, I/O contention, and waiting-for-storage delaysmay result.
SET FAVOR with the Percent Option

In addition to SET FAVOR(BASIC), consider using SET FAVOR with the percent option to control the allocation of processor resources to meet your requirements. VM/SP will then attempt to provide TDP with the specified percentage of the processor time, if TDP can use it.
3 24
Chapter 3: Performance Measurement LOCK PAGE
LOCK PAGE
Introduction
If TDP is idle for a period of time or if storage is in demand, the operating system may steal the working set pages of TDP or place them on the flush list. When TDP again becomes active, it will have to reclaim these pages or retrieve them from disk. This can degrade response time.
Usage Notes
In this case, the user should consider using the LOCK page1...pagen option to lock page 0 and pages containing critical code or data areas. You should consult with your NCR support representative to determine which pages it would be advantageous to lock.
3 25
Chapter 3: Performance Measurement SET RESERVE TDP
SET RESERVE TDP

In addition to using the LOCK page1...pagen option, you may use the SET RESERVE TDP nnn option to cause VM/SP to keep the critical pages of TDPs working set in storage.
3 26
Chapter 3: Performance Measurement Other VM Tuning Options
Other VM Tuning Options

Introduction
Other VM/SP tuning options include the following: Using microcode assists that are present in the VM client Placing Teradata applications and interface software on the Y-disk Running TDP in the V=R area Placing devices on dedicated channels Using the dedicated channel option
Microcode Assists
TDP invokes a significant number of privileged instructions that must be simulated by the operating system. This can increase overhead costs dramatically. Because of this, you may want to take advantage of any microcode assists present in the VM client: If the processor has ECPS/VM, CPA, VMA, or VMA extended, ensure that it is enabled on both the real machine and the TDP machine. Ensure that DMKFPS (fast path simulation for certain priv-ops) is included in the load list. If you have an Amdahl machine, consider installing VM/SA, which contains the Amdahl control program modifications, to improve priv-op simulation.
Y Disk
The Y-disk directory is part of the saved CMS system. To reduce directory search time, place the VM client applications and interface software for the Teradata RDBMS on the Y-disk.
V=R Area
When TDP runs in the V=R area, the SET NOTRANS ON option can be invoked. This results in the following performance benefits: Reduces I/O response by bypassing page and CCW translation and untranslation Eliminates page validation, translation, and stealing
Dedicated Channels
If channel processors share channels with disk or tape devices, interference from disk and tape I/O can delay I/O between TDP and the Teradata server, which can in turn delay disk I/O. Thus, both operating system and TDP
3 27
Chapter 3: Performance Measurement Other VM Tuning Options
performance suffer. Placing these devices on dedicated channels eliminates this problem.
Dedicated Channel Option

If channel processors are the only devices on a channel, dedicating the channel to TDP eliminates device address translation overhead.
3 28
Chapter 3: Performance Measurement Channel Processor Device and Channel Error Logging
Channel Processor Device and Channel Error Logging

Introduction
TDP logs channel processor device and channel errors in hexadecimal format to an error log on the MVS or VM client.You can access and print the error log by using the IBM EREP utility. For more details, see Appendix A: Channel Processor Device and Channel Error Log.
3 29
Chapter 3: Performance Measurement Channel Processor Device and Channel Error Logging
3 30
Chapter 4:
Security Features Under MVS and VOS3

The Teradata Director Program (TDP) and the Host System Interface to TDP (HSIT) use a combination of built-in hardware and software security functions.
Hardware Security Functions

On the hardware level, the HSI uses the full range of storage protection facilities afforded by MVS and VOS3: All control blocks generated by the Host System Interface to TDP (HSIT) or Host System Interface Utility (HSIU) routines are placed in protected storage. Control blocks are created in the user address space in protect key 0; in CSA, in protect key 7. Control blocks containing data (for example, passwords and data transferred to and from the Teradata server) are fetch-protected. Data moved between address spaces is always fetch-protected in protect key 7. All data in the TDP address space is protected by MVS and hardware from illegal access. Because TDP uses protect key 7, the hardware-level interface does not require TDP to switch PSW key in order to reference or move data being transferred to or from it. All data transferred to or from the Teradata server is handled by EXCP or EXCPVR and is protected by the operating system and hardware.
Software Security Functions

The security function is more complex on the software level. Because the HSIT runs as a privileged program in protect key 0, each of its data areas and buffers must be examined individually to validate access.
Sending a Request
When a request is sent, the HSIT must obtain a local lock on the storage containing the data in the user address space before accessing data. This locking prevents another task from releasing the storage.
41
Chapter 4: Security Features Under MVS and VOS3
Validity Checking When Returning a Response

When a response is returned, validity checking is more critical. Because the HSIU routine is running in SRB mode, abnormal termination of this routine may terminate the entire address space rather than any one TCB task.
42
Chapter 4: Security Features Under MVS and VOS3 Security Features Under VM
Security Features Under VM

Introduction
A virtual machine runs in virtual state. Data is obtained in protect key 14 instead of protect key 7. As a result, a VM/CMS user does not have most of the security features discussed previously.
Security Process
Stage Process
1 2 3
A request is sent in a VM/CMS system. The request data is sent to TDP via an IUCV (Inter-User Communication Vehicle) SEND. The response data is picked up when TDP does a IUCV RECEIVE. There is no CSA.
A Teradata server response is sent from TDP to the user via an IUCV REPLY.
43
Chapter 4: Security Features Under MVS and VOS3 User Logon Exit Interface
User Logon Exit Interface

Introduction
Through the User Logon Exit (TDPLGUX), a user-provided routine can reject, accept, provide, or modify a logon request. The exit also allows the user to send the following options: No logon string (implicit logon) Only a user id that the user routine provides a password for A user id that can be validated as not requiring a password
TDPLGUX Operation
TDPGLUX processes three types of calls: Initialization Logon requests Terminate
The exit is initialized when TDP is initialized or when an ENABLE LGUX command is executed. During initialization, TDPLGUX obtains a work area, opens files, and so on. A logon request is passed to the TDPLGUX before the request is allowed to continue. When a logon request call is made to TDPLGUX, it is processed in the following manner.
Stage Process
TDP builds and passes a parameter list to TDPLGUX. This parameter list consists of: TDP information Requestor information Time stamps Parameter data from TDPUAX (User Address Space Exit) (MVS or VOS3 only) Logon information Modify the default SECLOGON class.
The TDP identifier and separating slash that CLI allows as a prefix to the Logon String, and the ending semicolon character, are removed by CLI, so are not present within the exit.
44
Stage Process
After the user routine processes the parameter data, the exit may: Reject or accept the logon string. Validate the logon string (if it contains only a user id). Provide a logon string (if logon is implicit). Determine if the logon string has already been validated by TDPUAX (MVS or VOS3 only). Modify the logon string. If the logon string is to be modified, the exit is passed the location and length of the logon string in the parameter list.)
If the logon request is accepted, TDPLGUX sends a return code of zero. If the logon request is rejected, TDPLGUX sends a nonzero return code and the violation is reported to the security exit.
Teradata security mechanisms require that both the logical host on which TDP resides and the Teradata server userid both have been granted the right to logon with null password. For an example of coding TDPLGUX, refer to the sample TDPLGUX that is shipped with TDP. The parameter list is described by the TDPLGPRM macro, which is distributed with the product.
Customizing TDPLGUX
When customizing a TDPLGUX module, the following points must be considered: Because TDPLGUX runs as part of TDP, it is privileged. If improperly coded, it may cause errors or even destroy TDP. TDPLGUX may access only data supplied by TDP in data control blocks described in MACLIB and SAMPLIB, on a release tape of Teradata software. It may not access other TDP components. TDPLGUX may directly use most normal OS services. If TDPLGUX is abnormally terminated, TDP error recovery disables TDPLGUX and allows logon requests to continue. On MVS or VOS3, a dump is written to TDPSNAP DDName; on VM, a dump is written to the virtual printer. If the exit attaches tasks and a subtask abnormally terminates, TDP does not process the error. That is, the exit is not disabled and no dump is written by TDP. However, the operating system may record the dump if the standard resources are available (a SYSUDUMP DD statement on MVS, for example). It is the exits responsibility to properly manage its subtasks so that such failures do not impact its operation.
45
TDPLGUX runs under TDP as a single-threaded routine, and may process only one request at a time. Consequently, the exit routine must be at least serially reusable or re-enterable in order to be compatible with the rest of TDP. TDPLGUX may keep its own tables. A single word is always passed between TDPLGUX and TDP as part of the parameter list. TDPLGUX may use this word to point to a block of storage containing information that is required across calls. As a subroutine of TDP, TDPLGUX must save and restore registers in the standard OS format when it is called. If other services besides TDPLGUX also are called, the routine must provide its own save area. Finally, TDPLGUX must return to the address passed in general register 14.
Control is passed to TDPLGUX with general register 1 pointing to the TDPLGPRM control block. This control block contains a user word, the logon string, pointers to fields containing information about the register, and the session character set. If the logon string is parsed, the userid, password, and account name each consists of characters from the session character set. When supported by the session character set, each contiguous group of EBCDIC double-byte characters is preceded by the Shift-out control character, X0E, and followed by the Shiftin control character, X0F. Neither commas nor blanks may be specified as double byte characters. On return, TDPLGUX passes one of the following return codes to TDP in general register 15:
Return Code Meaning
0 Nonzero
Allow the logon request to continue. Do not allow the logon request to continue.
Installing a Customized TDPLGUX

You can install a customized TDPLGUX during normal TDP operation. Follow these steps to install a customized TDPLGUX:
Step Action
Rename the current version of TDPLGUX (either as originally supplied by NCR or as modified by your site) to allow you to revert back to the previous copy if necessary.
46
Step Action
Compile and link-edit the customized TDPLGUX module into one of the following: In MVS and VOS3, the <dbcpfx>.TDPLOAD In VM, TDP LOADLIB library as TDPLGUX with the options RENT,REUS.
In the MVS or VOS3 environment, install the customized TDPLGUX with SMP as a USERMOD to prevent overlaying a customized TDPLGUX with a replacement TDPLGUX module supplied in a later software release.
47
Chapter 4: Security Features Under MVS and VOS3 User Security Interface
User Security Interface

Introduction
Any return code from the Teradata server that indicates an illegal or invalid attempt to access data is intercepted and passed to TDP User Security Interface (TDPUSEC).
TDPUSEC Operation
TDPUSEC processes three types of calls: Initialization Security Violation Terminate
The exit is initialized when TDP is initialized or when an ENABLE USEC command is executed. During initialization, TDPUSEC obtains a work area, opens files, and so on. When a security violation call is received by TDPUSEC, it takes one of the following actions: Sets a return code that indicates the following: an error message is to be issued to the client operator and written to the system log, and (for MVS or VOS3 only), a Security Violation SMF/SMS record is to be written Returns control to TDP, which called TDPUSEC.
A terminate call is processed by TDPUSEC when TDP is disabled or a DISABLE USEC command is executed. When this call is received the exit closes all files and cleans up all resources. For a coding example of the TDPUSEC routine, refer to the sample TDPUSEC that is shipped with TDP. The parameter list is described by the TDPUSPRM macro, which is distributed with the product.
Customizing the TDPUSEC

When customizing a TDPUSEC module, consider the following points: Because the TDPUSEC runs as part of TDP, it is privileged. If improperly coded, it may cause errors or even destroy TDP. The module may access only data supplied by TDP in data control blocks described in MACLIB and SAMPLIB, on a release tape of Teradata software. It is not permitted access to other TDP components.
48
The TDPUSEC module may directly use most normal OS services. WTO, WTL, and SMFWTM services should be invoked by passing appropriate return codes to the caller of TDPUSEC, TDP. If the TDPUSEC routine is abnormally terminated, TDP error recovery disables TDPUSEC and takes default actions (returning SMF record, log and system operator messages, and error return code to the violating user). On MVS or VOS3, a dump is written to TDPSNAP DDName; on VM, a dump is written to the virtual printer. If the exit attaches tasks and a subtask abnormally terminates, TDP does not process the error. That is, the exit is not disabled and no dump is written by TDP. However, the operating system may record the dump if the standard resources are available (a SYSUDUMP DD statement on MVS, for example). It is the exits responsibility to properly manage its subtasks so that such failures do not impact its operation. TDPUSEC runs under TDP as a single-threaded routine, and may process only one request at a time. Consequently, the routine must be at least serially reusable or re-enterable to be compatible with the rest of TDP. TDPUSEC may keep its own tables. As part of the parameter list between TDPUSEC and TDP, a single word is always passed. Use of this word, which may be used to point to a block of storage containing information required across calls, is completely at the option of TDPUSEC. As a subroutine of TDP, TDPUSEC must save and restore registers in the standard OS format when it is called. If other services besides TDPUSEC also are called, the routine must provide its own save area, and it must return to the address passed in general register 14. Control is passed to the TDPUSEC routine with general register 1 pointing to the TDPUSPRM control block. This control block contains a function code, a user word, and pointers to fields containing information about the failed request. On return, TDPUSEC passes a return code in general register 15 that requests any of the following TDP actions: Do nothing but return an error code to the caller. In MVS or VOS3, issue a WTO to the security console. In VM, issue a message to the TDP console or a secondary user. (MVS or VOS3) Write a message to the system log and return an error code to the caller. (MVS or VOS3) Write a TDP security violation SMF record and return an error code to the caller. (MVS or VOS3) Abnormally terminate the caller (via cross memory ABTERM).
Any combination of these options may be chosen. If the last option is chosen, however, the failure message is discarded without any attempt to return it to the caller.
49
Installing a Customized TDPUSEC

You can install a customized TDPUSEC during normal TDP operation. Follow these steps to install a customized TDPUSEC:
Step Action
1 2
Rename the current version of TDPUSEC (this allows you to revert to the previous version if necessary). Compile and link-edit the customized TDPUSEC module into one of the following: In MVS or VOS3, the <dbcpfx>.TDPLOAD In VM, TDP LOADLIBlibrary as TDPUSEC, with the options RENT,REUS.
Install the customized TDPUSEC with SMP as a USERMOD to prevent overlaying a customized TDPUSEC with a replacement TDPUSEC module supplied in a later software release.
4 10
Chapter 4: Security Features Under MVS and VOS3 User Address Space Exit
User Address Space Exit

Introduction
The User Address Space Exit (TDPUAX) is available only in the MVS or VOS3 environment. It is called in the address space of the application when an application initiates a request to the Teradata server. The exit can accept, reject, validate, or modify the logon string of the caller. Teradata server security mechanisms require that both the logical host on which TDP resides and the Teradata server userid both have been granted the right to logon with null password.
TDPUAX Operation
TDP builds and passes a parameter list to TDPUAX. The parameter list consists of the following: TDP information Requestor information Time stamps Parameter data Logon information
When TDPUAX is called during an application logon or connect request, it can be used to: Accept the logon request and return to TDP with a return code of zero. This causes TDP to send the logon string to the Teradata server and return to the application with an initial status return code of zero. Reject the logon request by sending a nonzero return code to TDP. TDP immediately returns to the application with a non-zero return code. Modify the logon request in the TDPUAX build area and notify TDP that the logon string has been modified. Set a flag when it returns, indicating that the logon string has been validated. This causes TDP to notify the Teradata server that the exit has validated the logon. In a validated logon, the password field of the logon string is optional, and is ignored if present. The userid must be a valid userid with the proper rights granted, as described above. An account string, if it is used, must be valid and will be respected.
This exit does not currently support a terminate call, therefore any cleanup after the application ends or abend must be managed by the application.
4 11
For an example of coding TDPUAX, refer to the sample TDPUAX that is shipped with TDP.
Customizing TDPUAX
When customizing a TDPUAX module, the following points must be considered: As with any system exit, TDPUAX must be carefully coded and debugged with the assistance of an experienced system programmer. Any errors in TDPUAX can damage the application address space or the operating system itself. TDPUAX obtains control in supervisor state, key 7, enabled, in home mode, in task mode, with the local lock held. Since TDPUAX is locally locked, no SVCs can be issued. The local lock must not be released. If you are using MVS/XA or above, TDPUAX must specify AMODE 31 (in VOS3, specify TRAIT EA) because the data buffers may reside in virtual storage greater than 16 MB. During its execution, the TDPUAX can change the addressing mode, but it must later return control in the addressing mode of the caller (as indicated on entry by bit 0 in general register 14). This is normally accomplished using the instruction, BSM 0,14. A single copy of TDPUAX resides in CSA and is shared by all address spaces in the system. Therefore, it must be coded and linked re-entrant. Any memory obtained by TDPUAX should be associated with the jobstep task for the following reasons: It enables the Teradata server to distinguish between calls from different applications. TDPUAX can include a user word in its parameter list to maintain context across calls. The parameter list is associated with the jobstep task under which the application is executing. Thus, the contents of the user word are passed to TDPUAX with each call under that jobstep task. If another application is executing under a different jobstep task in the same address space and initiates a logon to the Teradata server, a different parameter list (and thus another unique user word) is passed. It ensures that the operating system cleans up the memory when the jobstep task terminates, since there is no termination call to TDPUAX. The interface to TDPUAX is established through standard OS linkage conventions. Upon entry, TDPUAX is passed the address of an 18-fullword save area in register 13. TDPUAX must save the callers registers on entry and restore them before returning to the return address that is passed in general register 14. If TDPUAX invokes services that require a save area, TDPUAX must provide one for the use of that service.
Control is passed to TDPUAX with general register 1 pointing to the TDPUAXP control block (parameter list), which contains the following:
4 12
A user word that can be set by the exit and remain intact on subsequent calls (under the same jobstep TCB) TDP information Requestor information Parameter information Logon information
Note: The TDP identifier and separating slash that CLI allows as a prefix to the Logon String, and the ending semicolon character, are removed by CLI, so are not present within the exit. Session character set information
If the logon string is parsed, the userid, password, and account name each consists of characters from the session character set. When supported by the session character set, each contiguous group of double byte characters is preceded by the Shift-out control character, X0E, and followed by the Shift-in control character, X0F. Neither commas nor blanks may be specified as double byte characters. On return, TDPUAX passes one of the following return codes to TDP in general register 15:
Return Code Meaning
0 Nonzero
Allow the logon request to continue. Do not allow the logon request to continue.
The parameter list is described by the TDPUAXP macro, which is distributed with the product.
Installing a Customized TDPUAX

You can install a customized TDPUAX during normal TDP operation in the MVS or VOS3 environment. It is not available under VM. Follow these steps to install a customized TDPUAX:
Step Action
1 2
Rename the current version of TDPUAX. (This allows you to revert to the previous version, if necessary.) Compile and link-edit the customized TDPUAX module into the <dbcpfx>.TDPLOAD library, specifying link-edit options that are consistent with the guidelines listed above. Install the customized TDPUAX with SMP (MVS clients only) as a USERMOD to prevent overlaying a customized TDPUAX with a replacement TDPUAX module supplied in a later software release.
4 13
Chapter 4: Security Features Under MVS and VOS3 External Security Manager Interface
External Security Manager Interface

Introduction
TDP provides an external security manager interface to the System Authorization Facility (SAF) on MVS and VM client systems. External security managers such as RACF and ACF2 can use SAF for logon validation and authorization, thus controlling access to the Teradata RDBMS without direct interaction with the RDBMS itself. Using TDP and an external security manager, system security administrators can maintain a separate external database or repository of resource profiles and access rules for the Teradata RDBMS, as well as for TSO, CICS, DB2, etc. This approach, called security logon, significantly enhances the convenience and flexibility of system security administration. Since SAF assumes all character data is in EBCDIC but a Teradata RDBMS userid may be in non-EBCDIC character sets, unexpected rejections or security exposures are possible. A userid known to the external security manager in EBCDIC would not be recognized if specified in ASCII. A userid specified in ASCII might consist of the same bytes as an EBCDIC userid known to the external security manager and erroneously match. Such problems could be circumvented by using different classes for userids encoded in different character sets. On a request by request basis, the TDPLGUX exit can override the default class from the ENABLE SECLOGON command based on the character set.
Security Logon Operation

The security logon operation is a four-stage process that involves: TDP The MVS or VM System Authorization Facility (SAF) Your external security manager The Teradata RDBMS
Stage Process
At logon time, if the security logon function is enabled, TDP compares the Teradata RDBMS user id supplied by the logon application with the authid associated with the requesting mainframe address space:
IF there is . . . THEN . . .
a match, either explicit or implicit (no Teradata RDBMS userid supplied)
TDP allows the logon to proceed with no further security processing.
4 14
Stage Process
not a match
TDP sends logon validation and authorization requests to the SAF interface to determine:
First, whether the user/authid is valid (validation) allowed access to the particular TDP (authorization)
b And, if it is valid, whether the user/authid is
2 3 4
The SAF interface routes the logon validation and authorization requests to the external security manager. The external security manager checks its own database or repository to identify the user and verify access authorization. The external security manager response to the SAF validation and authorization requests indicates: Whether the validation request succeeded or failed Whether the authorization request was approved or disapproved Any reason codes associated with a failed or disapproved request
Using Security Logon With TDPLGUX

The TDP security logon function and the User Logon Exit interface, TDPLGUX, can both operate independently. But, because TDPLGUX can optionally modify both the authid and the logon string itself, using them together can provide additional flexibility in security administration. When the security logon function is disabled, TDP allows a logon to proceed whenever TDPLGUX returns a zero value. When the security logon function is enabled, the logon is routed to TDP for final validation and authorization via the MVS or VM System Authorization Facility (SAF) and your external security manager. Note: Whenever TDPLGUX returns a nonzero value, TDP terminates the logon attempt, immediately, whether security logon is enabled or disabled. When using security logon with TDPLGUX, configure TDPLGUX to: 1 First, check flag bit LGSI$SEC in the LGISFL switch byte. This flag is ON when the security logon function is enabled, signifying that TDPLGUX may place a modified authid in LGICHUSR. Then, after modifying the authid, set flag bit LGI$CHNG in the LGISFL switch byte to ON. This signifies that TDP should use the new authid for logon validation and authorization. If necessary, override the default class in the LGICLASS field.
4 15
Note: By default, with no intervention by TDPLGUX, the authid is: LGIXISU for most applications LGIXIUSR for multiuser single-address-space applications such as CICS and IMS
Bypassing Security Logon

When using the security logon function with TDPLGUX, you can configure TDPLGUX to bypass security logon for special maintenance-type authids. To bypass the security logon function completely, for example, configure TDPLGUX to set the LGI$BYPS flag bit in the LGISFL switch byte to ON.
Enabling/Disabling Security Logon

If you change the enabled/disabled status of the security logon function while TDPLGUX is processing a logon request, TDP honors the configuration of the LGISFL switch byte as follows: If LGI$SEC was set to ON when TDPLGUX received control, and you disable the security logon function while TDPLGUX is still in control, TDP will apply security logon to the current request, but not to any subsequent requests. If LGI$SEC was set to OFF when TDPLGUX received control, and you enable the security logon function while TDPLGUX is still in control, TDP will apply security logon to all subsequent requests, but not to the current request.
Using Security Logon With Session Pools

The security logon function is fully compatible with session pools. Like TDPLGUX, security logon is not automatically invoked when you start a session pool. It receives control when an application actually logs onto one of the sessions in the pool. Note: Depending on how the session pool is defined at start-up, the application may still need to provide a password to log on to a session in a particular pool, even though the security logon function does not require a password.
Using Security Logon With The Validated Logon Function

The validated logon function allows applications to omit a password when logging on to the Teradata RDBMS from channel-attached client systems. (Logon requests from network-attached systems always require a password.) This function is also supported by the TDPLGUX User Logon Exit interface and the TDPUAX Address Space Exit. TDP security processing for validated logon requests may be handled by the security logon function, or by TDPLGUX or TDPUAX, or any combination of the three, depending on your system configuration.
4 16
Before any user can log onto the Teradata RDBMS, the user name must be defined in the database. A typical user name definition would be:
CREATE USER ASG AS PERM=10000000 PASSWORD=MYPASSWORD;
This would define user name ASG with ten megabytes reserved for tables and associated data structures, and a logon password of MYPASSWORD. (The user definition must include a password, even if you intend to use the validated logon feature.) With this definition, the user could log on to the Teradata RDBMS by specifying the TDPid associated with the RDBMS, a user name of ASG, and a password of MYPASSWORD. Before the user could omit the password from the logon string, per the validated logon function: The Teradata RDBMS system administrator would have to grant logon access with a null password. The system security administrator would have to create the appropriate user resource profiles or access rules in the external security manager application database.
See the setup procedure in the following subsection for a complete description of these tasks.
Security Logon Setup Procedure

Use the following procedure as a guideline for setting up and using the security logon function:
Step Action
Submit the following Teradata SQL statement to the Teradata RDBMS to grant logon access with a null password: GRANT LOGON ON ALL AS DEFAULT WITH NULL PASSWORD; Note: This command must be submitted either by the Teradata RDBMS system administrator, or by another user with EXECUTE access to DBC.LogonRule. Note also that: The null password privilege only applies to logon requests originating on mainframe client systems. Requests from networkattached workstations always require a password. Any attempt to log on to the Teradata RDBMS with user name DBC always requires a password. TDP will not use the validated logon feature for user name DBC. The AS DEFAULT provision can be overridden by more restrictive GRANT clauses for individual users.
4 17
Step Action
If you have customized the User Logon Exit interface (TDPLGUX), then review the interaction guidelines presented in subsection, Using Security Logon with TDPLGUX, to determine whether additional changes are required. If you have not customized TDPLGUX, its enabled/disabled status will have no effect on security logon operations.
Set up your external security manager to work with the TDP security logon function. For RACF:
Create user profiles in the FACILITY class with a universal access code of NONE to regulate logons. Note, in the following example, that the first qualifier of the resource name specifies the TDPid, and the second qualifier specifies the DBC user logon name: RDEFINE FACILITY TDP9.TEST01 UACC(NONE) RDEFINE FACILITY TDP0.BIG_DBC_USER_NAME UACC(NONE) RDEFINE FACILITY TDPX.PAYROLL977263 UACC(NONE) profile. READ is sufficient, as in the following examples: PERMIT UACC(READ) USER(TSO0997) PROFILE(TDP9.TEST01) CLASS(FACILITY) PERMIT UACC(READ) USER(TSO0998) PROFILE(TDP0.DBC_BIG_USER_NAME) CLASS(FACILITY) PERMIT UACC(READ) USER(TSO0999) PROFILE(TDPX.PAYROLL977263) CLASS(FACILITY) -
b Give each user the appropriate status authority to the FACILITY
If you have not already done so, activate the FACILITY class: SETROPTS CLASSACT(FACILITY)
For ACF2: Set up resource rules of TYPE(FAC) to regulate logon requests and grant access to each user. Note, in the following example, that the key represents the TDPid and the extension represents the DBC user logon name: SET RESOURCE(FAC) COMPILE * $KEY(TDP9) TYPE(FAC) TEST01 UID(TSO997) ALLOW
4 18
Step Action
STORE COMPILE * $KEY(TDPX) TYPE(FAC) STORE COMPILE * $KEY(TDPX) TYPE(FAC) PAYROLL977263 UID(TSO999) ALLOW STORE For all other external security managers: Refer to the appropriate vendor documentation.
Always test new resource profiles or access rules before placing them in a production environment. Because the FACILITY class is limited to 39 bytes, it will not suffice if RDBMS user names exceed 30 bytes. This will be the case only if character sets are being used that support more than one byte per character. If this is the case, you will have to create an entirely new class with a maximum length of 92 bytes (the maximum number of bytes for an RDBMS user id in any currently supported character set). This is a complicated processespecially under RACF, where an IPL will be requiredand should be performed only by an experienced systems programmer. Refer to the appropriate vendor documentation for details, and when the security logon function is enabled, specify the name of your new alternate class as follows: ENABLE SECLOGON MSGS CLASS DBCLOGON This forces TDP to use a class name of DBCLOGON instead of FACILITY for RACROUTE authorization calls. Note: Under RACF, class names can be between 4 and 8 characters in length. Under ACF2, class names are called resource names and are generally 3 characters in length. (ACF2 internally translates FACILITY to FAC, and vice versa.)
Enable the security logon function with the desired messages option: ENABLE SECLOGON MSGS or: ENABLE SECLOGON NOMSGS
4 19
See Chapter 4: Security Features Under MVS and VOS3, for more information about the TDP commands that pertain to the security logon function: ENABLE SECLOGON DISABLE SECLOGON MODIFY SECLOGON
4 20
Chapter 5:
TDP Operation
This chapter describes TDP operation. It should be used by: Operators who manage the Teradata server System programmers who create the TDPPARM data set End users
Unless stated otherwise, this information applies to all environments.
51
Chapter 5: TDP Operation Starting a TDP Under MVS or VOS3
Starting a TDP Under MVS or VOS3

To start a TDP, use the following general steps:
Step Action
1 2 3
Check that the <dbcpfx>.TDPLOAD library at your site is APF-authorized. Check that the TDPISSI module was run and completed at IPL time. (Optional) Customize the TDPPARM data set, if necessary. For example, you may want to customize the TDPPARM data set if you have installed a new TDP or if you want to make a change in the initialization options.
Start the TDP task, typically with the same name as the tdpid. Examples of TDP startup JCL are included in <dbcpfx>.PROCLIB, with the member names of TDP0 and TDP1.
For more detailed information on starting a TDP, see Teradata Tools and Utilities Installation Guide for OS/390
52
Chapter 5: TDP Operation Starting a TDP Under VM
Starting a TDP Under VM

To start a TDP, use the following general steps:
Step Action
(Optional) Customize the TDPPARM data set, if necessary. For example, you may want to customize the TDPPARM data set if you have installed a new TDP or if you want to make a change in the initialization options. Run the TDP startup program, TDP EXEC.
For more detailed information on starting a TDP under VM, see Teradata Tools and Utilities Installation Guide for VM.
53
Chapter 5: TDP Operation Initializing a TDP
Initializing a TDP
Introduction
After TDP starts, it can be initialized to communicate with the Teradata server. The environment in which TDP is to operate is defined using TDP operator commands. The TDP operator commands can be entered manually from a console or automatically in the TDPPARM data set. Minimally, the following TDP operator commands are necessary: START IFP (one for each Teradata channel processor that communicates with TDP) ENABLE LOGONS (to allow users to log on to TDP) RUN (to begin the execution phase of TDP operation; allows TDP commands, including the ones currently queued, to be executed)
You may want to use additional operator commands, such as INITIAL commands, to further define the TDP environment.
Entering Initialization Commands From TDPPARM

The TDP parameter (TDPPARM) data set can be used in any client to automatically issue all or some of the initialization commands when TDP is started. Each TDP can have its own TDPPARM data set, which can contain any TDP command. The following TDPPARM examples are included on the appropriate release tape:
Operating System TDPPARM Example Name
MVS VOS3 VM/CMS
Members TDPCMD0 and TDPCMD1 in <dbcpfx>.PROCLIB
File TDP TDPCMD
TDPPARM for MVS and VOS3

In the MVS or VOS3 environment, the job that starts TDP contains the TDPPARM DD statement, which identifies the member name of the TDPPARM data set. In the examples on the release tape, the TDP0 job calls TDPCMD0, and the TDP1 job calls TDPCMD1. Typically, the name of the job that starts TDP is the same as the tdpid.
54
TDPPARM for VM/CMS

In the VM environment, the TDP EXEC checks for a TDPPARM data set with a filename that is the same as the tdpid and a filetype of TDPCMD. If such a file exists, the TDP EXEC executes it.
Creating Your Own TDPPARM

If you do not want to use the examples on the release tape, you can create your own TDPPARM data set. It may be any data set that contains fixed, 80-character records and is accessible to QSAM (Queued Sequential Access Method). Columns 73 through 80 are reserved for traditional sequence numbers and are ignored. Records containing only blanks are ignored. If the first non-blank characters of a record are /*, the record is considered a comment and ignored. Messages that result from executing commands in the TDPPARM data set are routed to the console at which TDP was started; if the system console was used, messages are displayed at that console. If TDP was started as a batch job, messages are routed to the master console route code. If execution of any TDPPARM command results in an error, TDP displays:
TDP0113 INITIALIZATION ERRORS -- ENTER GO OR CANCEL
If you enter GO,TDP continues to run. CANCEL stops TDP. The source of the error(s) may be determined either from the responses displayed at the console or from the dump.
TDP Internal Sessions for Two Phase Commit

When TDP is initialized, two internal sessions are logged on to the Teradata server with the userid, TDPUSER. The TDPUSER name can be changed using the SET USERID command (see SET USERID, in Chapter 6). Any new userid that is substituted for TDPUSER must have the EXECUTE privilege on the DBC.TwoPCRule macro in DIPVIEWS. This privilege typically is set by the DBA for your site. For more information on 2PC and the DBC.TwoPCRule macro, see one of the following: Teradata RDBMS for UNIX Database Design and Administration Teradata DBS Reference Manual (TOS) Volume 1 (Database Design and Administration)
The two TDP-internal sessions are used for in-doubt resolution of 2PC transactions. They are established when TDP is started, and remain until TDP is shut down. These internal sessions can appear on any TDP command display that lists session-related information, such as the output from the DISPLAY SESSIONS command. The internal sessions appear in the displays with the following job name:
*TDPINT*
55
These two internal sessions comprise the In-doubt Resolution Facility (IRF) for 2PC. In order to run 2PC applications, you must have IRF enabled. The IRF can be disabled using the DISABLE IRF command to achieve a LOGON/QUIET status on the RDBMS console. However, if the IRF is disabled, your 2PC applications will not run. Note that to disable the two internal sessions, you must use the DISABLE IRF command, not the Performance Monitor ABORT SESSION command.
56
Chapter 5: TDP Operation Entering TDP Commands
Entering TDP Commands

The TDP accepts operator commands from the MVS console, MVS/TSO users, VOS3/TSS users, VM console, VM/CMS virtual machines, and CLIv2 applications. As with commands entered from TDPPARM, commands entered from the console are not executed until the RUN command is executed. Messages that result from executing operator commands entered from a console are returned to the console. Commands issued by an operator, an application, or TDP itself are recorded in the TDP joblog. When responses are written to the console or system log, it may sometimes occur that the joblog may not be perfectly ordered. Specifically, the command and its response may be reversed. When a START POOL command containing a logon string is echoed, all text after the LOGON operand is echoed as asterisks to prevent display of any password in the logon string.
57
Chapter 5: TDP Operation Entering TDP Commands on MVS and VOS3
Entering TDP Commands on MVS and VOS3

Introduction
The TDP accepts operator commands from the MVS console and from MVS/TSO or VOS3/TSS users.
Entering TDP Commands from the MVS or VOS3 Console

The MODIFY command can be used from the console to issue TDP operator commands to a TDP that is already running in the MVS or VOS3 environment. This has the advantage of not requiring TDP PC cells to execute. The syntax of the MODIFY command is:
F tdpid,TDPcommand_text
where:
Syntax element . . . Is the . . .
F tdpid
abbreviation for the MVS MODIFY command. four-character identifier associated with the TDP subsystem (for example, TDP0, TDP1, and so on) to which the command is directed. syntax of the TDP command.
TDPcommand_text
Entering TDP Commands From MVS/TSO or VOS3/TSS

TDP accepts commands from the console or any user that has the authorization to execute the commands. The TDP commands can be executed in the TSO foreground or background by: Using a TSO CALL command to call the DBCCMD user interface Using the DBCCMD CLIST that is supplied on the release tape Invoking the DBCCMD program from within batch jobs
The standard application-to-TDP interface routine supports routing a command from the MVS/TSO or VOS3/TSS address space to the requested TDP subsystem.
Using a TSO CALL Command

The parmstring used as the input argument to DBCCMD is composed of the name of the subsystem TDP to which the command is to be sent, followed by the text of the TDP command.
58
The syntax of the statement is:

CALL loadlib(DBCCMD) tdpid TDPcommand_text
where:
loadlib tdpid TDPcommand_text
name of the load library containing DBCCMD. four-character TDP subsystem identifier. text of the command to be executed by TDP.
The parmstring that includes the tdpid and the command text should have a maximum length of 120 characters, enclosed in single quotation marks.
Using the DBCCMD CLIST

To simplify the calling sequence, you can use the supplied CLIST of the same name, DBCCMD, to build the parmstring and call the DBCCMD module. The DBCCMD CLIST accepts the parmstring as the argument to the CMD keyword as follows:
DBCCMD CMD(tdpid TDPcommand_text)
where:
tdpid TDPcommand_text
four-character TDP subsystem identifier. text of the command to be executed by TDP.
Invoking DBCCMD From a Program

DBCCMD expects standard OS linkage conventions, described in the IBM publication MVS Supervisor Services and Macros Manual. The TSO CALL command invokes the called program using these conventions. In particular, Register 1 should point to a parameter list, and other registers to different areas, as follows:
Register . . . Is the . . .
R1 R13 R14 R15
pointer to parmlist. pointer to a 72-byte save area (will be used). return address to calling program. entry address of DBCCMD.
59
Construct the parmlist and argument as follows:

parmlist: argument: 1 full word containing address of argument. (Bit 0 should be set to b1 to indicate the last parameter.) +0: 2-byte length of following parmstring. +2: command parmstring, as described earlier.
DBCCMD Return Codes

DBCCMD validates the input parameters. If the command is used in the background, any response is sent to the TDP console log. If the command is run in the foreground, DBCCMD responds with a return code or an error code. Possible return and error codes are as follows:
Return Code Meaning
0 4 8 12 264 280 282
Command was successfully sent to target TDP. Required input parameter is missing or invalid. Required tdpid argument is missing or invalid. Required command text argument is missing. Target TDP does not support the command facility. Target TDP was not found. Target TDP was not available.
Since DBCCMD essentially uses the same interface that CLI uses to send work to TDP, the DBCCMD interface performs the same validation as it does for any CLI-to-TDP request. Any error codes returned other than those listed above would, therefore, indicate an internal error in DBCCMD.
Viewing Command Responses

TDP returns the command response to the issuing foreground user via cross-memory TPUT. This is the same interface used by the SEND command. The response, therefore, appears on the terminal screen as similar to any message returned to the application by TDP using the SEND command.
5 10
Chapter 5: TDP Operation Entering TDP Commands on VM
Entering TDP Commands on VM

Introduction
TDP accepts operator commands from the VM console and VM/CMS virtual machines.
Entering TDP Commands from the VM Console

It is recommended that the TDP virtual machine be established and run disconnected, with the VM system console functioning as a secondary console for the TDP virtual machine. (For the Teradata RDBMS, the VM Secondary Console Image Facility, or SCIF, is used to designate a particular virtual machine to function as a secondary console for another disconnected virtual machine.) You can enter a TDP operator command from the VM console by preceding it with the tdpid command, for example:
where:
identifier associated with the TDP (for example, TDP0, TDP1, and so on) to which the command is directed. syntax of the TDP command.
Entering TDP Commands From VM/CMS

The TDP virtual machine accepts and processes commands issued through the VM SMSG facility, a CP command used to send a special message to any virtual machine programmed to accept such a message. A user virtual machine must have the authorization to issue that TDP command and the SET SMSG ON option set. To send a TDP command with the SMSG facility, use the following syntax:
SMSG tdpid TDPcommand_text
where:
tdpid TDPcommand_te xt
identifier associated with the TDP (for example, TDP0, TDP1, and so on) to which the command is directed. syntax of the TDP command.
5 11
Upon receipt of the special message from an application virtual machine, TDP internally routes the text of the message and the source userid (virtual machine name) to its command handling facility. TDP also indicates that the origin of the command is SMSG from an application virtual machine.
Viewing Command Responses

TDP uses either the VM MSG or MSGNOH (Message, No Header) facility to return the command response to the userid that issued the command. If TDP utilizes the MSGNOH option, the returned screen display is more user friendly (see below), and therefore this option is preferable. However, this option also requires that the TDP virtual machine be granted Class B privileges in its VM/SP directory entry. If MSG is used, VM precedes the return message with a timestamp and message source id. For example, assuming two lines of output, a VM MSG response would display as follows:
hh:mm:ss MSG FROM TDPx : hh:mm:ss MSG FROM TDPx : TDPxxxx: response data TDPxxxx: response data
The resulting line display for many TDP return messages is often long enough to form more than one line. For such multiple line responses (TDP DISPLAY SESSIONS command response is an example), the output does not obviously line up or format on the screen as intended. Moreover, the MSG id information is normally appropriate only as a response to an unsolicited message received by a virtual machine. By contrast, TDP operator command response data constitutes an immediate, solicited message. For these reasons, the MSGNOH option may be preferable to MSG. If MSGNOH is used, the response message is not preceded by the timestamp and source id. Therefore, multiple line response messages do format on the screen as intended, thus appearing more user friendly. TDP determines whether it has Class B privileges during its initialization. If it does, it can use MSGNOH to return command responses. If it does not, TDP uses MSG.
Using the TDP Communication Character

To enter commands using a TDP communication character, you must first define a communication character using the SET COMCHAR command, for example:
SET COMCHAR +
where the + is the chosen communication character.
5 12
Once the communication character has been set, you can precede TDP operator command syntax with that character. Continuing with the above example, where the communication character is set to a plus sign, you would enter any TDP operator command in the following manner:
+TDP commandtext
5 13
Chapter 5: TDP Operation Entering TDP Commands from CLIv2 Applications
Entering TDP Commands from CLIv2 Applications

To issue TDP operator commands from within CLIv2 programs, you must use the CMD function available in CLIv2. For details, refer to the section on the CMD function in Teradata Call-Level Interface Version2 for Channel-Attached Systems.
5 14
Chapter 5: TDP Operation Types of TDP Command Responses
Types of TDP Command Responses

Introduction
TDP commands usually cause TDP to generate at least one, and sometimes two types of responses.
Immediate Response Commands

The first is the immediate command response type, in other words, a direct and immediate response to the command. For example, a display command causes TDP to generate a direct display response, or a direct error message response.
Process-Oriented Commands
Certain TDP commands, however, initiate a process or modify the state of a process. For example, a START IFP command causes TDP to go through the device startup sequence. In such a case, TDP first returns an immediate response, essentially indicating whether the command was accepted or not. If the command is accepted, TDP monitors the completion of the process. After the requested process has completed, TDP then sometimes issues an asynchronous status message describing the results of the process. This message is not considered a command response, and is not therefore routed to the originating userid. Instead, the message displays on the TDP console. (In most cases the user can enter other TDP display commands to obtain the new status of the process.)
5 15
Chapter 5: TDP Operation TDP Operator Message Character Set
TDP Operator Message Character Set

In a multibyte character environment, the text of operator messages produced by TDP contains only valid EBCDIC graphic characters (in the range of X40 through XEF). Other characters are replaced by a hyphen before the message is issued. The only exceptions are the control characters Shift-out and Shift-in, which are replaced by the less than (<) and greater than (>) characters, respectively. When more than one byte comprises a character, each byte is replaced by a hyphen. So the number of hyphens reflects the number of bytes, not the number of characters.
5 16
Chapter 5: TDP Operation Shutting Down a TDP
Shutting Down a TDP

Introduction
The SHUTDOWN operator command (for details see SHUTDOWN, in Chapter 6) allows you to shut down a TDP in one of the following ways:
Type of Shutdown TDP Action
Orderly Quick Cancel
Waits for all user sessions to end before shutting itself down normally. Forces a logoff of all sessions before shutting itself down normally. Shuts itself down immediately.
Canceling a TDP Under MVS or VOS3

In addition to the SHUTDOWN command, you also may use the CANCEL command to shut down a TDP. For example, to cancel a TDP named TDP1, you could use the following command:
CANCEL TDP1
The effect of this command is similar to that of the Cancel form of the SHUTDOWN command. When shutting down a TDP, you may use the CANCEL command to generate a dump. For example, to cancel TDP1 and generate a dump, use the following command:
CANCEL TDP1,DUMP
Note: Using PC IACMODE on MVS SP release 4.3 or later always produces the following message when TDP is shut down:
IEF352I ADDRESS SPACE UNAVAILABLE
This is a normal result of MVS requirements when using a system linkage index. It does not indicate an error in either TDP or MVS.
5 17
Chapter 5: TDP Operation Regulating Authority to Issue TDP Commands
Regulating Authority to Issue TDP Commands

Introduction
The distribution of authority to issue TDP commands is a site-specific issue. Following is a description of the authorization capabilities featured in TDP.
Levels of Command Issuing Authority

There are five levels of command-issuing authority that you can grant to a user: NONE DISPLAY ANY AUTHORIZ RESOLVE
AUTHORIZ Command
With the AUTHORIZ command you can grant: Authority to one, many, or all users Any or all of the five authority levels
For details, see AUTHORIZ in Chapter 6.
User Validation
To validate users, TDP performs the following steps:
Step Action
Determines if the user entry is a valid TDP command.

IF the command is . . . THEN TDP . . .
not a valid TDP command a valid TDP command
returns the standard syntax error message to the source virtual machine or user. validates the authority of the userid to issue that specific command.
5 18

Step Action
Verifies if a user is authorized to issue a specific command by searching for a matching userid listing in an existing internal table.
IF the userid is . . . THEN TDP . . .
listed in the table not listed in the table
confirms that the user is authorized to issue the command. reverts to a default authority to determine whether the userid is valid, and if so, if such a user is authorized to issue the command. The TDP command is then accepted and processed, or rejected with an error message, based on this default validation process.
5 19
5 20
Chapter 6:
TDP Commands
This chapter describes TDP operator commands and INITIAL commands used to control TDP operation. It should be used by: Operators who manage the Teradata server System programmers who create the TDPPARM data set End users
Experienced TDP users can also refer to the simplified command descriptions in the TDP chapter of the Teradata Client Command Summary. This book provides the syntax diagrams and a brief description of the syntax variables for each Teradata client utility. Refer to Appendix C: How to Read the Syntax Diagrams, for additional information on syntax diagrams. Unless stated otherwise, this information applies to all environments.
61
Chapter 6: TDP Commands TDP Operator Commands
TDP Operator Commands

How to Issue TDP Operator Commands
As discussed before, you may issue TDP operator commands from: The TDPPARM data set The system console before the RUN is executed The system console during normal TDP operation An authorized userid
TDP Operator Command Descriptions

The sections that follow describe TDP operator commands alphabetically. Each command description includes: A brief explanation of the command function The command syntax Usage notes that describe how the command operates and how it may be used An example of a command entry The normal completion message that you can expect For display commands, an example result is also included
Table 6-1 lists TDP operator commands and summarizes their function.
Table 6-1 TDP Operator Commands
Command Function
ADD CELLS/XMSCELLS ATTACH IFP COMMIT DETACH IFP DISABLE IRF DISABLE LGUX DISABLE LOGONS DISABLE POOL
Adds cells of main memory or cross memory PC cells to a TDP. Allocates an IFP to a TDP. For 2PC sessions, commits the changes in the specified in-doubt sessions. Deallocates an IFP from a TDP. Logs off TDP internal sessions that are used for 2PC in-doubt resolution. Causes TDP to stop passing logon requests to the User Logon Exit Interface (TDPLGUX). Causes TDP to stop accepting requests from applications. Logons are not enabled when TDP starts. Prevents logons to one or more pools.
62
Chapter 6: TDP Commands TDP Operator Commands Table 6-1 (Continued) TDP Operator Commands
Command Function
DISABLE SECLOGON
Disables the security logon interface to the System Authorization Facility (SAF) on MVS and VM Client systems. Stops TDP from producing messages that indicate the elapsed time spent in the application and on the server when a session ends. Causes TDP to release the reserved session capacity so that customer applications can use the maximum session capacity supported by the Teradata server. Stops TDP from producing messages when a session starts or stops. Prevents SMF information from being recorded. In the VOS3 environment, applies to SMS records.
DISABLE SESSION DETAIL DISABLE SESSION RESERVE DISABLE SESSION STATUS DISABLE SMF
DISABLE TDPSTATS DISABLE TEST
Causes TDP to stop collecting performance data. Causes TDP to stop writing the informational/diagnostic messages generated by TEST mode to the system console. TEST mode is not enabled when TDP starts. Prevents TDP from sending time to the Teradata server. Disables TDP calls to the User Transaction Collection Exit (TDPUTCE), which is enabled when TDP starts. Stops a TDP diagnostic trap. Causes TDP to stop accepting requests from the user address space exit. Causes TDP to stop passing security/ logon violations information to the User Security Interface (TDPUSEC), which is enabled when TDP starts. Displays information related to the operation of CPs started with the CCU operand. Displays all availability and usage information generated by the TDP internal memory management system. Displays the status of one or more channel processors (CPs). Displays the status of IFPs that are allocated to TDP. For 2PC sessions, displays any in-doubt sessions or any coordinators that have in-doubt sessions.
DISABLE TIME DISABLE TMON DISABLE TRAP DISABLE UAX DISABLE USEC
DISPLAY CCU DISPLAY CELLS
DISPLAY CP DISPLAY IFP DISPLAY INDOUBT
63
Command Function
DISPLAY JOB DISPLAY MODULE DISPLAY POOL DISPLAY QUEUES DISPLAY SERVER DISPLAY SESSION DISPLAY SMF
Displays the status of jobs that are communicating with the Teradata server through TDP. Displays information about a TDP module. Lists information and statistics about session pools. Displays the status of internal work queues for a TDP. Displays attributes of the server with which TDP is communicating. Displays the status of sessions that are communicating with the Teradata server through TDP. Displays the status of SMF recording. In the VOS3 environment, applies to SMS records.
DISPLAY SP DISPLAY STORAGE DISPLAY TDP DISPLAY TDPSTATS ENABLE IRF ENABLE LGUX ENABLE LOGONS ENABLE POOL ENABLE SECLOGON
Displays the status of one or more session processors (SPs). Displays information about the use of virtual storage by TDP. Displays the status of TDP. Displays the status (enabled or disabled) of TDPSTATS. Logs on TDP internal sessions that are used for 2PC in-doubt resolution. Causes TDP to begin passing logon requests to TDP User Logon Exit Interface (TDPLGUX). Causes TDP to begin accepting logon requests from applications. Logons are not enabled when TDP starts. Enables logons to one or more pools. Enables the security logon interface to the System Authorization Facility (SAF) on MVS and VM Client systems. Causes TDP to produce messages that indicate the elapsed time spent in the application and on the server when a session ends. Causes TDP to reserve session capacity for recovery processing in the event of the failure of an IFP, thus reducing the maximum number of sessions that it can control during its current run. Causes TDP to produce messages when a session starts or stops.
ENABLE SESSION DETAIL ENABLE SESSION RESERVE
ENABLE SESSION STATUS
64
Command Function
ENABLE SMF
Causes SMF information to be recorded. In the VOS3 environment, applies to SMS records.
ENABLE TDPSTATS ENABLE TEST
TDP to begin collecting performance data. Causes TDP to start writing the informational and diagnostic messages generated by TEST mode to the system console. TEST mode is not enabled when TDP starts.
ENABLE TIME ENABLE TMON ENABLE TRAP ENABLE UAX
Causes TDP to send time to the Teradata server. Enables TDP calls to the User Transaction Collection Exit (TDPUTCE), which is enabled when TDP starts. Establishes a TDP diagnostic trap. Causes TDP to pass requests to the user address space exit. Currently, only connect or logon requests are passed. Causes TDP to start passing security/ logon violations information to the User Security Interface (TDPUSEC), which is enabled when TDP starts. Forces one or more sessions to be logged off the Teradata server. Ends a pool immediately by forcing the logoff of pool sessions that are in use by application programs. Increases or decreases the number of sessions in a pool. Changes the messages display option for the security logon interface to the System Authorization Facility (SAF) on MVS and VM Client systems. For 2PC sessions, rolls back the changes in the specified in-doubt sessions. Causes operator commands entered from TDPPARM or the system console to be executed. Establishes the character set with which userids and logon strings are specified in TDP commands. Establishes or changes the communication character that is used to link operator command entry with a TDP to be initialized. Establishes the maximum number of sessions that TDP can control during its current run. Changes the virtual storage limits used by TDP.
ENABLE USEC
LOGOFF LOGOFF POOL MODIFY POOL MODIFY SECLOGON
ROLLBACK RUN SET CHARSET SET COMCHAR
SET MAXSESS SET STORAGE
65
Command Function
SET USERID SHUTDOWN START IFP START POOL STOP IFP
Establishes the Database userid for TDP internal sessions. Stops TDP operation. Causes TDP to begin communicating with an IFP. Establishes and enables a session pool. Causes TDP to stop communicating with an IFP.
The sections that follow contain detailed descriptions of each TDP operator command.
66
Chapter 6: TDP Commands ADD CELLS/XMSCELLS
ADD CELLS/XMSCELLS
Function
Adds cells of main memory to a TDP for its internal use. The ADD XMSCELLS command can be specified in the MVS environment to increase the number of cells reserved for use by the IOMODE PC interface to transfer data between the application and TDP address spaces. Except for a small number of cells used for specialized purposes, all cells are allocated from 31bit storage
Syntax
ADD CELLS XMSCELLS SIZE SIZ NUMBER NUM cellsize NUMBER NUM number_of_cells SIZE SIZ cellsize
FZAPB001
number_of_cells
where:
CELLS XMSCELLS cellsize
specification that the maximum number of cells are to be increased. specification that the number of cells reserved for use by the IOMODE PC interface are to be increased. size, in decimal, of the cells to be added. Range is 1 through 32760.
number_of_cells
number, in decimal, of cells to be added. Size range is 1 through any multiple of 16.
Usage Notes
The ADD CELLS and ADD XMCELLS commands may be used to improve TDP throughput when throughput has degraded. Use the DISPLAY CELLS command to display excessive GETMAIN or wait counts, which can reduce TDP throughput. Note that the size argument must specify an existing cell size. To obtain the cell size, issue the DISPLAY CELLS command. You can add numberofcells to the cellsize cell pool by issuing the ADD command.
67
Chapter 6: TDP Commands ADD CELLS/XMSCELLS
XMSCELLS are used in MVS only.
Example
ADD CELLS SIZ 80 NUM 16
Completion Message
TDP0527 16 MEMORY CELLS OF SIZE 80 SUCCESSFULLY ADDED
68
Chapter 6: TDP Commands ATTACH IFP
ATTACH IFP
Function
Allocates an IFP to a TDP.
Syntax
ATTACH ATT ifpname
FZAPB002
where:
ifpname
IFP as IFPnnnn, where nnnn is the device number of the even-numbered IFP or device, in three or four hexadecimal digits.
Usage Notes
The devices for an IFP may be either explicitly or dynamically allocated. Dynamic allocation is the more usual operation since no explicit allocation is required: TDP automatically allocates the required devices. Explicit allocation requires that the following be performed prior to ATTACHing the IFP:
If using this operating system . . . Do the following . . .
MVS VOS3
Include two DD statements in the JCL procedure that is used to start TDP. The DD statements should be in this format: //IFPnnnn DD UNIT=nnn One of these statements is for the even IFP device number, the other for the corresponding odd IFP device number. If a four-digit device number is specified for the UNIT keyword, MVS requires that a slash precede the digits, as in UNIT=/nnnn
VM
Include two FILEDEFs in the TDP startup EXEC. The FILEDEFs should be in this format: FILEDEF IFPnnnn DUMMY IFP nnnn I
69
Chapter 6: TDP Commands ATTACH IFP
For either operating system, IFPnnnn corresponds to the ifpname used in the ATTACH command. IFPnnn and IFP0nnn are equivalent. That is, the command may specify one form and the static system definition may specify the other. Before any session can be assigned to a newly attached IFP, the following must occur: The RUN command must be executed A START IFP command must be executed for the IFP TDP must respond with an IFP STARTED message
Because an IFP is implicitly attached to a TDP by the RUN/START IFP command execution sequence, the explicit use of the ATTACH IFP command is unnecessary under normal operating conditions.
Example
ATT IFP490
Completion Message
TDP1356 IFP490 ATTACHED
6 10
Chapter 6: TDP Commands AUTHORIZ
AUTHORIZ
Function
Grants authority to users at any or all of the five authority levels.
Syntax
AUTHORIZ AU
NONE ALL userid job N DISPLAY D ANY A AUTHORIZ AU RESOLVE R

FZAPB074
where:
userid
Virtual machine name MVS/TSO userid for foreground MVS/TSO, VOS3/TSS userid, or MVS or VOS3 jobname (IMS control region or CICS job).
ALL
way to set the default authority for all users for whom no other specific authority has been granted. Note that the ALL authority does not imply RESOLVE or AUTHORIZ; those authorities are set separately.
job NONE
jobname for the 2PC job (IMS control region or CICS job) that is being authorized. way to deny authority to issue TDP commands to the specified userid(s) or to ALL. It reverses any authority.
DISPLAY ANY AUTHORIZ
way to grant authority to issue display commands only. way to grant authority to issue any TDP command except AUTHORIZ and RESOLVE. way to grant authority to issue the AUTHORIZ command.
6 11
Chapter 6: TDP Commands AUTHORIZ

This option enables the target userid(s) to authorize others to issue TDP commands. If you do not want to use the AUTHORIZ option, you can choose to use the ANY or DISPLAY options. RESOLVE way to indicate that the 2PC coordinator(s) are authorized to perform automatic in-doubt resolution.
Usage Notes
At the start, the system is set to the default authority level of NONE. You may execute the AUTHORIZ command from:
Location When
TDPPARM data set System operator console A command interface user with AUTHORIZ authority
During TDP initialization After TDP initialization After TDP initialization
Example 1
AU ALL DISPLAY
6 12
Chapter 6: TDP Commands COMMENT
COMMENT
Function
Adds comments to the JOBLOG and GTF, if being used.
Syntax
COMMENT COMMEN COMME COMM COM
text
FZAPZ001
where:
text
is a comment consisting of all characters until the end of the command
Usage Notes
If the comment is to be written to GTF, the USR GTF option must be specified both when GTF is started and when the trace records are formatted. The GTF JOBNAMEP option might also to warranted to limit tracing of user records to the desired TDP
Example 1
COMMENT Begin performance test 6
Completion Message
TDP2062 "COMMENT" COMMAND COMPLETE
6 13
Chapter 6: TDP Commands COMMIT
COMMIT
Function
Commits a single 2PC in-doubt session or all 2PC in-doubt sessions for a specified coordinator.
Syntax
COMMIT ALL SESSION number COORD name HOST id
FZAPA003
where:
ALL SESSION number name
specification that all in-doubt sessions for the coordinator are to be committed. specification that only one session is to be committed. number of the in-doubt session to be committed. coordinator name in alphanumeric characters. In MVS, the coordinator name is either: The CICS VTAM application name, or The IMS system id
id
(optional) logical host ID, a decimal number. The default is host ID of the current TDP.
Usage Notes
The COMMIT command includes a LOGOFF action by default. The result of this command is recorded in the InDoubtResLog on the Teradata server.
Example 1
COMMIT ALL COORD IMS
Completion Message
TDP0419 ALL IN-DOUBT SESSIONS FOR COORDINATOR IMS COMMITTED
6 14
Chapter 6: TDP Commands COMMIT
Example 2
COMMIT SESSION 4321 COORD CICSS2
Completion Message
TDP0402 SESSION 4321 COMMITTED
6 15
Chapter 6: TDP Commands DETACH IFP
DETACH IFP
Function
Deallocates an IFP from a TDP.
Syntax
DETACH DET ifpname
FZAPB004
where:
ifpname
IFP as IFPnnnn, where nnnn is the device number of the even-numbered IFP device, in three or four hexadecimal digits.
Usage Notes
If the devices were dynamically allocated by the ATTACH or START commands, they are de-allocated. The DETACH IFP command is successful only if the IFP identified is currently attached to TDP and the IFP is stopped. The IFP is considered stopped if the IFP was never started, or if a STOP IFP operator command was successfully processed for the IFP.
Example
DET IFP490
Completion Message
TDP1357 IFP490 DETACHED
6 16
Chapter 6: TDP Commands DISABLE IRF
DISABLE IRF
Function
Disables TDP internal sessions that are used for 2PC in-doubt resolution.
Syntax
DISABLE DISA IRF
FZAPB005
Usage Notes
This command disables the In-doubt Resolution Facility (IRF), which consists of two TDP-internal sessions used for 2PC in-doubt resolution. The result of the DISABLE IRF command is that the two TDP-internal sessions are logged off from the Teradata server. If there are no other sessions logged on and the DISABLE IRF command is completed, the status display on the RDBMS console changes to LOGON/QUIET. This LOGON/QUIET state is necessary for the Reconfiguration program to be run. Use the DISABLE IRF command to log off the internal sessions, which have the jobname of *TDPINT*. After executing the Reconfiguration program, use the ENABLE IRF command to re-establish the two internal sessions. If the IRF is disabled, then automatic in-doubt resolution and the TDP commands for manual in-doubt resolution (COMMIT, ROLLBACK, and DISPLAY INDOUBT) are rejected. Note that if the IRF is disabled, you are still able to use manual in-doubt resolution if you use a CLIv2 application or the TPCCONS utility. Note: To disable the two internal sessions, you must use this TDP command, DISABLE IRF. Do not use the Performance Monitor command, ABORT SESSIONS, to log off TDP internal sessions.
Example
DISA IRF
Completion Message
TDP0445 sessiontype SESSION ENDED where sessiontype is either RBM (Resolver Base Module) or LOG. Usually, one message is displayed for the RBM session and one for the LOG session.
6 17
Chapter 6: TDP Commands DISABLE LGUX
DISABLE LGUX
Function
Causes TDP to stop passing logon requests to the User Logon Exit Interface (TDPLGUX). The command also detaches the LGUX task. This allows a new version of TDPLGUX to be brought online without having to stop TDP and then restart it.
Syntax
DISABLE DISA
LGUX
FZAPB006
Usage Notes
The TDPLGUX is enabled when TDP starts. If the DISABLE LGUX command is subsequently executed, TDP stops passing logon requests to TDPLGUX and deletes the TDPLGUX module from main memory.
Example
DISA LGUX
Completion Message
TDP0912 TDP LOGON USER EXIT INTERFACE DISABLED
6 18
Chapter 6: TDP Commands DISABLE LOGONS
DISABLE LOGONS
Function
Causes TDP to stop accepting logon requests from applications.
Syntax
LOGONS
FZAPB007
DISABLE DISA
Usage Notes
When TDP starts, logons are not enabled. Logons are enabled during TDP initialization (see Initializing a TDP on page 5-4 for more information) using the ENABLE LOGONS operator command. If the DISABLE LOGONS command is executed after logons are enabled, a logon request from an application program is returned to the application with an error message indicating that logons are currently not allowed. Sessions that are logged on when the DISABLE LOGONS command is executed are allowed to continue to completion.
Example
DISA LOGONS
Completion Message
TDP0856 LOGONS DISABLED
6 19
Chapter 6: TDP Commands DISABLE POOL
DISABLE POOL
Function
Prevents logons to one or more pools.
Syntax
DISABLE DISA POOL ID poolid ALL
FZAPB008
where:
poolid ALL
unique identifier of the pool that is to be disabled. request that all pools be disabled.
Usage Notes
The DISABLE POOL command is used to prevent applications from logging on to pool sessions. Once a pool is disabled, any application logon request that would normally be satisfied by a session from the pool is rejected with an error code. When a pool is disabled, any session that is in use is allowed to run until the using application logs off. At that time, the session is returned to the pool. To enable applications to log on to pool sessions, use the ENABLE POOL command.
Example
DISA POOL ID ACTR04
Completion Message
TDP0881 POOL ID: ACTR04 IS NOW DISABLED
6 20
Chapter 6: TDP Commands DISABLE SECLOGON
DISABLE SECLOGON
Function
Disables the security logon function that provides an interface to the System Authorization Facility (SAF) on MVS and VM client systems.
Syntax
DISABLE DISA
SECLOGON
FZAPA093
Usage Notes
TDP responds to the DISABLE SECLOGON command with a TDP2108 message indicating the new status of the security logon function and its messages option.
Example
DISABLE SECLOGON
Completion Message
TDP2108 SECLOGON: DISABLED, DIAGNOSTIC MSGS: DISABLED
6 21
Chapter 6: TDP Commands DISABLE SESSION DETAIL
DISABLE SESSION DETAIL

Function
Stops TDP from producing messages when a session ends that indicate the elapsed time that the session spent within the application and within the server.
Syntax
DISABLE DISA SESSION DETAIL DET
FZAPA096
Usage Notes
When TDP starts, Session Detail is disabled. To subsequently enable Session Detail, use the ENABLE SESSION DETAIL command. The current setting may be displayed using the DISPLAY TDP command. When Session Detail is enabled and a session ends, a TDP0846 message is produced to indicate the total elapsed time that the session spent within the application and within the server.
Example
DISABLE SESSION DETAIL
Completion Message
TDP0401 SESSION DETAIL HAS BEEN DISABLED
6 22
Chapter 6: TDP Commands DISABLE SESSION RESERVE
DISABLE SESSION RESERVE

Function
Causes TDP to release the reserved session capacity so that customer applications can use the maximum session capacity supported by the Teradata server.
Syntax
DISABLE DISA SESSION RESERVE RES
FZAPB009
Usage Notes
When TDP starts, the Session Reserve is enabled. To subsequently disable Session Reserve, use the DISABLE SESSION RESERVE command. When Session Reserve is enabled and more than one SP is operational, TDP reserves a number of sessions equal to the capacity of one SP. This is to ensure that if a single SP fails, all user sessions allocated to the failed SP can be switched to other SPs that were started by this TDP. This command affects the value of DBC/1012 MAXSESS, as displayed in the output from the DISPLAY TDP command. This is a separate limit from the value of TDP MAXSESS, which is controlled by the SET MAXSESS command. The maximum number of sessions that can be logged on through this TDP is the lower of these two values. When the maximum number of sessions is already logged on to TDP, any new logon request from an application is refused with an error code of CLI0513.
Example
DISA SESSION RES
Completion Message
TDP0401 SESSION RESERVE HAS BEEN DISABLED
6 23
Chapter 6: TDP Commands DISABLE SESSION STATUS
DISABLE SESSION STATUS

Function
Stops TDP from producing a message when a session starts or ends.
Syntax
DISABLE DISA SESSION STATUS STA
FZAPA097
Usage Notes
When TDP starts, Session Status is disabled. To subsequently enable Session Status, use the ENABLE SESSION STATUS command. The current setting may be displayed using the DISPLAY TDP command. If Session Status is enabled, a TDP0899 message is produced when a session starts, and a TDP0898 message is produced when a session ends. When a session to be used for session pool assignment is started, a TDP0800 message is produced; when such a session ends, a TDP0801 message is produced. These messages had previously been controlled by the ENABLE TEST command. For compatibility, they continue under TEST control until an ENABLE SESSION STATUS or DISABLE SESSION STATUS is issued, after which TEST has no effect on these messages.
Example
DISABLE SESSION STATUS
Completion Message
TDP0401 SESSION STATUS HAS BEEN DISABLED
6 24
Chapter 6: TDP Commands DISABLE SMF
DISABLE SMF
Function
Prevents all System Management Facility (SMF) records from being recorded. You can also disable the recording of specific subtypes of SMF records. In VOS3, applies to SMS records.
Syntax
DISABLE DISA SMF ALL SUBn
FZAPB010
where:
Syntax element . . . Is the specification that recording for . . .
ALL SUBn
all SMF record types is to be disabled. certain SMF types is to be disabled Available subtypes are as follows: 1: Session Termination 2: Security Violation 3: IFP Activity 4: TDP Shutdown 5: Structure-protocol termination
Usage Notes
When TDP starts, SMF recording is enabled for subtypes 1 through 4. To disable SMF recording, use the DISABLE SMF command. The ALL argument is the default for this command. If you enter just the DISABLE SMF command with no arguments, recording is disabled for all SMF record subtypes. To disable the recording of a specific SMF record subtype, use the SUBn argument, where n is the number of the SMF record type to have its recording disabled.
Example 1
DISA SMF
6 25
Chapter 6: TDP Commands DISABLE SMF
Example 2
DISA SMF SUB1
Completion Message
TDP0594 SMF RECORDING DISABLED
6 26
Chapter 6: TDP Commands DISABLE TDPSTATS
DISABLE TDPSTATS
Function
Causes TDP to discontinue collection of statistical and performance information.
Syntax
SET COMCHAR COM comchar OFF
FZAPB043
Usage Notes
When TDP starts, TDPSTATS is not enabled. TDPSTATS is enabled by executing the ENABLE TDPSTATS command. Use the DISPLAY TDPSTATS command to display the current status of TDPSTATS.
Example
DISA TDPSTATS
Completion Message
TDP2501 TDP THROUGHPUT STATISTICS REPORTER DISABLED
6 27
Chapter 6: TDP Commands DISABLE TEST
DISABLE TEST
Function
Causes TDP to discontinue writing informational or diagnostic messages to the system console.
Syntax
DISABLE DISA
TEST
FZAPB011
Usage Notes
When TDP starts, TEST mode is not enabled. TEST may be enabled by executing the ENABLE TEST operator command. If the DISABLE TEST command is executed after TEST is enabled, informational messages produced by TEST mode are no longer written to the system console.
Example
DISA TEST
Completion Message
TDP0542 TEST MODE DISABLED
6 28
Chapter 6: TDP Commands DISABLE TIME
DISABLE TIME
Function
Prevents TDP from sending time to the Teradata server.
Syntax
DISABLE DISA TIME TIM
FZAPB012
Usage Notes
If neither an ENABLE TIME nor a DISABLE TIME command is issued, the default action is specified in the HSISPB. While the HSISPB can be customized as necessary, as distributed, DISABLE TIME is the default. You can use the ENABLE TIME command to enable the option again. If you are using a Teradata RDBMS release between V1R4.1 and V1R5.1, inclusive, the ENABLE TIME feature is supported only for DBC/1012 configurations controlled by a Model 2 Access Module Processor (AMP) or below. If the configuration at your site does not include a Model 2 AMP, you may want to include the DISABLE TIME command in the TDPPARM data set to reduce meaningless channel traffic. For releases prior to V1R4.1 or V1R5.2 and above, ENABLE or DISABLE TIME function as expected. To set the time, use the RDBMS console command, SET TIME.
Example
DISA TIM
Completion Message
TDP0596 HOST TO DBC TIME MESSAGES ARE: DISABLED
6 29
Chapter 6: TDP Commands DISABLE TMON
DISABLE TMON
Function
Disables TDP calls to the User Transaction Collection Exit (TDPUTCE) routine, which is used to collect statistics about requests and responses that traverse TDP.
Syntax
DISABLE DISA TMON
FZAPB013
Usage Notes
When TDP starts, the TDPUTCE is enabled. If the DISABLE TMON command is subsequently executed, TDP stops passing requests and responses to TDPUTCE and deletes the TDPUTCE module from main memory.
Example
DISA TMON
Completion Message
TDP0922 TDP USER MONITOR EXIT INTERFACE DISABLED
6 30
Chapter 6: TDP Commands DISABLE TRAP
DISABLE TRAP
Function
Disables a previously-enabled diagnostic trap.
Syntax
DISABLE TRAP NAME name
FE0CA050
where:
name
name of a previously-established trap
Usage Notes
A trap is established by the ENABLE TRAP command. DISABLE TRAP is intended for use in consultation with NCR Customer Support personnel.
Example
DISABLE TRAP NAME TRAP0001
Completion Message
TDP0401 TRAP TRAP0001 HAS BEEN DISABLED
6 31
Chapter 6: TDP Commands DISABLE UAX
DISABLE UAX
Function
Causes TDP to stop passing requests to the User Address Space Exit Interface (TDPUAX).
Syntax
DISABLE DISA
UAX
FZAPB014
Usage Notes
The TDPUAX is available only in the MVS or VOS3 environment. If you use the DISABLE UAX command in the VM environment, the following message is returned:
TDP0506 UNKNOWN OPERAND TO THE DISABLE COMMAND: UAX
The TDPUAX is enabled by the ENABLE UAX command.
Example
DISA UAX
Completion Message
TDP0597 TDP USER ADDRESS SPACE EXIT INTERFACE NOW DISABLED
6 32
Chapter 6: TDP Commands DISABLE USEC
DISABLE USEC
Function
Causes TDP to stop passing security and logon violations information detected by the Teradata server and by the User Logon Exit Interface (TDPLGUX) to the TDP User Security Interface (TDPUSEC). The command also detaches the TDPUSEC task. This allows a new version of TDPUSEC to be brought on-line without having to stop TDP and then restart it.
Syntax
DISABLE DISA USEC
FZAPB015
Usage Notes
When TDP starts, the TDPUSEC is enabled. If the DISABLE USEC command is subsequently executed, TDP stops passing security and logon violations information to the TDPUSEC and deletes the TDPUSEC module from main memory.
Example
DISA USEC
Completion Message
TDP0902 TDP USER SECURITY EXIT INTERFACE DISABLED
6 33
Chapter 6: TDP Commands DISPLAY CCU
DISPLAY CCU
Function
Displays limits used during operation of CCU-type CPs.
Syntax
DISPLAY CCU
FE0CA046
Usage Notes
The maximum number of channel blocks for an I/O, the maximum size of a channel block, and the number of checksum rejections at which the CP will become unusableare displayed. The values may be set using the INITIAL CCU MAXBLKNM, INITIAL CCU MAXBLKSZ, and INITIAL CCU MAXCKSUM commands.
Example
DISPLAY CCU
6 34
Chapter 6: TDP Commands DISPLAY CELLS
DISPLAY CELLS
Function
Displays cell availability and usage information generated by the TDP internal memory management system. The information is accumulated from the time the current TDP was started; there is no command to reset it.
Syntax
DISPLAY D CELLS CEL
VERIFY VER
FZAP B016
where:
VERIFY
specification that the actual number of MVS PC cells that are currently in use is to be displayed. This option is intended for use in consultation with NCR support personnel. Use of this option normally has no effect on the accuracy of the information and simply increases system overhead.
Usage Notes
The initial number of cells may be specified using the TDP ADD CELLS, ADD XMSCELLS, and INITIAL IOBUFS commands in the TDPPARM dataset. The number of cells may be dynamically increased using the TDP ADD CELLS and ADD XMSCELLS commands. There is no way to reduce the number of cells When you execute the DISPLAY CELLS command, TDP displays the following information about cells in the memory management system:
Column . . . Contains the . . .
CELSZ AVAIL INUSE MXUSE
size, in bytes, of a cell. number of cells not currently in use. number of cells currently in use. maximum number of cells used at any one time. This will include any cells reserved for IOMODE PC interface usage.
6 35
Chapter 6: TDP Commands DISPLAY CELLS

Column . . . Contains the . . .
GMAIN
number of times a cell was dynamically obtained. Normally, if no cell is available the TDP process will be suspended until a cell is made available, but under certain circumstances a cell will be dynamically obtained to satisfy the request. A cell dynamically obtained is freed when no longer in use. PC cells are never dynamically obtained. Overall throughput may be impacted since dynamically obtaining a cell is less efficient that reusing an available cell. The larger the number of dynamic actions, the greater the potential performance impact.
PC #WAITS
number of cells reserved for use by the IOMODE PC interface at any one time. number of times a TDP process was suspended because no cells were available. Normally, if no cell is available the TDP process will be suspended until a cell becomes available. Overall throughput may be impacted since a suspended TDP process is not available to process other work. The larger the number of suspensions, the greater the potential performance impact
If INITIAL IACMODE PC is specified, information about cross-memory cell shortages is also displayed. That information could be: TDP1250, which indicates the number of times that at least one of the three cross-memory cell pools was exhausted. Each request requires one cell from each of the three cross-memory cell sizes. If any of the sizes is unavailable, the request must wait. TDP1251, which indicates the number of times that no cell was available to process a request that required more than one cell from the largest crossmemory cell pool
Except for a small number of cells used for specialized purposes, all cells are allocated from 31bit storage If all available cells of a given size are used at one time, the following message is issued:
TDP0021 **WARNING** 100% of <size> BYTE CELLS IN USE
Such a message appears at most once for each cell size.
Example
D CEL
Completion Message
The result of the DISPLAY CELLS command is in the following format:
TDP0501 CELSZ AVAIL INUSE MXUSE GMAIN PC #WAITS
6 36
Chapter 6: TDP Commands DISPLAY CELLS TDP0528 TDP0528 TDP0528 TDP0528 TDP0528 TDP0528 TDP0528 TDP0528 TDP0529 TDP1250 TDP1251 TDP0500 00064 00498 00002 00042 0000000 00000 00000 00128 00496 00004 00006 0000000 00000 00000 00240 00499 00001 00043 0000000 00000 00000 00256 00491 00209 00247 0000000 00200 00000 00352 00499 00201 00243 0000000 00200 00000 00480 00005 00001 00005 0000000 00000 00000 00992 00498 00392 00890 0000000 00390 5265* 12272 00004 00002 00006 0000000 00000 12272* OVERSIZE CELLS, INUSE: 1 MAXUSE: 0 GETMAINS: 1 WAITS FOR INITIAL PC CELLS: 0 WAITS FOR ADDITIONAL PC CELLS: 0 ADDITIONAL I/O CONTROL BLOCKS OBTAINED: 0
Notes on the Example

TDP1250 and TDP1251 appear only if IACMODE PC is specified. TDP0500 appears only if TEST is enabled, IOMODE IOSDRIVR is specified, and CIC-type CPs are being used. Note that the I/O Control Blocks mentioned are not IOBUFS. The #WAITS entry that contains an asterisk to the right of the five-digit number (00001*) indicates that TDP is currently waiting for the 12,272 byte cell size. The #WAITS entry that contains an asterisk in the last position of the five-digit number (5625*) indicates that the #WAITS counter has wrapped (that is, it is a very large number).
6 37
Chapter 6: TDP Commands DISPLAY CHECKSUM
DISPLAY CHECKSUM
Function
Displays the status of checksum validation of data transfers to and from the Teradata server when using CCU-type CPs.
Syntax
DISPLAY D CHECKSUM CHE
EF03A072
Usage Notes
Use the SET CHECKSUM command to change the CHECKSUM setting.
Message
TDP2036 CHECKSUM IS AUTOMATIC BY CP
6 38
Chapter 6: TDP Commands DISPLAY CP
DISPLAY CP
Function
Displays the status of channel processors (CPs) that are assigned to this TDP. While both this and the DISPLAY IFP command are concerned with the same underlying information, this command presents more detail for diagnostic purposes.
Syntax
DISPLAY D A LOCATION PROTOCOL SELECT
FZAPB101
CP PNUM xxxx NAME cpname REQUESTS DETAIL
where:
xxxx
four-character hexadecimal CP id for which information is to be displayed. If neither NAME nor PNUM is specified, information for all CPs is displayed.
cpname
six or seven character CP name for which information is to be displayed. The name is that which had been specified on a previous TDP START IFP command. If neither NAME nor PNUM is specified, information for all CPs is displayed.
REQUESTS DETAIL
indication that a list of all pending and active requests for the CP is to be displayed. indication that diagnostic information for the CP is to be displayed. This option is intended for use in consultation with NCR customer support personnel. Note: The associated information requires internal knowledge of TDP to properly interpret. Without such knowledge, misleading conclusions are probable. Time can be saved by heeding this recommendation.
6 39

LOCATION
indication that diagnostic information concerning the location of the CP within the server is to be displayed. If such information is not available, nothing is added to the display. This option is intended for use in consultation with NCR customer support personnel. Note: The associated information requires internal knowledge of TDP to properly interpret. Without such knowledge, misleading conclusions are probable. Time can be saved by heeding this recommendation.
PROTOCOL
indication that diagnostic information for the communication protocol being used by the CP is to be displayed. This option is intended for use in consultation with NCR customer support personnel. Note: The associated information requires internal knowledge of TDP to properly interpret. Without such knowledge, misleading conclusions are probable. Time can be saved by heeding this recommendation.
SELECT
indication that diagnostic information for the selection of the CP for sending requests is to be displayed. This option is intended for use in consultation with NCR customer support personnel. Note: The associated information requires internal knowledge of TDP to properly interpret. Without such knowledge, misleading conclusions are probable. Time can be saved by heeding this recommendation.
CHECKSUM
indication that the status of checksum in effect for a CCU-type CP is to be displayed. The SET CHECKSUM command may be used to control the use of checksum.
Usage Notes
The following information is always displayed, as applicable: CP number and corresponding IFP name. Status of the CP, as follows:
Status Definition
NOT OPERATIONAL OPERATIONAL
Communication with the server is not established. Communication with the server has been established.
6 40

Status Definition
INITING SYNCING
Operational but the communication protocol between TDP and the device is being initialized. Operational but the status of TDP has not yet been synchronized with that of the server.
The number of active or pending requests.
The following information is meaningful when you consult with NCR customer support personnel; when applicable, it is presented to aid in diagnosis without having to recreate the problem. This information is displayed, according to the options specified in the command:
IF you select this option . . . THEN TDP displays . . .
REQUESTS
For all active requests sent to this CP: Request number Session number State, as follows: State ACTIVE PENDING Definition The request has been sent. The request is waiting to be sent.
DETAIL
The number of messages and bytes sent on the output device and the number of messages and bytes received on the input device. If appropriate for internal operation, the total number of messages and bytes transferred.
6 41

IF you select this option . . .
THEN TDP displays . . .
DETAIL (continued)
For CPs requiring the CCU operand on the START command, I/O buffer utilization information for each device. For the output device, if not meaningful, the information may not be displayed. If meaningful, this information includes the following: The number of I/O buffers associated with any current I/O The number of I/O buffers associated with any I/O being constructed The maximum number of buffers used for any one I/O The number of times an I/O was limited by the maximum number of blocks per I/O. The number of times an I/O was limited by the maximum amount of virtual storage available for I/O. The number of times a delay was incurred to wait for an I/O buffer For the input device, this information includes the following, if meaningful: The number of I/O buffers associated with any current I/O The maximum number of buffers used for any one I/O The number of times an I/O was limited by the maximum number of blocks per I/O The number of times an I/O was limited by the maximum amount of virtual storage available for I/O The number of attempts to obtain an I/O buffer that failed The number of times a delay was incurred to wait for a TDP 992-byte cell Whether there is currently a delay waiting for a 992-byte cell
DETAIL (continued)
If communication has been lost, a count of the number of times such an event has occurred for this CP, and the status of the output and input devices as follows:
Status Definition
DOWN RECOVERED INVOLVED OBLIVIOUS
The device has stopped responding. A down device has begun responding. The device will be recovered but has not yet been found to be down. The device is not affected by the loss of communication of the other device.
6 42

For CPs requiring the CCU operand on the START command, if the communication protocol is being initialized, the protocol structure that is expected from the server. If synchronization is in progress:
IF . . . THEN TDP displays . . .
a Configuration Request is to be sent SPs are being synchronized
which CP will be used. The number of SPs remaining. Whether all or only dependent SPs are involved.
If this CP has dependent SPs, the extended dependency id and a list of the SP numbers. LOCATION If the server supplies information concerning the physical location of the CP, the following is presented: The cabinet The processor-id within the cabinet If the server supplies no such information, nothing is displayed.
6 43

PROTOCOL
For CPs requiring the CCU operand on the START command: The routing factor The maximum number of bytes per block The maximum number of bytes per structure The type of channel attachment For CPs not requiring the CCU operand: The maximum number of bytes per block and the servers default value The maximum number of blocks per I/O and the servers default value
SELECT
When appropriate for the current operation: The relative power of this CP to other CPs The origin of other CPs when this CP was started Otherwise, no information is displayed.
CHECKSUM
The setting of the last SET CHECKSUM command (ON, OFF, or AUTO). For AUTO, ACTIVE indicates that checksum has been activated by the server, and INACTIVE indicates that it has not. For AUTO, the number of times that the server has activated checksum is also indicated. If any checksums have been processed, the number of messages sent to the server with checksums, and the number of messages received from the server with checksums is also indicated."
Example
D CP
Completion Message
TDP1280 CPNUM 000E: (IFPB92): OPERATIONAL TDP1281 ACTIVE REQUESTS: 1, PENDING REQUESTS: 0 TDP1280 CPNUM 000F: (IFPB90): OPERATIONAL
6 44
Chapter 6: TDP Commands DISPLAY IFP
DISPLAY IFP
Function
Displays the status of IFPs that are allocated to TDP.
Syntax
DISPLAY D IFP ifpname
STATE
FZAPB017
where:
IFP ifpname
specification that a summary of the desired status of all active IFPs be displayed. IFP whose information is to be displayed as IFPnnnn, where nnnn is the device number of the even-numbered IFP device, in three or four hexadecimal digits. option that is used for diagnostic purposes only and should be used in consultation with NCR customer support personnel.
STATE
Usage Notes
When the DISPLAY IFP form of the command is executed, for each active IFP, TDP displays a summary line containing: IFP name The desired status of the IFP. Normally this reflects the completion of the last command affecting the IFP (STARTED or STOPPED) or that the command is ongoing (STARTING or STOPPING). If the IFP is unavailable on the Teradata server, HALTED or HALTING may appear. Other possible states are: COMM LOST indicates that communication has been lost SYNCING indicates that communication is being restored TEMP ERROR indicates that an I/O error occurred PERM ERROR indicates that the IFP is not currently configured on the Teradata server
When the DISPLAY ifpname form of the command is executed, TDP displays the name and status of the specified IFP, plus the number of blocks, messages, packets, and bytes that the IFP has sent to, and received from, the Teradata server.
6 45
Chapter 6: TDP Commands DISPLAY IFP
Note that the DISPLAY IFP command displays the desired status, for example, a status that has been set with the START IFP or STOP IFP command. It may not reflect the current or actual status of the IFP it reflects only what the IFP has been set to.
Example 1
D IFP
Completion Message
TDP0517 IFP490 STARTED TDP0517 IFP492 STARTED
Example 2
D IFP490
Completion Message
TDP0519 IFP490 OUTPUT BLOCKS 29535 MESSAGES 338991 BYTES 62052464 TDP0519 STARTED INPUT BLOCKS 28099 MESSAGES 29834 BYTES 3730779 29501 PACKETS 29818 PACKETS
6 46
Chapter 6: TDP Commands DISPLAY INDOUBT
DISPLAY INDOUBT
Function
Displays any 2PC in-doubt sessions or any coordinators that have in-doubt sessions.
Syntax
DISPLAY D INDOUBT IND SESSIONS COORD name HOST id COORDS HOST id
FZAPB018
RESOLVED
where:
SESSIONS name
specification that all currently in-doubt sessions be displayed for a coordinator. coordinator name in alphanumeric characters. In MVS, the coordinator name is either: The CICS CTAM application name, or The IMS system id
id
(optional) logical host ID, a decimal number. The default is the host ID of the current TDP.
RESOLVED
specification that the display include sessions that were manually resolved, as well as sessions that are currently in-doubt, for a coordinator. The returned session status can be IN-DOUBT, COMMITTED, or ROLLED BACK.
COORDS
specification that all coordinators with in-doubt sessions be displayed.
Example 1
DISPLAY IND COORDS
Completion Message
TDP0410 COORDINATORS WITH IN-DOUBT SESSIONS coordinator coordinator ...
6 47
Chapter 6: TDP Commands DISPLAY INDOUBT where coordinator is the coordinator name.
Example 2
DISPLAY IND SESSIONS COORD IMSA
Completion Message
TDP0412 IN-DOUBT SESSIONS FOR COORDINATOR IMSA TDP0413 SESSION RUN-UNIT ####### rrrrrrr ...
where:
####### rrrrrrr
session number. run-unit id.
Example 3
DISPLAY IND SESSIONS COORD CICSS2 RESOLVED
Completion Message
TDP0409 IN-DOUBT OR RESOLVED SESSIONS FOR COORDINATOR name TDP0437 STATUS SESSION RUN-UNIT TDP0438 sssssssssss ########### rrrrrrrrrrr ...
where:
sssssssssss ########### rrrrrrrrrrr
phrase, IN-DOUBT, COMMITTED, or ROLLED BACK. session number. run-unit id.
6 48
Chapter 6: TDP Commands DISPLAY JOB
DISPLAY JOB
Function
Displays detailed information on jobs that are communicating with the Teradata server through TDP. The DISPLAY JOB command requires a valid job name as an operand. Note that in some cases the job name is a userid. To use this command, you must first use the DISPLAY SESSIONS command to display a list of current jobs, then use a listed jobname as the operand to the DISPLAY JOB command.
Syntax
DISPLAY D JOB jobname
FZAPB019
where:
jobname
name of job for which status information is to be displayed.
Usage Notes
When the DISPLAY JOB command is executed, TDP displays: Job name Number of sessions owned by the job Status of logons (enabled or disabled) for the job Status of each session owned by a job: Name of the job owning the session Session number (in decimal numbers) Status of the session One of the following is always present:
Status Description
IDLE ACTIVE
Session has no request active. Session has a request active
6 49
Chapter 6: TDP Commands DISPLAY JOB
One or more of the following may be present if the condition occurs:

Status Description
STARTING ENDING SWITCH PENDING SWITCH ACTIVE
Session has not completed logon processing. Session has not completed logoff processing. Session must be switched to another session processor, which is not yet assigned. Session is currently being switched to a new session processor.
Example
D JOB BASE7MA
Completion Message
TDP0524 JOB BASE7MA, 1 SESSIONS, 1 ACTIVE, LOGONS ENABLED TDP0525 JOB BASE7MA, SESSION 1012: ACTIVE
6 50
Chapter 6: TDP Commands DISPLAY MODULE
DISPLAY MODULE
Function
Displays information about a TDP module.
Syntax
DISPLAY D MODULE name LOCATION
FZAPB092
where:
name LOCATION
name of a TDP module. optional request that displays the storage location and length of the module,
Usage Notes
Since the names of the TDP modules and the interpretation of the resulting information requires understanding of the internal structure of TDP, this command is intended for use in consultation with NCR customer support people. The earlier, undocumented form of the command, DISPLAY HISTORY, is a synonym for the DISPLAY MODULE command.
Example
D MODULE TDPSYNC
Completion Message
TDP2000 TDPNSPCI: 06.00.00.00 (08/15/96 AT 10:01)
6 51
Chapter 6: TDP Commands DISPLAY POOL
DISPLAY POOL
Function
Lists information and statistics about one or more established session pools.
Syntax
DISPLAY D POOL ALL ID poolid
FZAPB020
where:
poolid ALL
id of pool whose information is to be displayed. request that information about all pools be displayed.
Usage Notes
If an error occurs during START POOL processing (because creation of further pool sessions will cause Teradata server or installation-defined maximum session capacity (MAXSESS) to be exceeded), you can use the DISPLAY POOL command to determine how many sessions were successfully added to the pool before the error prevented further processing. Later, if session demand is reduced, you can use the MODIFY SESSIONS command to acquire the desired number of sessions for the pool.
Example
D POOL ID ACTR04 D POOL ALL
Completion Message
The completion message to the DISPLAY POOL command consists of a header line, followed by one line of statistics per pool, as follows:
ID poolid REQD AVAL ALC BUSY LOGS ERR E/D (statistics appear under these headings)
6 52
Chapter 6: TDP Commands DISPLAY POOL
where:
Column heading . . . Contains the . . .
ID REQD AVAL ALC BUSY LOGS ERR E/D
unique identifiers of the pool whose statistics are displayed. number of sessions requested for the pool in the START POOL or MODIFY POOL command. number of sessions in the pool that are currently not in use and available to satisfy application logon requests. number of pool sessions that are currently in use by applications. number of pool sessions that are in the process of logging on to the Teradata server. number of application logon requests that have already been satisfied by pool sessions. number of application logon requests that have been denied owing to a lack of available pool sessions. indication of whether logons to the pool are enabled (E), or disabled (D).
6 53
Chapter 6: TDP Commands DISPLAY QUEUES
DISPLAY QUEUES
Function
Displays the status of internal work queues for a TDP.
Syntax
DISPLAY D QUEUES Q
FZAPB021
Usage Notes
After the DISPLAY QUEUES command is executed, TDP displays a status line containing the following for each of its internal work queues: Task name Number of work elements in the queue for the task Number of command elements in the queue for the task Number of other work elements for the task
Tasks are only displayed if they have non-zero counts.
Example
D Q
Completion Message
TDP0554 TASK: TDPWTO, WORK(3), COMMANDS(0), OTHER(0) TDP0554 TASK: TDPCMD, WORK(1), CMDS(0), OTHER(0)
6 54
Chapter 6: TDP Commands DISPLAY SERVER
DISPLAY SERVER
Function
Displays attributes of the server with which TDP is communicating.
Syntax
DISPLAY SERVER FEATURES CHARSETS
KY01A123
where:
FEATURES CHARSETS
indication that a list of all internal server features provided to TDP is to be displayed. indication that a list of all character sets supported by the server is to be displayed.
Usage Notes
The following information is always displayed: the decimal id of the logical host the default character set (a question mark is substituted if for some reason the name cannot be ascertained) the default transaction semantics the numeric parallelism factor the numeric values for the maximum segment number and maximum segment size.
The following information may be displayed, depending on the options specified in the command: FEATURES, which is a list of names of the feature information. The usefulness of this information depends upon knowledge of TDP internals; it is intended for use in consultation with NCR customer support personnel. CHARSETS, which is the character set name and corresponding numeric code for each character set
Example
DISPLAY SERVER
6 55
Chapter 6: TDP Commands DISPLAY SERVER
Completion Message
TDP2040 TDP2041 TDP2042 TDP2043 TDP2044 SERVER INFORMATION HOSTID: 250, DEFAULT CHARSET: EBCDIC DEFAULT TRANSACTION SEMANTICS: T PARALLELISM FACTOR: 8 SEGMENT MAXIMUMS: NUMBER(0), SIZE(0)
6 56
Chapter 6: TDP Commands DISPLAY SESSIONS
DISPLAY SESSIONS
Function
Displays the status of sessions that are communicating with the Teradata server through TDP.
Syntax
DISPLAY D SESSIONS SES ALL sessnumber ENDING END
FZAPB022
where:
sessnumber ENDING
session number for which status information is to be displayed. Leading zeros need not be specified. specification that status information be displayed only for sessions that are ending. (An ending session is one for which a logoff request has been sent to the Teradata server but not yet acknowledged.) specification that status information be displayed for all sessions. This is the default if no operand is chosen.
ALL
Usage Notes
The DISPLAY SESSIONS command can be used to display summary information about jobs and sessions or detailed information using the operands. When the DISPLAY SESSIONS command is executed with the default ALL operand, TDP displays the following: Number of sessions logged on to TDP Number of sessions that are ending Status of logons to TDP (enabled or disabled) Job names and the status of their sessions Number of sessions Number of active sessions Status of the session:
6 57
One of the following is always present:

Status Description
IDLE ACTIVE
Session has no request active. Session has a request active.
One or more of the following may be present if the condition occurs:

Status Description
STARTING ENDING SWITCH PENDING SWITCH ACTIVE
Session has not completed logon processing. Session has not completed logoff processing. Session must be switched to another IFP, which is not yet assigned. Session is currently being switched to a new IFP.
The listed job names can be used in the DISPLAY JOBS command to display detailed information about the jobs, including the session numbers related to the different jobs. Note that the job name *TDPINT* may appear in the result of the DISPLAY SESSIONS command. This indicates a TDP-internal session (a session owned by TDP itself). There are two kinds of TDP-internal sessions, and both types have the job name *TDPINT*: Unallocated POOL sessions Two TDP-internal sessions that are used for 2PC in-doubt resolution
When the DISPLAY SESSIONS command is executed with the sessnumber operand, TDP displays: Name of the job owning the session Session number (in decimal) Status of the session
If TEST is enabled, the following information is also displayed: The function number that identifies the last request:
Function Number Meaning
1 2 3 8 9
Logon Logoff Run Logoff all Logoff all tasks
6 58

Function Number Meaning
B C D 10 11 14 20
Connect DISABLE logons ENABLE logons Start request Continue request Aborted start request Directed request
Information about the session (note that more than one bit may be set to on in the flag byte):
Number Meaning
01 02 04 08 10 20 40 80
SP switch required SP switch in progress Transaction state unknown Logging responses to session Request complete Request active on the Teradata server Request on flow queue Request active in TDP
A state indicator for the session (please note that more than one bit may be set to on in the flag byte):
State Indicator Meaning
01 02 04 08 10 20 80
Cleanup required Real pool logoff Pool session Session is owned Abort has been sent Session within user transaction RUN command has been performed
Total transaction count Request number of the last request (in decimal)
6 59
SP number CP number used to send the request to the Teradata server (if a request is active) Number of bytes of information sent to the Teradata server Number of bytes of information received from the Teradata server Session timing Elapsed time (hhh:mm:ss.t) since the start of the session Percentage of time (nn:nn:nn%) the session spent in TDP, the Teradata server, and waiting for the request from the user application (TDP:DBC:OUT) Elapsed time (hhh:mm:ss.t) in the specified session state (IDLE or ACTIVE)
Example 1
D SES SES
Completion Message
TDP0523 2 SESSIONS, 0 ENDING, LOGONS ENABLED TDP0524 JOB BASE7MA, 1 SESSIONS, 1 ACTIVE, LOGONS ENABLED TDP0524 JOB DC, 1 SESSIONS, 0 ACTIVE, LOGONS ENABLED
Example 2
D SES sessnumber
Completion Message
The following result format is displayed for a specified session number when TDP is in test mode.
TDP0525 TDP0549 TDP0503 TDP0515 TDP0574 TDP0578 JOB BASE7MA, SESSION 1012: IDLE FUNCT: 10, INFO: 00, STATE: 88 COUNT: 4 REQUEST: 850476, SPNUM: 000F, CPNUM: 000E BYTES SENT 311, BYTES RECVD: 1582 SESSION ELAPSED: 004:34:45.5 TDP:DBC:OUT=0:0:100% CURRENT ELAPSED: 004:31:10.8
6 60
Chapter 6: TDP Commands DISPLAY SMF
DISPLAY SMF
Function
Displays the status of TDP System Management Facility (SMF) recording. It displays whether SMF recording is enabled or disabled and (if necessary) the status of individual SMF record subtypes. In VOS3, applies to SMS records.
Syntax
DISPLAY D SMF
FZAPB023
Usage Notes
SMF recording can be enabled or disabled for all SMF subtype records or for selected records. If SMF recording is disabled for only some records, the DISPLAY SMF command shows which records have that status. There are four record subtypes:
Record Subtype Description
1 2 3 4 5
Teradata server session termination record Teradata server session security violation record IFP activity data record TDP global statistics record (written at time of TDP SHUTDOWN) Structure-protocol termination record
Example
D SMF
Completion Message
TDP0594 SMF RECORDING ENABLED CONDITIONALLY TDP0595 SUBTYPE2: DISABLED TDP0595 SUBTYPE4: DISABLED
6 61
Chapter 6: TDP Commands DISPLAY SP
DISPLAY SP
Function
Displays the status of session processors (SPs) that are assigned to this TDP.
Syntax
DISPLAY D SP PNUM xxxx SESSIONS DETAIL
FZAPA100
where:
xxxx
four-character hexadecimal SP id for which information is to be displayed. If omitted, all information for all SPs is displayed.
SESSIONS DETAIL
indication that a list of all sessions for the SP is to be displayed. indication that diagnostic information for the SP is to be displayed. This option is intended for use in consultation with NCR customer support personnel. Note: The associated information requires internal knowledge of TDP to properly interpret. Without such knowledge, misleading conclusions are probable. Time can be saved by heeding this recommendation.
Usage Notes
The following information is always displayed, as applicable: SP number. SP Status, as follows:
Status Definition
NOT OPERATIONAL OPERATIONAL USABLE
The server indicates that the SP is down. The server indicates that the SP is up. Operational and the TDP state has been synchronized with that of the server.
6 62

Status Definition
DELAYED SERIALIZED
Operational but requests are being delayed while synchronization is in progress for this SP. Operational and in use for a synchronization request for an SP.
If sessions are allocated, the total number of sessions the number of these sessions that are using the Monitor partition the number of these sessions that are in-doubt but whose original application is no longer using the session If any allocated sessions are waiting the response to a Logoff. If any allocated sessions are involved in switching sessions from a down SP to an operational SP.
The following information is displayed, according to the options specified in the command:
IF you select this option . . . THEN this information is displayed . . .
DETAIL
IF . . .
This information is displayed . . .
synchronization is in progress, this SP has an affinity for CP, this SP is dependent upon a CP, SESSIONS
whether a Host Start or Session Information request has been sent and which SP is being used. the extended affinity id and a list of CPs. the intended dependency id and a list of CPs.
For each session allocated on this SP, the session number, job name and state, as follows:
State Definition
IDLE ACTIVE STARTING ENDING SWITCH PENDING
No request is active. A request is active. The session is being established. The session is to be logged off. The session is to be switched to an operational SP.
6 63

THEN this information is displayed . . .
SWITCH ACTIVE
The session is being switched to an operational SP.
Session number for each in-doubt session whose application is no longer using the session.
Example
D SP
Completion Message
TDP1260 SPNUM 000F: OPERATIONAL, USABLE TDP1261 SESSIONS: 2 (MONITOR: 0, INDOUBT: 1) TDP1260 SPNUM 000E: OPERATIONAL, USABLE TDP1261 SESSIONS: 2 (MONITOR: 0, INDOUBT: 0)
6 64
Chapter 6: TDP Commands DISPLAY STORAGE
DISPLAY STORAGE
Function
Displays information about the use of virtual storage by TDP.
Syntax
DISPLAY STORAGE CP
FE0CA047
Usage Notes
If CP is not specified, it is assumed. For CP, the following virtual storage information is displayed: current number of bytes being used for I/O current number of bytes allocated for use by I/O highest number of bytes allocated for use by I/O minimum number of bytes required for I/O to prevent deadlocks maximum number of bytes that may be allocated for I/O DYNAMIC, indicating that the maximum value was dynamically calculated by TDP, or STATIC, indicating that the value was set manually by the SET STORAGE command
Example
DISPLAY STORAGE
6 65
Chapter 6: TDP Commands DISPLAY TDP
DISPLAY TDP
Function
Displays the status of TDP.
Syntax
DISPLAY D
TDP
FZAPB024
Usage Notes
When the DISPLAY TDP command is executed, TDP displays information on the following items:
Item Description
RUN command
(May not always appear.) If the RUN command has not been entered, a message stating that fact is displayed first, preceding the other settings. Otherwise, only the following settings are shown in the display.
TDP release COMCHAR
The release identifier for TDP. Current subsystem command character for TDP. This is set using the TDP command, INITIAL COMCHAR.
TDP MAXSESS
Maximum number of sessions currently allowed for TDP. This is determined by the TDP SET MAXSESS command.
LOGONS
Status of logons (enabled or disabled). This is modified using the ENABLE LOGONS and DISABLE LOGONS commands.
SERVER MAXSESS
Maximum number of sessions supported by the CPs that are currently operational. This value may vary during recovery from Teradata server restarts as the status of the SPs vary.
I/O MODE
Mode used by TDP to send I/O to the Teradata server (EXCP, EXCPVR, IOSDRIVR). The I/O mode is set using the INITIAL IOMODE command.
IAC MODE
MVS communication mode (SVC or PC).
6 66

Item Description
If the operating system is VM, the IAC MODE value should be IUCV. This is set using the INITIAL IACMODE command. SECURITY EXIT State of the TDP User Security Interface (TDPUSEC), enabled or disabled. This is modified using the ENABLE USEC and DISABLE USEC commands. TEST State of the TEST flag (enabled or disabled). This is modified using the ENABLE TEST and DISABLE TEST commands. MONITOR EXIT State of the TDP User Transaction Collection Exit (TDPUTCE), enabled or disabled. This is modified using the ENABLE TMON and DISABLE TMON commands. LOGON EXIT State of the TDP User Logon Exit interface (TDPLGUX), enabled or disabled. This is modified using the ENABLE LGUX and DISABLE LGUX commands. CHECKSUM State of the checksum error detection setting on the Teradata server for CIC-type CPs, enabled or disabled. This is modified using a DBS console command. (See the Teradata DBS Operators Guide.) SECLOGON State of the Security Logon (SECLOGON) feature, and whether its messages option is enabled or disabled. This is modified using the MODIFY SECLOGON command. TIME MSGS State of the time messages, enabled or disabled. This is modified using the ENABLE TIME and DISABLE TIME commands. UAX State of the TDP User Address Space Exit interface (TDPUAX), enabled or disabled.
This is modified using the ENABLE UAX and DISABLE UAX commands. SESSION DETAIL State of the SESSION DETAIL setting, enabled or disabled.
This is modified using the ENABLE SESSION DETAIL and DISABLE SESSION DETAIL commands.
6 67

Item Description
SESSION RESERVE
State of the session reserve setting, enabled or disabled. This is modified using the ENABLE SESSION RESERVE and DISABLE SESSION RESERVE commands.
SESSION STATUS
State of the SESSION STATUS setting, enabled or disabled.
This is modified using the ENABLE SESSION STATUS and DISABLE SESSION STATUS commands. SHUTDOWN STATUS (May not always appear.) If a SHUTDOWN command has been entered and has not yet completed, the above settings are followed by a message that an orderly, quick, or cancel shutdown is in progress. TDP USERID USERID CHARSET TDP CHARSET Userid for TDP internal sessions. Name of the character set associated with the TDP USERID. Name of the default TDP character set.
Example
D
Completion Message
TDP2010 TDP0550 TDP0551 TDP0556 TDP0552 TDP0570 TDP0572 TDP0573 TDP2012 TDP0400 TDP0392 TDP0395 RELEASE: TDP.06.01.00 COMCHAR: OFF, TDP MAXSESS: 1024 LOGONS: ENABLED , SERVER MAXSESS: 120 I/O MODE: EXCP, IAC MODE: IUCV SECURITY EXIT: ENABLED, TEST: DISABLED MONITOR EXIT: ENABLED, LOGON EXIT: ENABLED CHECKSUM: DISABLED TIME MSGS: ENABLED, UAX: DISABLED SESSION STATUS: DISABLED, DETAIL: DISABLED SESSION RESERVE: ENABLED TDP USERID: TDPUSER, USERID CHARSET: EBCDIC TDP CHARSET: EBCDIC
6 68
Chapter 6: TDP Commands DISPLAY TDPSTATS
DISPLAY TDPSTATS
Function
Displays the current status (enabled or disabled) of the TDPSTATS function.
Syntax
DISPLAY DISP TDPSTATS
FE0CA044
Usage Notes
TDPSTATS is enabled with the ENABLE TDPSTATS command, and disabled with the DISABLE TDPSTATS command.
Example
DISP TDPSTATS
Completion Message
TDP2031 TDPSTATS ID DISABLED
6 69
Chapter 6: TDP Commands ENABLE IRF
ENABLE IRF
Function
Enables TDP internal sessions that are used for 2PC in-doubt resolution.
Syntax
ENABLE ENA IRF
FZAPB025
Usage Notes
This command enables the In-doubt Resolution Facility (IRF), which consists of two TDP-internal sessions used for 2PC in-doubt resolution. The result of the ENABLE IRF command is that the two internal sessions are logged on to the Teradata server. If no other sessions are logged on, the status display on the RDBMS console changes from Logon/Quiet to Logon. The ENABLE IRF command typically is issued after a DISABLE IRF command is completed. For more information see DISABLE IRF, earlier in this chapter. Enabling the IRF allows automatic in-doubt resolution and the execution of TDP commands for manual in-doubt resolution (COMMIT, ROLLBACK, and DISPLAY INDOUBT). When a specified character set is not available, the following error message displays:
TDP0394 CHARACTER SET charactersetname IS NOT AVAILABLE.
Example
ENA IRF
Completion Message
TDP0444 type SESSION ESTABLISHED
where:
type is either:
RBM (Resolver Base Module) or LOG
Usually, one message is displayed for the RBM session and another is displayed for the LOG session.
6 70
Chapter 6: TDP Commands ENABLE LGUX
ENABLE LGUX
Function
Causes TDP to begin passing logon requests to TDP User Logon Exit Interface (TDPLGUX).
Syntax
ENABLE ENA LGUX
FZAPB026
Usage Notes
TDPLGUX is enabled when TDP starts. If TDPLGUX is subsequently disabled using the DISABLE LGUX command, it may be re-enabled using the ENABLE LGUX command. When the ENABLE LGUX command is executed, TDP loads the TDPLGUX module into main memory and begins passing logon requests to the module.
Example
ENA LGUX
Completion Message
TDP0911 TDP USER LOGON EXIT INTERFACE ENABLED
6 71
Chapter 6: TDP Commands ENABLE LOGONS
ENABLE LOGONS
Function
Causes TDP to begin accepting logon requests from application programs.
Syntax
ENABLE ENA LOGONS
FZAPB027
Usage Notes
When TDP starts, logons are not enabled. During TDP initialization, the ENABLE LOGONS command should be executed to allow applications to begin processing requests. After the ENABLE LOGONS command is executed, TDP begins forwarding logon requests to the Teradata server for processing.
Example
ENA LOGONS
Completion Message
TDP857 LOGONS ENABLED
6 72
Chapter 6: TDP Commands ENABLE POOL
ENABLE POOL
Function
Enables logons to one or more pools.
Syntax
ENABLE ENA POOL ALL ID poolid
FZAPB028
where:
poolid ALL
unique identifier of the pool that is to be enabled. specification that all pools be enabled.
Usage Notes
The ENABLE POOL command is used to enable logons for a pool that has been disabled by the DISABLE POOL command. When a session to be used for session pool assignment is started, a TDP0800 message is produced; when such a session ends, a TDP0801 message is produced.
Example 1
ENA POOL ID ACTR04
Completion Message
TDP881 POOL ID: ACTR04 IS NOW ENABLED INIT USERID PLKMN
Example 2
ENA POOL ALL
6 73
Chapter 6: TDP Commands ENABLE SECLOGON
ENABLE SECLOGON
Function
Enables the security logon function that provides an interface to the System Authorization Facility (SAF) on MVS client systems. Note: You must enable the security logon function manually either from the system console or via the TDPPARM command list. It does not automatically enable at TDP initialization like TDPLGUX, TDPUSEC, or TDPUTCE.
Syntax
ENABLE ENA SECLOGON NOMSGS MSGS CLASS xxxxxxxx
FZAPB094
where:
Syntax element . . . Is the specification of . . .
NOMSGS MSGS xxxxxxxx
the messages option that suppresses messages to the system console in response to logon validation failure or denied access. the messages option that enables messages to the system console in response to logon validation failure or denied access. an class for SAF processing. The default class is FACILITY.
Usage Notes
TDP responds to the ENABLE SECLOGON command with a TDP2108 message indicating the new status of the security logon function and its messages option. SECLOGON will only work under MVS, and only when IACMODE XMS has been selected at TDP initialization. To use SECLOGON in a Multi-User Address Space (MUSAS) environment like CICS or IMS, obtain the security userid from the external security manager via TDPUAX, and pass that information to TDPLGUX. Once this is done TDPLGUX can direct SECLOGON to use the TDPUAX-supplied security userid for validation purposes. For more details, consult your external security managers documentation or contact the vendors technical support.
Example
ENABLE SECLOGON
6 74
Chapter 6: TDP Commands ENABLE SECLOGON
Completion Message
TDP2108 SECLOGON: ENABLED, DIAGNOSTIC MSGS: DISABLED CLASS: FACILITY
6 75
Chapter 6: TDP Commands ENABLE SESSION DETAIL
ENABLE SESSION DETAIL

Function
Causes TDP to produce a message when a session ends that indicates the elapsed time that the session spent within the application and within the server.
Syntax
ENABLE ENA SESSION DETAIL DET
FZAPA099
Usage Notes
When TDP starts, Session Detail is disabled. The current setting may be displayed using the DISPLAY TDP command. When Session Detail is enabled and a session ends, a TDP0846 message is produced to indicate the total elapsed time that the session spent within the application an within the server.
Example
ENABLE SESSION DETAIL
Completion Message
TDP0401 SESSION DETAIL HAS BEEN ENABLED
6 76
Chapter 6: TDP Commands ENABLE SESSION RESERVE
ENABLE SESSION RESERVE

Function
Causes TDP to reserve session capacity for use in the event of a failure of a session processor (SP). This reserve reduces the maximum number of sessions TDP can control during its current run.
Syntax
ENABLE ENA SESSION RESERVE RES
FZAPB029
Usage Notes
When TDP starts, the Session Reserve is enabled. If the Session Reserve has been subsequently disabled with the DISABLE SESSION RESERVE command, you can use the ENABLE SESSION RESERVE command to enable the Session Reserve again. When Session Reserve is enabled and more than one SP is operational, TDP reserves a number of sessions equal to the capacity of one SP. This is to ensure that if a single SP fails, its sessions can be switched to other SPs that were started by this TDP. This command affects the value of SEVER MAXSESS, as displayed in the output from the DISPLAY TDP command. This is a separate limit from the value of TDP MAXSESS, which is controlled by the SET MAXSESS command. The maximum number of sessions that can be logged on through this TDP is the lower of these two values. When the maximum number of sessions is already logged on to TDP, any new logon request from an application is refused with an error code of CLI0513.
Example
ENA SESSION RES
Completion Message
TDP400 SESSION RESERVE: ENABLED
6 77
Chapter 6: TDP Commands ENABLE SESSION STATUS

Function
Causes TDP to produce a message when a session starts or ends.
Syntax
ENABLE ENA SESSION STATUS STA
FZAPA098
Usage Notes
When TDP starts, Session Status is disabled. The current setting may be displayed using the DISPLAY TDP command. If Session Status is enabled, a TDP0899 message is produced when a session starts, and a TDP0898 message is produced when a session ends. These messages had previously been controlled by the ENABLE TEST command. For compatibility, they continue under TEST control until an ENABLE SESSION STATUS or DISABLE SESSION STATUS is issued, after which TEST has no effect on these messages.
Example
Completion Message
TDP0401 SESSION STATUS HAS BEEN ENABLED
6 78
Chapter 6: TDP Commands ENABLE SMF
ENABLE SMF
Function
Enables the recording of all System Management Facility (SMF) records. You can also limit the recording to specific record subtypes. In VOS3, this applies to SMS records.
Syntax
ENABLE ENA SMF ALL SUB n
FZAPB030
where:
Syntax element . . . Is the specification that recording for . . .
ALL SUBn
all SMF record types is to be enabled. certain SMF types is to be enabled. There are four subtypes: 1: Session Termination 2: Security Violation 3: IFP Activity 4: TDP Shutdown 5: Structure-protocol Termination
Usage Notes
When TDP starts, SMF recording is enabled for subtypes 1 through 4. To disable SMF recording, use the DISABLE SMF operator command. The ALL argument is the default for this command. If you enter just the ENABLE SMF command with no arguments, recording is enabled for all SMF record subtypes. To enable the recording of a specific SMF record subtype, use the SUBn argument, where n is the number of the SMF record subtype to be recorded.
Example
ENA SMF ENA SMF SUB1
6 79
Chapter 6: TDP Commands ENABLE SMF
Completion Message
TDP0594 SMF RECORDING ENABLED
6 80
Chapter 6: TDP Commands ENABLE TDPSTATS
ENABLE TDPSTATS
Function
TDPSTATS measures the performance and assesses the efficiency of data movement between TDP and the Teradata RDBMS. TDPSTATS collects the following information over the course of one-minute intervals, then displays it on a normalized per second basis: EXCPS ininput execute channel program (data blocks) messages inmessages received retries ininput retries Kbytes inkilobytes received EXCPs outoutput EXCPs messages outmessages sent retries outtransmission retries Kbytes out kilobytes sent
This data is useful for application tuning as well as performance benchmarking. The Kbytes in and Kbytes out values provide an overall measure of throughput efficiency.
Syntax
ENABLE ENA TDPSTATS
FE0CA042
Usage Notes
TDPSTATS is stopped by the DISA TDPSTATS command. Use the DISPLAY TDPSTATS command to determine the status of TDPSTATS. You can configure TDPSTATS to route output to the system console, or to a data set. The advantage of routing to the console is that you can view the data in real time, make adjustments to various tuning parameters, and observe the results immediately. The disadvantage is that the console may become cluttered with messages from TDPSTATS. The advantage of routing to a data set is that the data can be collected automatically and post-processed using a product such as Microsoft Excel to produce historical graphs or charts that can depict performance trends over longer periods of time. The disadvantage is the concomitant loss of immediacy. To route data to the console, enter ENA TDPSTATS. At one-minute intervals, TDSPTATS writes two messages to the console (one for input statistics and the
6 81
Chapter 6: TDP Commands ENABLE TDPSTATS
other for output statistics). This continues until TDPSTATS is terminated by entering DISA TDPSTATS, or until a TDP shutdown occurs. To route data to a data set, include a DD statement to identify a sequential data set in the JCL for the TDP started task. The DDNAME of this file must be TDPSTATS. Generation data groups (GDGs) are acceptable, as is SYSOUT. At one-minute intervals, TDPSTATS writes one record to this file using QSAM. Following are typical entries:
TDPSTATS FOR TDPC (VALUES ARE PER SECOND SAMPLED AT ONE-MINUTE INTERVALS YYYY.DDD,HH:MM,EXCPIN,MSGSIN,RTRYIN,KBYTIN,EXCPOU,MSGSOU,RTRYOU,KBYTOU 1999.215,09:51,000008,000064,000000,001455,000007,000063,000000,001593 1999.215,09:52,000000,000000,000000,000000,000000,000000,000000,000000 1999.215,09:53,000000,000000,000000,000000,000000,000000,000000,000000
The first record identifies the output as being generated by TDPSTATS for a specific TDP (in this case, TDPC). The second record provides a legend for easier readability. Note that the actual data values are comma-separated; this facilitates their input into a spreadsheet program like Excel. In both console and data set modes, if the device configuration is changed (for example, starting and or stopping one or more IFPs) while TDPSTATS is active, data associated with the current interval is discarded and TDPSTATS will be reinitialized. This results in the loss of data from one one-minute interval. In data set mode, if an OPEN/CLOSE/EOV failure or I/O error associated with the TDPSTATS file occurs, TDPSTATS is permanently disabled for the life of the TDP address space, and restarting TDPSTATS will require restarting TDP.
Example
ENABLE TDPSTATS
Completion Message
TDP2500 TDP THROUGHPUT STATISTICS REPORTER ENABLED
6 82
Chapter 6: TDP Commands ENABLE TEST
ENABLE TEST
Function
Causes TDP to start writing informational or diagnostic messages to the system console.
Syntax
ENABLE ENA TEST
FZAPB031
Usage Notes
When TDP starts, TEST mode is not enabled. TEST may be enabled by executing the ENABLE TEST operator command. After ENABLE TEST is executed, informational messages produced by TEST mode are written to the system console to indicate the starting and ending of sessions. If the DISPLAY SESSION command is executed while TEST is enabled, a more comprehensive display is given. For details, refer to DISPLAY SESSIONS.
Example
ENA TEST
Completion Message
TDP0541 TEST MODE ENABLED
6 83
Chapter 6: TDP Commands ENABLE TIME
ENABLE TIME
Function
Causes TDP to send the time from the client to the Teradata server.
Syntax
ENABLE ENA TIME TIM
FZAPB032
Usage Notes
If neither an ENABLE TIME nor a DISABLE TIME command is issued, the default action is specified in HSISPB. While HSISPB can be customized as necessary, as distributed, DISABLE TIME is the default. If you are using a Teradata RDBMS release between V1R4.1 and V1R5.1, inclusive, the ENABLE TIME feature is supported only for DBC/1012 configurations controlled by a Model 2 Access Module Processor (AMP) or below. If the configuration at your site does not include a Model 2 AMP, you may want to include the DISABLE TIME command in the TDPPARM data set to reduce meaningless channel traffic. For releases prior to V1R4.1 or V1R5.2 and above, ENABLE or DISABLE TIME function as expected. To set the time, use the RDBMS console command, SET TIME.
Example
ENA TIM
Completion Message
TDP0596 HOST TO SERVER TIME MESSAGES: ENABLED
6 84
Chapter 6: TDP Commands ENABLE TMON
ENABLE TMON
Function
Enables TDP calls to the User Transaction Collection Exit (TDPUTCE) routine, which is used to collect statistics about requests and responses that traverse TDP.
Syntax
ENABLE ENA TMON
FZAPB033
Usage Notes
When TDP starts, TDPUTCE is enabled. If TDPUTCE is subsequently disabled using the DISABLE TMON operator command, the routine may be re-enabled using the ENABLE TMON command. When the ENABLE TMON command is executed, TDP loads the TDPUTCE module into main memory and begins passing all requests and responses to the module.
Example
ENA TMON
Completion Message
TDP0921 TDP USER MONITOR EXIT INTERFACE ENABLED
6 85
Chapter 6: TDP Commands ENABLE TRAP
ENABLE TRAP
Function
Enables a TDP internal diagnostic trap. The trap causes the TDP to perform a specified action if the trap conditions occur.
Syntax
ENABLE TRAP PERMIO CHECKSUM CHE BADCP SERVERPV CLIENTPV FAULTRSP ACTION ABEND SNAP IMPRSTRT IMP ACTION ABEND SNAP UNSOLRSP UNS ACTION ABEND SNAP
FE0CS045
NAME name
where:
Syntax element . . . Indicates. . .
PERMIO BADCP SERVERPV CLIENTPV FAULTRSP
trap a CP permanent I/O error. trap an invalid CP device. trap a server protocol violation. trap a client protocol violation. trap a faulty response. A faulty response is one whose parcels do not exactly fill the response.
6 86
Chapter 6: TDP Commands ENABLE TRAP

Syntax element . . . Indicates. . .
IMPrstrt
trap detection of an implicit CP restart. An implicit CP restart occurs when TDP was not informed of the restart of a CP directly by the CP, but rather detects the restart by subsequent errors returned by the server. Note: Lower case letters represent optional characters.
UNSolrsp
trap detection of an an unsolicited response. An unsolicited response occurs when TDP receives a response from the Teradata server that is not associated with a request that had been sent by TDP. Note: Lower case letters represent optional characters.
ABEND SNAP CHECKSUM name
terminate TDP if the trap condition occurs. This is the default. record the event to TDPSNAP if the trap condition occurs. indication that a checksum validation failure for a CCU-type CP is to be trapped. trap name; length is 1 to 8 characters. If omitted, TDP supplies a name.
Usage Notes
The trap may be removed by using the DISABLE TRAP command. For event types that do not support the ACTION operand, or when the ACTION operand is not specified, ABEND is the implied action. Because TDPSNAP is not used in VM, ACTION SNAP has no effect. This command is intended for use in consultation with NCR Customer Support personnel.
Example
ENABLE TRAP PERMIO
Completion Message
TDP0401 TRAP TRAP0001 HAS BEEN ENABLED
6 87
Chapter 6: TDP Commands ENABLE UAX
ENABLE UAX
Function
Causes TDP to pass requests to the User Address Space Exit Interface (TDPUAX).
Syntax
ENABLE ENA
FZAPB034
UAX
Usage Notes
TDPUAX is available only in the MVS or VOS3 environment. If you use the ENABLE UAX command in the VM environment, you receive the following message:
TDP0506 UNKNOWN OPERAND TO THE ENABLE COMMAND: UAX
To disable TDPUAX, use the DISABLE UAX command.
Example
ENA UAX
Completion Message
TDP0597 TDP USER ADDRESS SPACE EXIT INTERFACE ENABLED
6 88
Chapter 6: TDP Commands ENABLE USEC
ENABLE USEC
Function
Causes TDP to begin passing security and logon violations information detected by the Teradata server and by the User Logon Exit Interface (TDPLGUX) to the TDP User Security Interface (TDPUSEC).
Syntax
ENABLE ENA
FZAPB035
USEC
Usage Notes
When TDP starts, TDPUSEC is enabled. If TDPUSEC is subsequently disabled using the DISABLE USEC operator command, the interface may be re-enabled using the ENABLE USEC command. When the ENABLE USEC command is executed, TDP loads the TDPUSEC module into main memory and begins passing security violations to the module.
Example
ENA USEC
Completion Message
TDP0901 TDP USER SECURITY EXIT INTERFACE ENABLED
6 89
Chapter 6: TDP Commands LOGOFF
LOGOFF
Function
Forces one or more sessions to be logged off the Teradata server.
Syntax
LOGOFF SESSIONS SES JOB jobname TASK taskid SUPPRESS SUCCESS WARNING ALL
FZAPC036
sessnumber ALL
where:
sessnumber ALL jobname
session number, in decimal, of the session to be logged off. Leading zeros need not be specified. specification that all sessions are to be logged off. Job name (in all environments), or TSO user identification (in MVS only) whose sessions are to be logged off. TSS user identification (in VOS3 only) whose sessions are to be logged off.
taskid SUCCESS WARNING ALL
MVS or VOS3 TCB address that established the sessions to be logged off. specification that messages indicating success of the command will be suppressed. specification that messages indicating warnings that no sessions were affected will be suppressed. specification that both success and warning messages will be suppressed.
Usage Notes
When the LOGOFF command is executed, a logoff request is sent to the Teradata server for each session to be logged off. When the SES ALL operand is used, Teradata server logons are disabled when all sessions have been logged off.
6 90
Chapter 6: TDP Commands LOGOFF
Outstanding requests for sessions to be logged off are aborted, and any results are returned to the requesting application. Subsequent requests for a logged-off session are returned to an application with an error message. To log off a session, issue the LOGOFF command from the TDP that the session is running on.
Performance Monitor ABORT SESSION Command

There is a separate performance monitor command, ABORT SESSION, that is executed from the RDBMS console. The ABORT SESSION command can log off any Teradata server session on any mainframe or LAN client. It can also log off sessions based on username only (the host id and session number are not required).
Example 1
LOGOFF SES 1259
Completion Message
TDP0864 LOGOFF COMMAND ACCEPTED FOR SESSION 1259
Example 2
LOGOFF SES ALL
Completion Message
TDP0860 LOGOFF INITIATED FOR number_of_sessions SESSIONS
Example 3
LOGOFF JOB AWVRET
Completion Message
TDP0850 JOB AWVRET number_of_sessions LOGOFFS INITIATED
6 91
Chapter 6: TDP Commands LOGOFF POOL
LOGOFF POOL
Function
Ends a pool immediately by forcing the logoff of pool sessions that are in use by application programs.
Syntax
LOGOFF POOL ID poolid ALL
FZAPA037
where:
poolid ALL
unique identifier of the pool that is to be logged off. way to request that all pools be logged off.
Usage Notes
The LOGOFF POOL command affects only pool sessions that are being used by applications. The LOGOFF POOL command terminates any pool sessions that are in use and disables their associated pools. The pools still exist, but they are disabled. To use the pools again, use the ENABLE POOL command. To completely eliminate existing pools in an orderly manner, use the STOP POOL command.
Example 1
LOGOFF POOL ID ACTR04
Example 2
LOGOFF POOL ALL
6 92
Chapter 6: TDP Commands LOGOFF POOL
Completion Messages
When LOGOFF POOL . . . This message is displayed . . .
begins processing finishes processing
TDP0877 LOGOFF POOL INITIATED FOR POOL ID: poolid TDP0878 POOL ID: poolid STOPPING
6 93
Chapter 6: TDP Commands MODIFY POOL
MODIFY POOL
Function
Increases or decreases the number of sessions in a pool.
Syntax
MODIFY POOL ID poolid NUM number
FZAPB038
where:
poolid number
unique identifier of the pool that is to be modified. modified number of sessions desired for the pool.
Usage Notes
The MODIFY POOL command may be used to supplement the number of sessions in a pool that was originally unable to acquire the desired number of sessions because there was insufficient session capacity. When supplementing the number of pool sessions, the MODIFY POOL command is entered after system session load has been reduced. If the modified number of sessions is equal to the current number of sessions in the
pool, then the command is rejected with an error message.
Example
MODIFY POOL ID ACTR04 NUM 30
Completion Messages
When MODIFY POOLis executed to . . . The resulting message is . . .
increase the number of sessions in a pool decrease the number of sessions in a pool
TDP0866 ADDING number SESSIONS TO POOL ID: poolid TDP0879 REMOVING number SESSIONS FROM POOL ID: poolid
6 94
Chapter 6: TDP Commands MODIFY SECLOGON
MODIFY SECLOGON
Function
Changes the configuration of the messages option of the security logon function that provides an interface to the System Authorization Facility (SAF) on MVS and VM client systems.
Syntax
MODIFY MOD SECLOGON MSGS NOMSGS
FZAPA092
where:
Syntax element . . . Is the specification of the messages option that . . .
NOMSGS MSGS
suppresses messages to the system console in response to logon validation failure or denied access. enables messages to the system console in response to logon validation failure or denied access.
Usage Notes
TDP responds to the MODIFY SECLOGON command with a TDP2108 message indicating the new status of the security logon function and its messages option.
Example
MODIFY SECLOGON MSGS
Completion Message
TDP2108 SECLOGON: ENABLED, DIAGNOSTIC MSGS: ENABLED
6 95
Chapter 6: TDP Commands ROLLBACK
ROLLBACK
Function
Rolls back a single 2PC in-doubt session or all 2PC in-doubt sessions for a specified coordinator.
Syntax
ROLLBACK ALL SESSION number COORD name HOST id
FZAPB039
where:
ALL SESSION number name
specification that all in-doubt sessions for the coordinator are to be rolled back. specification that only one session is to be rolled back. number of the in-doubt session to be rolled back. coordinator name in alphanumeric characters. In MVS, the coordinator name is either: The CICS VTAM application name, or The IMS system id.
id
(optional) logical host ID, a decimal number. The default is the host ID of the current TDP.
Usage Notes
The ROLLBACK command includes a LOGOFF action by default. The result of this command is recorded in the InDoubtResLog on the Teradata server.
Example 1
ROLLBACK ALL COORD TERCICS
Completion Message
TDP0420 ALL IN-DOUBT SESSIONS FOR COORDINATOR TERCICS ROLLED BACK
Example 2
ROLLBACK SESSION 3253 COORD IMS
6 96
Chapter 6: TDP Commands ROLLBACK
Completion Message
TDP0403 SESSION 3253 ROLLED BACK
6 97
Chapter 6: TDP Commands RUN
RUN
Function
Enables communication with the Teradata server by allowing IFPs to be started.
Syntax
RUN
FZAPA040
Usage Notes
Sessions cannot be established until the RUN command is executed. Any TDP command can be issued before the RUN command. Those commands that require communication with the Teradata server (for example, IFP-related commands) are accepted but do not complete. Once the RUN command is executed, any pending IFP-related commands will complete and sessions can then be established. This gives an operator the opportunity to enter commands that are not included in the TDPPARM data set before TDP begins execution. If the command used to start TDP is executed from the system console, each command in TDPPARM is displayed at the console as it is executed, followed by a processing response. If the RUN command is entered as part of a batch job, messages are routed to the master console route code.
Example
RUN
6 98
Chapter 6: TDP Commands SET CHARSET
SET CHARSET
Function
Establishes the character set with which userids and logon strings are specified in TDP commands.
Syntax
SET CHARSET character_set_name

FZAPB041
where:
character_set_name
name of a character set known to TDP, chosen as one of the following: EBCDIC EBCDIC037_0E EBCDIC273_0E EBCDIC277_0E KANJIEBCDIC5026_0I KANJIEBCDIC5035_0I KATAKANAEBCDIC ASCII LATIN1_0A LATIN9_0A LATIN1252_0A KANJISJIS_0S KANJIEUC_0U UCS2 UTF8 Or any user-defined character set established using the TDP SET USERCS command.
While other names may be specified, their characteristics (codepoint for the space, comma, apostrophe, and quotation symbols; the codepoints for control characters; the encoding scheme, and the rules for monocasing) are assumed to be the same as the characteristics for EBCDIC.
6 99
Chapter 6: TDP Commands SET CHARSET
Usage Notes
Unless this command is specified, EBCDIC is assumed. Neither the ability of the database to support character sets nor the existence of the specified character set is validated during the execution of this command. Subsequent attempts to specify a database object in a TDP command may result in errors.
Example 1
SET CHARSET KANJIEBCDIC5026_0I
Example 2
SET CHARSET EBCDIC
Completion Message
TDP0396 TDP CHARSET IS NOW character_set_name
Error Messages
Possible error messages are:
TDP0504 TDP0506 TDP0535 TDP0536 TDP0502 UNKNOWN TDP COMMAND NAME: text UNKNOWN OPERAND TO THE SET COMMAND: text TOO FEW OPERANDS FOR THE SET CHARSET COMMAND TOO MANY OPERANDS FOR THE SET CHARSET COMMAND LENGTH INCORRECT FOR SET CHARSET VALUE
6 100
Chapter 6: TDP Commands SET CHECKSUM
SET CHECKSUM
Function
Changes the use of checksum validation for data transfer to and from the Teradata server through CCU-type CPs.
Syntax
SET CHECKSUM CHE ON OFF AUTO AUT
EF03A073
where:
Syntax element . . . Indicates that. . .
ON OFF AUTO
checksums from the server are honored, and checksums are always sent to the server. checksums from the server are ignored, and no checksums are sent to the server. when a checksum is received from the server, checksums are sent to the server.
Usage Notes
Use the DISPLAY CHECKSUM command to display the current checksum setting.
Message
TDP2033 CHECKSUM IS NOW 'ON' (WAS 'OFF')
6 101
Chapter 6: TDP Commands SET COMCHAR
SET COMCHAR
Function
Establishes or changes the communication character (comchar) that is used to link the entry of TDP operator commands with a TDP that is to be initialized.
Syntax
SET COMCHAR COM comchar OFF
FZAPB043
where:
comchar
communication character as one of the following special characters: [.<(+|&!$*);-/,%_>?:#@=
OFF
specification that no communication character be used to identify commands.
Usage Notes
When a TDP starts, no comchar is defined. After the SET COMCHAR command is executed to specify a communication character for a TDP, all TDP commands subsequently entered that are preceded by the character are interpreted as commands for that TDP. It is not recommended that the same communication character be defined for more than one TDP subsystem. If this is done, commands prefixed by the character are processed by all subsystems that are assigned that communication character.
Example 1
SET COM +
Completion Message
TDP0543 COMMUNICATION CHARACTER IS NOW SET: +
Example 2
SET COMCHAR OFF
6 102
Chapter 6: TDP Commands SET MAXSESS
SET MAXSESS
Function
Establishes the maximum number of concurrent sessions that TDP will allow.
Syntax
SET MAXSESS MAXS number_of_sessions
FZAPB044
where:
number_of_sessions
maximum number of sessions, in decimal, that may be concurrently logged on to TDP. This operand may be set to any value between 0 and 4,294,967,295.
Usage Notes
The SET MAXSESS command limits TDP usage of Teradata server resources by limiting the number of sessions that it can control. When the maximum number of sessions is already logged on to TDP, any new logon request from an application is rejected. If this command is not used, the maximum number of concurrent sessions that TDP will allow is the same as the maximum number currently supported by the server. Unless IRF disabled, two internal sessions are established upon TDP startup that are used for 2PC. You cannot prevent these sessions from being established by setting the MAXSESS number to 0. You can disable these two internal sessions only by using the DISABLE IRF command, either by entering it manually or including it in the TDPPARM data set.
Example
SET MAXS 25
Completion Message
TDP0544 TDP MAXIMUM SESSION LIMIT NOW SET TO: 25
6 103
Chapter 6: TDP Commands SET STORAGE
SET STORAGE
Function
Changes the virtual storage limits used by TDP.
Syntax
SET STORAGE CP nnnn
FE0CA048
where:
nnnnnnnnnn
maximum number of bytes of virtual storage that will be used for CP I/O
Usage Notes
If the SET STORAGE command is not used, TDP dynamically calculates the value, based on the CCU MAXBLKNM value and the number of started CPs. The minimum value, which is determined by TDP, varies according to the number and types of CPs started, and the values of INITIAL MAXBLKNM and MAXBLKSIZE. The maximum value is 4294967295. SET STORAGE overrides subsequent dynamic changes by TDP, and may prevent additional CPs from being started. Once SET STORAGE is invoked, there is no way to revert to dynamic calculation by TDP without restarting TDP. The current values may be displayed with the DISPLAY STORAGE command. SET STORAGE is intended for use in consultation with NCR Customer Support personnel.
Example
SET STORAGE CP 2000000
6 104
Chapter 6: TDP Commands SET USERCS
SET USERCS
Function
Establishes characteristics of a user-defined character set that is available on the server.
Syntax
SET USERCS name DDNAME DDNAM DDNA DDN DD ddn
FE0CQ101
DDNAME may be abbreviated as DD, DDN, DDNA, and DDNAM.

name ddn
Name of the user-defined character set on the server. MVS or VOS3 JCL DD statement name in the TDP JCL or previously established CMS FILEDEF name that is associated with a file that contains the character set attributes.
Usage Notes
This command does not create a new user-defined character set on the Teradata server, it only provides characteristics of such a user-defined character set that are needed by TDP. The existence of the character set on the server is not validated during execution of the command. Such errors are reported if an attempt is made to use the character set. Character sets supplied by the server cannot be altered using this command. If the specified character set name is that of a character set supplied by the server, no error will be generated but the definition will never be used; the standard definition will be used. If the character set name had been previously defined,that definition is replaced. The DISPLAY USERCS command may be used to display the user defined character sets that have been defined to TDP.
For more information on character sets, see Defining a Character Set on page D-3.
6 105
Chapter 6: TDP Commands SET USERCS
Example
SET USERCS KOREAN_EBCDIC933 DDNAME TDPCS
Completion
TDP2832 KOREAN_EBCDIC933 HAS BEEN DEFINED
6 106
Chapter 6: TDP Commands SET USERID
SET USERID
Function
Changes the Database userid that TDP uses to establish its internal sessions.
Syntax
SET USERID name
FZAPB042
where:
name
name of a database userid consisting of characters from the TDP character set. When supported by the character set, you may include EBCDIC double-byte characters if you: Precede each contiguous group of characters with the Shift-out control character, X0E, and Follow the group with the Shift-in control character, X0F
Usage Notes
Unless this command is specified, TDPUSER is assumed. The specified name is used when TDP internal sessions are next established (either when the IFPs are initially started or as the result of an ENABLE IRF command). The existence of the TDP character set in the database is not validated during the execution of this command. Such errors are reported when the information is subsequently used in attempting to establish TDP internal sessions. The specified userid must already exist in the Database and have the following privileges: SELECT on the DBC.InDoubtLog view DELETE on the DBC.InDoubtLog view EXECUTE on the DBC.TwoPCRule macro With NULL Password
Example 1
SET USERID ANOTHERUSERID
6 107
Chapter 6: TDP Commands SET USERID
Example 2
SET USERID TDPUSER
Completion Message
TDP0393 TDP USERID HAS BEEN SET TO name
Error Messages
Possible error messages are:
TDP0504 TDP0506 TDP0535 TDP0536 TDP0502 UNKNOWN TDP COMMAND NAME: text UNKNOWN OPERAND TO THE SET COMMAND: text TOO FEW OPERANDS FOR THE SET USERID COMMAND TOO MANY OPERANDS FOR THE SET USERID COMMAND LENGTH INCORRECT FOR SET USERID VALUE
6 108
Chapter 6: TDP Commands SHUTDOWN
SHUTDOWN
Function
Stops TDP operation.
Syntax
SHUTDOWN ORDERLY O CANCEL QUICK
FZAPB045
where:
Syntax element . . . Is the specification to . . .
CANCEL QUICK ORDERLY
cancel TDP immediately with a memory dump. log off all sessions before shutting down TDP. disable logons and wait for sessions to end before shutting down TDP. This is the default.
Usage Notes
While this kind of shutdown is in progress . . .
You may execute SHUTDOWN with this option . . .
Orderly Quick
QUICK or CANCEL CANCEL
To obtain a dump in . . .
Use the command . . .
MVS VOS3 VM
MVS DUMP (for an SVC dump), or MVS CANCEL with the DUMP argument. Note that an SVC dump is preferable. CP VMDUMP
6 109
Chapter 6: TDP Commands SHUTDOWN
Example 1
SHUTDOWN CANCEL
Example 2
SHUTDOWN QUI
Completion Message
TDP510 QUICK SHUTDOWN REQUEST ACCEPTED
Example 3
SHUTDOWN O
Completion Message
TDP0510 ORDERLY SHUTDOWN REQUEST ACCEPTED
Example 4
SHUTDOWN
6 110
Chapter 6: TDP Commands START IFP
START IFP
Function
Causes TDP to begin communicating with an IFP.
Syntax
START STA ifpname CIC CCU
FZAPB091
where:
ifpname
IFP with which TDP is to communicate as IFPnnnn, where nnnn is the device number of the even-numbered IFP device, in three or four hexadecimal digits. Specification that this CP requires a communication protocol known as the Segment Protocol. All CPs for the DBC/1012 and CPs implemented by hardware known as an MCA have this requirement. Specification that this CP requires a communication protocol known as the Structure Protocol. All CPs using ESCON and CPs implemented by hardware known as an EBCA have this requirement.
CIC
CCU
Usage Notes
The START IFP command must be executed for at least one IFP before TDP can accept any requests from applications. Once executed, the START IFP command initiates processing that implicitly ATTACHes (establishes a logical and a physical attachment between) the IFP to TDP, if the IFP was not previously ATTACHed The devices for an IFP may be either explicitly or dynamically allocated. Dynamic allocation is the more usual operation since no explicit allocation is required: TDP automatically allocates the required devices. Explicit allocation requires that the following be performed prior to STARTing the IFP:
If using this operating system . . . Do the following . . .
MVS VOS3
Include two DD statements in the JCL procedure that is used to start TDP.
6 111
Chapter 6: TDP Commands START IFP

If using this operating system . . .
Do the following . . .
The DD statements should be in this format: //IFPnnnn DD UNIT=nnn One of these statements is for the even IFP device number, the other for the corresponding odd IFP device number. If a four-digit device number is specified for the UNIT keyword, MVS requires that a slash precede the digits, as in UNIT=/nnnn VM Include two FILEDEFs in the TDP startup EXEC. The FILEDEFs should be in this format: FILEDEF IFPnnnn DUMMY IFP nnnn I
For either operating system, IFPnnnn corresponds to the ifpname used in the START command. IFPnnn and IFP0nnn are equivalent. That is, the command may specify one form and the static system definition may specify the other. If you issue the START IFP command immediately after a STOP IFP command, the IFP must complete the stop process before it can start again.
Example
STA IFP490
Completion Message
IFP490 SUCCESSFULLY STARTED
6 112
Chapter 6: TDP Commands START POOL
START POOL
Function
Establishes and enables a session pool. Session pools are not supported for utilities such as FastLoad, MultiLoad, Archive/Recovery, and FastExport. Because utility programs use special internal run strings, they do not work with session pools.
Syntax
START STA POOL POO DDNAME DD NUMSESS NUM A RUN RU B CHARSET CH C NULLPSWD NUL D LOGON LO username ,password ,' acctid '
FZAPC047
filename
number JOBNAME JO jobname
B runstring ID poolid
C character_set_name D session_attributes
where:
filename
MVS data set or VM file, defined in the TDP startup procedure, that contains START POOL commands. If specified, it must be the only argument specified by the command.
number
number of sessions that are to be established for the pool. This is a required argument unless DDNAME is specified. The deprecated specification FILE is equivalent to DDNAME.
6 113

number may be no larger than the maximum number of sessions (MAXSESS) that has been set by the installation, or the session capacity of the Teradata server jobname indication that the pool is restricted to a job named jobname. (You can establish several pools with the same logon string, but with different job names.) optional run string argument that is used when establishing pool sessions. The default is DBC/SQL. TEQUEL can also be specified. poolid optional, unique identifier of up to eight alphanumeric characters that identifies the pool. If omitted, TDP assigns the pool an identifier in the form POOLnnnn, where nnnn is an ascending number, beginning with 1. character_set_name Character set name with a maximum of 30 characters, to be used in this pool for logons. Choose from the following: EBCDIC EBCDIC037_0E EBCDIC273_0E EBCDIC277_0E KANJIEBCDIC5026_0I KANJIEBCDIC5035_0I KATAKANAEBCDICASCII ASCII LATIN1_0A LATIN9_0A LATIN1252_0A KANJISJIS_0S KANJIEUC_0U UCS2 UTF8 Or any user-defined character set established using the TDP SET USERCS command.
runstring
6 114

While other names may be specified, their characteristics (the codepoint for the space, comma, apostrophe, and quotation symbols; the codepoints for control characters; the encoding scheme, and the rules for monocasing) are assumed to be as for EBCDIC. This character set also defines the characters that can be used in the logon string of the LOGON operand. If omitted, the default TDP character set is used to process this logon string. Since the character set must be known prior to the interpretation of the LOGON value, if CHARSET is needed it should precede LOGON to ensure proper parsing. If CHARSET for other than the TDP default character set follows LOGON, the command is not rejected but a TDP2712 warning message is issued since the logon string may not be properly interpreted, depending on the characteristics of the character set. NULLPSWD optional password in the logon string (specified by the LOGON option). This keyword enables the use of session pools that have implicit logons (logons without Teradata server passwords). The deprecated specification NULLPWD is equivalent to NULLPSWD. session_attributes list of available attributes for all sessions for this pool, as described below. If the Teradata server does not support a specified attribute, the pool does not start. If an attribute is not specified, but the Teradata server has been configured with a default attribute, the default is used.
Attribute Function
TWOPC TERADATA
Causes TDP to establish all sessions in the pool in 2PC mode. Indicates that Teradata transaction semantics are to be used. This keyword is mutually exclusive with the ANSI keyword.
ANSI
Indicates that ANSI transaction semantics are to be used. This keyword is mutually exclusive with the TERADATA keyword.
6 115

DATEFORM
Indicates how dates are processed by the server. DATEFORM values are: ANSI Indicates that ANSI date format is to be used. TERADATA Indicates that Teradata date format is to be used. DEFAULT Indicates that the server uses the default date format associated with the user/server. Since TDP does not know which format the server will use when DEFAULT is specified, only sessions that also specify (or default to) DEFAULT will use the pool. If DATEFORM is omitted, DATEFORM DEFAULT is assumed.
SQL2
Generates a warning when SQL not conforming with to the FIPS 127-2 language standard is used. This keyword is mutually exclusive with the SQL3 keyword.
SQL3
Generates a warning when SQL not conforming with to the FIPS 127-3 language standard is used. This keyword is mutually exclusive with the SQL2 keyword.
username ,password ,acctid
logon string to be used to log the pool sessions on to the Teradata server. The password is optional if the NULLPSWD option is also specified. This argument is required unless DDNAME is specified.
6 116

The userid, password, and account name each consist of characters from the current character set. When supported by the current character set, EBCDIC double-byte characters may be included by preceding each contiguous group of them with the Shift-out control character, X0E, and following this group with the Shift-in control character, X0F. Neither commas, apostrophes, nor quotation marks may be specified as double-byte characters. If the TDP default character set is not appropriate for the logon string, the proper character set must be specified by the CHARSET operand. If CHARSET for other than the TDP default character set follows LOGON, the command is not rejected but a TDP2712 warning message is issued since the logon string may not be properly interpreted, depending on the characteristics of the character set. The deprecated specification STRING is equivalent to LOGON.
Usage Notes
A START POOL command is not processed by TDP until at least one START IFP command and the RUN command has been processed (that is, until at least one IFP has been started). Thus, if a START POOL command occurs in the TDP startup data set (TDPPARM) before either of these commands, the START POOL command is not processed until an IFP is attached and started. A START POOL command may not be processed for one of the following reasons: The command contains syntax errors. A pool having the same logon string (and jobname, if appropriate) already exists. Logons are disabled. The poolid argument of the command is not unique.
When a character set that is not valid is specified, the following message displays:
TDP2711 THE "CHARSET" VALUE IS NOT SUPPORTED
A START POOL command is rejected if a pool already exists with the same logon string JOB specification and session attributes (TWOPC, ANSI/TERADATA, DATEFORM, SQL2/SQL3). The JOB jobname and session attributes restriction is used to reserve pool sessions only for application logon requests that are associated with the specified job and session attributes. If a request matches the restriction of an established pool and the pool has no sessions available (not in use) to satisfy
6 117
the request, the request is rejected. This is true even if an unrestricted pool (that is, one with no restriction) exists with the same logon string. Any logon request that has the same logon string as an unrestricted pool may use sessions from the pool, regardless of the job or address space of the application (provided, of course, that a restricted pool for that job does not also exist). To be considered a match, the logon string of the application must be identical to the logon string of the pool. Specification of NULLPSWD does not affect comparison of the logon strings. If the user password is changed for a userid being used in a session pool, the userid can log on to the Teradata server with the old password while the session pool is active. It may be necessary to use the DDNAME filename specification of the START POOL command and include the command in a data set (under MVS or VOS3) or a file (under VM) that is accessed during TDP startup in the following situations: When a START POOL command exceeds the maximum length (128 characters) allowed for a console command. Because a logon string may contain up to 278 bytes, including commas, apostrophes, and quotation marks (a maximum of 92 bytes for each specificationusername, password, account identifier), it is possible that the START POOL command may exceed 128 characters. When it is necessary to protect the security of a password that is used in the logon string of a START POOL command.
TDP supports sequential files with fixed or varying length unspanned record formats and any logical record length supported by the device/operating system. If the records are fixed 80byte 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. Commands 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 command 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 command continues with the first non-blank column of the next record. A command may be continued onto any number of records. While all characters for all records are normally EBCDIC, the value of the LOGON option may be in another character set. Care must be taken to ensure that the final byte of the logon string appearing at the end of a command is not a value that could be taken as an EBCDIC continuation character when no continuation is intended. To prevent this, a semicolon may be added to the end of any command. The semicolon is discarded before the command is processed. NULLPSWD indicates that Teradata server may process logon requests for the sessions even if they do not supply a password. This requires that the userid be
6 118
GRANTed WITH NULL PASSWORD authority on the server. Refer to either "Teradata RDBMS for UNIX Security Administration Guide" or "Teradata DBS Security Administration Guide". The DBC userid always requires a password so NULLPSWD is effectively ignored for this useridTeradata RDBMS for UNIX Security Administration Guide. Understand that using NULLPSWD in conjunction with GRANTing WITH NULL PASSWORD allows unrestricted access to that userid unless a TDPUAX or TDPLGUX exit is provided to control use of this userid by other means that a password. If exits are used to provide such control, should they be disabled, either explicitly by the DISABLE command, or implicitly as a result of TDPLGUX ABENDing, access is unrestricted.
Completion Messages
When the START POOL command is accepted for processing by TDP, the following message is displayed:
TDP0866 ADDING number SESSIONS TO POOL ID: poolid
When the START POOL command has been processed, the following message is displayed:
TDP0881 POOL ID: poolid IS NOW ENABLED
Example
The following example demonstrates how to set up session pools to be used by an application. In this example, nine session pools are established for Accounts Receivable, Accounts Payable, and Finance. These pools are accessed only via transactions from JOB CICS. Under MVS or VOS3, the following DD statements are added to the startup JCL for TDP:
. . . //TDPPARM //ACCTREC //ACCTPAY //FINANCE . . .
DD DD DD DD
DSN=DBC.TDPPARM,DISP=SHR DSN=DBC.ACCTREC,DISP=SHR DSN=DBC.ACCTPAY(POOLPARM),DISP=SHR DSN=DBC.FINANCE(POOLPARM),DISP=SHR
Under VM, the following FILEDEF statements are added to the startup EXEC for TDP:
. . . FILEDEF TDPPARM DISK TDPn TDPCMD fm
6 119
Chapter 6: TDP Commands START POOL FILEDEF ACCTREC DISK fn ft fm FILEDEF ACCTPAY DISK fn ft fm FILEDEF FINANCE DISK fn ft fm
The <dbcpfx>.TDPPARM data set and the TDPn TDPCMD fm file contain the following commands:
ENABLE LOGONS START IFP6B0 START IFP6B2 START POOL DDNAME ACCTREC START POOL DDNAME ACCTPAY START POOL DDNAME FINANCE RUN
These commands are all echoed to the operator console. The commands contained in the data sets or files that are identified by the ddnames or FILEDEFs referenced by the START POOL commands are not echoed to the system console. The contents of ACCTREC (data set or file) are:
START POOL NUM 15 JOB CICS LOGON AR,MONEYIN START POOL NUM 25 JOB CICS LOGON AR,MONEYIN,ACCT1 START POOL NUM 40 JOB CICS LOGON AR,MONEYIN,ACCT2
The contents of ACCTPAY (data set or file) are:

START POOL NUM 20 JOB CICS LOGON AP,MONEYOUT,ACCT1 START POOL NUM 30 JOB CICS LOGON AP,MONEYOUT,ACCT2 START POOL NUM 5 JOB CICS LOGON AP,MONEYOUT,ACCT3
The contents of FINANCE (data set or file) are:

START POOL NUM 2 JOB CICS LOGON FIN,SPENDIT,DEPT1 START POOL NUM 1 JOB CICS LOGON FIN,SPENDIT,DEPT2 START POOL NUM 3 JOB CICS LOGON FIN,SPENDIT,DEPT3
Note that these session pools are established only after IFP6B0 and IFP6B2 are started.
6 120
Chapter 6: TDP Commands STOP IFP
STOP IFP
Function
Causes TDP to stop communicating with an IFP. While the command completes immediately, the IFP does not actually stop until all activity on the IFP ends. The status in a DISPLAY IFP command indicates STOPPING until all sessions end, and STOPPED thereafter.
Syntax
STOP STO ifpname
FZAPB048
where:
ifpname
FP as IFPnnnn, where nnnn is the device number of the even-numbered IFP device, in three or four hexadecimal digits.
Usage Notes
The purpose of the STOP IFP command is to stop an IFP for servicing without shutting down the TDP to which it is attached. It can also be used if an IFP is to be detached from the current TDP and then attached to another TDP. In this case, once the IFP is stopped (logically detached from the current TDP), it must be physically detached from the current TDP using the DETACH IFP command. All activity on the IFP must end before the IFP stops. On some versions of the Teradata server, the IFP stops when an active request completes. On other versions of the server, all sessions on SPs associated with the CP must end before the IFP will stop. In the latter case, in addition to application sessions, this includes any unassigned session pool sessions and any TDP internal sessions. It may be necessary to stop relevant session pools using the STOP POOL command and relevant TDP internal sessions using the DISABLE IRF command. The START POOL and ENABLE IRF commands may then be used to restore the necessary sessions.
Example
STO IFP490
6 121
Chapter 6: TDP Commands STOP IFP
Completion Messages
TDP1363 STOP IFP COMMAND ACCEPTED
After all activity has ended:

TDP0531 devicename SUCCESSFULLY STOPPED
6 122
Chapter 6: TDP Commands STOP POOL
STOP POOL
Function
Ends one or more session pools in an orderly manner.
Syntax
STOP STO POOL ID poolid ALL
FZAPB049
where:
poolid ALL
unique identifier of the pool that is to be stopped. way to request that all pools be stopped.
Usage Notes
The STOP POOL command does the following: Disables logons to the pool(s) that are to be stopped. Logs off pool sessions that are not in use. Waits for any pool session that is in use to run until the application logs off. The session is then logged off from the Teradata server. When all pool sessions are logged off, the pool is removed.
To terminate existing pool sessions without waiting for them to finish and disable the pools (but not eliminate them), use the LOGOFF POOL command.
Example 1
STO POOL ID: ACTR04
Example 2
STO POOL ALL
Completion Messages
When the STOP POOL command is accepted for processing by TDP, the following message is displayed:
TDP0867 STOPPING POOL ID poolid
When the STOP POOL command has been processed, the following message is displayed:
POOL ID: poolid IS NOW STOPPED
6 123
Chapter 6: TDP Commands TDP INITIAL Commands
TDP INITIAL Commands

Introduction
The HSISPB module that the Teradata server makes available to an application controls the environment in which TDP runs. Certain options specified in the HSISPB may be overridden by including INITIAL commands in the TDPPARM data set used to initialize a TDP.
Restrictions on TDP Initial Commands

INITIAL commands may only be entered from the TDPPARM data set.
Command Summary
The following table lists each INITIAL command, summarizes its use, and identifies the mainframe operating systems to which it applies.
Table 6-2 TDP INITIAL Commands
Command Operating System Use
INITIAL CCU
MVS VOS3 VM
Change limits used by CCU-type CPs.
INITIAL DLYTIME
MVS VOS3 VM
Indicate interval for issuing reminders that all communication with the Teradata server has been lost.
For compatibility with prior releases, this parameter may also be specified as INITIAL RSTTIME. INITIAL IACMODE MVS VOS3 VM INITIAL IOBUFS MVS VOS3 VM INITIAL IOMODE MVS VOS3 VM Choose the mode used by TDP for sending I/O to the Teradata server. Change the number of I/O buffers for CPs not requiring the CCU operand on the START command. Choose the mode of communication between TDP and an application program.
6 124
Chapter 6: TDP Commands TDP INITIAL Commands Table 6-2 (Continued) TDP INITIAL Commands
Command Operating System Use
INITIAL JOBWAIT
MVS VOS3 VM
Choose the amount of time that an application can be in a wait state before TDP initiates an activity to prevent the application from being timed out by the operating system. Control the use of LSQA in address spaces communicating with the RDBMS. While still functional, this command has been replaced by the SET MAXSESS command. Control the TDP identifier that normally appears before the message prefix.
INITIAL LSQA
MVS VOS3
INITIAL MAXSESS
MVS VOS3 VM
INITIAL MSGPREF
MVS VOS3 VM
INITIAL OSSISUFX
MVS VOS3
Associate a TDP with the version of HSIOSSI (if SVC mode) or HSISXMS (if PC mode) that is used by the subsystem in which the TDP is to run. Associate a TDP with the version of the TDPNSPCI module that is used in the TDP subsystem. INITIAL DLYTIME has replaced this command.
INITIAL PCSUFX
MVS
INITIAL RSTTIME
MVS VOS3 VM
INITIAL TRUNCRSP
MVS VOS3 VM
Specifies if truncation of a response is to be indicated by a return code.
INITIAL USERID
MVS VOS3 VM
While still functional if the USERID uses the EBCDIC character set, this command has been replaced by the SET USERID command, which supports all character sets.
The sections that follow provide detailed descriptions of each TDP INITIAL command.
6 125
Chapter 6: TDP Commands INITIAL CCU
INITIAL CCU
Function
Changes limits used during operation of CCU-type CPs.
Syntax
INITIAL CCU MAXBLKNM n MAXBLKSZ n MAXCKSUM n
FE0CQ049
where:
MAXBLKNM
maximum number of channel blocks for any I/O. The value can be 1 through 255; the default is 4.
MAXBLKSZ
maximum size of a channel block used for I/O. The value can be 320 through 65535; the default is 65535.
MAXCKSUM
number of checksum rejections at which the CP will become unusable. A value of zero, the default, indicates that the CP will never be considered unusable due to checksum rejections.
Usage Notes
You can display CCU limits with the DISPLAY CCU command. INITIAL CCU is intended for use in consultation with NCR Customer Service personnel. These values are not necessarily the values that will be used by the CP. Rather, they are TDP's preferences but may be negotiated to other values by the server when communication for each CP is established. While the server may not increase a value, it may decrease it. For MAXCKSUM, the value could be forced to zero, thereby allowing any number of checksum rejections.
Example
INITIAL CCU MAXBLKNM 4 INITIAL CCU MAXBLKSZ 32767 INITIAL CCU MAXCKSUM 13
6 126
Chapter 6: TDP Commands INITIAL DLYTIME
INITIAL DLYTIME
Function
Sets the time interval for issuing reminders that all communication with the Teradata server has been lost.
Syntax
INITIAL INIT DLYTIME ssss
FZAPB050
where:
ssss
time interval in seconds. This interval may not be less than 60 seconds.
Usage Notes
If an interval of less than 60 seconds is specified, 60 seconds is used.
Example
INIT DLYTIME 90
6 127
Chapter 6: TDP Commands INITIAL IACMODE
INITIAL IACMODE
Function
Changes the mode of communication between TDP and an application program.
Syntax
INITIAL INIT IACMODE SVC nnn DYNAMIC IUVC PC
FZAPB087
where:
SVC
specification that the communication mode be a supervisor call (SVC). This option is valid only in the MVS environment, and is equivalent to the old option, CSA.
nnn
number of the SVC to be used. Legal values range from 200 through 255. The value selected must not be currently defined to the rating system. If a value is not specified, 245 is used
DYNAMIC
indication that the SVC is to be installed into MVS by TDP when started, and removed by TDP upon stopping. If DYNAMIC is not specified, the SVC must be installed before starting TDP. (See the Teradata Client for MVS Installation Guide.)
IUCV
specification that the communication mode be Inter-User Communication Vehicle (IUCV). This option is valid only in the VM environment, where it is the default.
PC
specification that the communication mode be a program call (PC). This option is only valid in the MVS environment, where it is the default. It is equivalent to the old option, XMS.
6 128
Chapter 6: TDP Commands INITIAL IACMODE
Usage Notes
The DYNAMIC option must not be specified if multiple TDPs are to use the same SVC number. If DYNAMIC is specified, the first TDP to be stopped removes the SVC from the system, making it unavailable for the other TDPs. When the Teradata RDBMS uses more than one version of the TRDTMAS (MVS) or TRDTHAS (VOS3), each version is identified by a unique SVC number, nnn. The version of the SVC used by an application that uses Call-Level Interface (CLI) routines is controlled by the HSISPB module that the Teradata RDBMS makes available to the application.
Example 1
INIT IACMODE SVC
Example 2
INITIAL IACMODE PC
6 129
Chapter 6: TDP Commands INITIAL IOBUFS
INITIAL IOBUFS
Function
Increase the number of I/O buffers for CPs not requiring the CCU operand on the START command. The command overrides the system defaults.
Syntax
INITIAL INIT IOBUFS number
FZAPB052
where:
number
number of I/O buffers.
Usage Notes
The buffers requested by this command are not used for CPs that require the CCU operand on the START command. If all CPs are of this type, then any use of INITIAL IOBUFS wastes storage. The INITIAL IOBUFS command overrides the system default and is the only way to increase the numbers of I/O buffers before TDP initialization. The system default is a function of the number of IFPs and the workload. This default is appropriate for most situations. The INITIAL IOBUFS command should be used if the D CELLS command shows an excessive number of GETMAINS and/or WAIT COUNTS on the I/O buffers. If this occurs, consult with NCR customer support personnel to determine the optimum number of I/O buffers.
Example
INIT IOBUFS 32
6 130
Chapter 6: TDP Commands INITIAL IOMODE
INITIAL IOMODE
Function
Chooses the mode used by TDP to send I/O to the Teradata server.
Syntax
INIT INITIAL INIT IOMODE EXCP EXCPVR IOSDRIVR DIAG98
FZAPB086
where:
Syntax element . . . Is the specification that . . .
EXCP
I/O be performed through the EXCP instruction (SVC 0). This is the default in the VM environment.
EXCPVR
I/O be performed through the EXCPVR instruction (SVC 114). This is the default in the MVS environment. This option may be used in the VM environment, however, DIAG98 is equivalent and preferred.
IOSDRIVR
the type of I/O be STARTIO. This option is only valid in the MVS environment.
DIAG98
I/O be performed using VM Diagnose 98. This option is available only in the VM environment, VM/SP4 or later.
Usage Notes
EXCPVR or DIAG98 improves system performance in the following ways: Eliminates address translation of channel programs by the I/O supervisor each time the channel program supervisor call is invoked, thus improving the efficiency of I/O operations. Allows address translation for the Channel Control Words (CCWs) that make up the channel programs to be done only once, during TDP initialization. This is because, under EXCPVR or DIAG98, the data areas involved in the I/O operation and the area containing the channel program are page-fixed.
Use of IOSDRIVR reduces CPU use and improves TDP performance by reducing the I/O path length between TDP I/O tasks and the MVS and VOS3
6 131
Chapter 6: TDP Commands INITIAL IOMODE
IOS. Use of the option also avoids SVC interrupts by enabling TDP to pass any new I/O request directly to the IOS.
Example 1
INIT IOMODE EXCP
Example 2
INITIAL IOMODE EXCPVR
Example 3
INIT IOMODE IOSDRIVR
Example 4
INIT IOMODE DIAG98
6 132
Chapter 6: TDP Commands INITIAL JOBWAIT
INITIAL JOBWAIT
Function
Chooses the amount of time that an application can be in a wait state before TDP initiates an activity to prevent the application from being timed out by the operating system.
Syntax
INITIAL INIT JOBWAIT mmmm
FZAPB054
where:
mmmm
time, in minutes. A value of zero indicates that TDP does not attempt to prevent timeouts. This value must be less than 1440 (number of minutes in a day).
Usage Notes
See Job Wait Timeout for VM on page 2-11 in for more information.
Example
INIT JOBWAIT 2
6 133
Chapter 6: TDP Commands INITIAL LSQA
INITIAL LSQA
Function
Controls the use of LSQA in address spaces communicating with the RDBMS. Not available in VM.
Syntax
INITIAL INIT LSQA 24BIT 31BIT
FZAPB055
where:
Syntax element . . . Is the specification that . . .
24BIT
24-bit storage is to be used for LSQA working storage. This is the default configuration if you do not use the INITIAL LSQA command.
31BIT
31-bit storage is to be used for LSQA working storage.
Usage Notes
31BIT may only be specified if all TDPs on the system are running at the current level and specify the 31-bit value.
Example
INIT LSQA 31BIT
6 134
Chapter 6: TDP Commands INITIAL MSGPREF
INITIAL MSGPREF
Function
Controls the TDP identifier that normally appears before the message prefix. The initial setting is ON, which causes all messages to be preceded by the last character of the TDP identifier, a colon and a blank. OFF suppresses this TDP identifier prefix.
Syntax
INITIAL INIT MSGPREF ON OFF COM NOCOM
FZAPB056
where:
Syntax element . . . Is the way to . . .
ON OFF COM NOCOM
display the TDP identifier prefix for all messages. suppress display of the TDP identifier prefix for all messages. display the COMCHAR preceding the TDP identifier. suppress the COMCHAR for all messages.
Usage Notes
Specifying MSGPREF OFF only does not suppress the COMCHAR, which precedes all TDP messages. To suppress the COMCHAR, specify NOCOM, which is optional. If NOCOM is specified, the communication character appears as a blank. When specifying these operands, ON or OFF must precede COM or NOCOM. The default condition is ON and COM for all TDP messages.
Example
INIT MSGPREF OFF NOCOM
6 135
Chapter 6: TDP Commands INITIAL OSSISUFX
INITIAL OSSISUFX
Function
Associates a TDP with the HSI Operating System Subsystem Interface. If the subsystem uses SVC mode, TDP is associated with a version of HSIOSSI. If the subsystem uses PC mode, TDP should be associated with a version of HSI Program Call Services (HSISXMS).
Syntax
INITIAL INIT OSSISUFX OSSI suffix_character
FZAPB057
where:
Syntax element . . .
Is the . . .
suffix_character
suffix character of the HSIOSSI or HSISXMS module to be used. The character may be alphabetic, numeric, or $, #, or @.
Usage Notes
When a Teradata server uses more than one TDP subsystem (for example, a test TDP subsystem and a production TDP subsystem), each subsystem may use a different version of the HSIOSSI (SVC mode) or HSISXMS (PC mode) module to communicate with an application address space. To enable a TDP to distinguish between HSIOSSI or HSISXMS modules, a suffix is appended to the name of each module during the installation of Teradata RDBMS software on the MVS client. When TDP starts, the OSSISUFX is not set. When the INITIAL IOMODE command is executed, the version of HSIOSSI or HSISXMS identified by the suffix character must be compatible with the version of the TDP to be used.
Example
INIT OSSI #
6 136
Chapter 6: TDP Commands INITIAL PCSUFX
INITIAL PCSUFX
Function
Associates a TDP with the version of the TDPNSPCI module that is used by the subsystem in which TDP is running. (MVS only)
Syntax
INITIAL INIT PCSUFX suffix_character
FZAPB058
where:
suffix_character
suffix character of the TDPNSPCI module to be used. The character may be alphabetic, numeric, or $, #, or @. If not specified, the default is I.
Usage Notes
When a Teradata server uses more than one TDP subsystem (for example, a testing TDP subsystem and a production TDP subsystem), each subsystem may use a different copy of the non-space-switched PC program (TDPNSPCI) module to communicate with an application address space. To enable a TDP to distinguish between TDPNSPCI modules, a suffix is appended to the name of each module during the installation of Teradata RDBMS software on the client. The TDPNSPCI module is used only if TDP runs in communication mode PC (Program Call). When using TDP under VM/CMS, the INITIAL PCSUFX command is ignored.
Example
INIT PCSUFX $
6 137
Chapter 6: TDP Commands INITIAL TRUNCRSP
INITIAL TRUNCRSP
Function
Specifies if response truncation is to be indicated by a return code.
Syntax
INITIAL TRUNCRSP RC NORC
FE0CA051
where:
RC
Indicate truncation in return code If not specified, the default is RC.
NORC
Suppress any indication that the response has been truncated
Usage Notes
There is no command to display the current setting. This command is intended for use in consultation with NCR Customer Support personnel.
Example
INIT TRUNCRSP NORC
6 138
Appendix A:
Channel Processor Device and Channel Error Log

This appendix contains details about the channel processor device and channel error log.
A1
Appendix A: Channel Processor Device and Channel Error Log Sample EREP Record
Sample EREP Record

Introduction
TDP logs IFP unit and channel errors in hexadecimal format to an error log on the MVS or VM client. You can access and print the error log by using the appropriate error logging utility, such as the IBM EREP utility for MVS and VM clients. shows a sample record returned by EREP. The four-digit hexadecimal numbers in the left-most column of the record are memory addresses. The tables in the following subsections describe the format and contents of the EREP record and the CSW sense byte: Record Format For CPs That Require the CCU Operand in the START Command Record Format For CPs That Do Not Require the CCU Operand in the START Command Sense Data For CPs That Require the CCU Operand in the START Command Sense Data For CPs That Do Not Require the CCU Operand in the START Command
Figure A-1 Sample EREP Record
RECORD TYPE UNKNOWN OR UNSUPPORTED MODEL 4341 SERIAL NO- 014816
--- RECORD ENTRY SOURCE - OBR VS 2 REL. NONE HH MM SS.TH TIME-15 34 08 72
DAY YEAR DATE- 107 60 JOB
IDENTITY- TDP3 01 33 D0 E0 60 00 00 14
FAILING CCW CSW
00 26 50 70 0E 00 00 14
DEVICE TYPE CODE- 300008D0 PRIMARY CUA 0005B0 SECONDARY CUA 0005B0 HEX DUMP OF RECORD HEADER 30800800 00000000 0060107F 15340872 00014816 43410000 0018 E3C4D7F3 00000000 0133D0E0 60000014 00265070 0E000014 000005B0 300008D0 0038 000005B0 00001800 03000000 00000009 0FA00020 0000000B D2000101 00F10010 0058 0000
FZAPA090
A2
Appendix A: Channel Processor Device and Channel Error Log Record Format
Record Format
For CPs That Require the CCU Operand in the START Command
The following table provides the format and content of the EREP record for devices of a CP that require the CCU operand on the START command:
Byte # (Dec) Content Description
0 1 2 3 4 57 8 11 12 15 16 23 24 31 32 39 40 47 48 49 50 & 51 52 55 56 & 57 58 & 59 60 & 61 62 & 63 64 87
Hexadecimal 30, indicating an Outboard record. System-dependent operating system version. Hexadecimal 08, indicating the time and date are as formatted by the TIME service, plus a hexadecimal 10 if at least Extended Architecture. Hexadecimal 40, indicating a temporary error. Hexadecimal 80, indicating that no channel path is included. Not used. Date in packed decimal format. Time in packed decimal format. CPU identification. TDP jobname. Channel Command Word (CCW) of the failing channel. Channel Status Word (CSW) for 370 architecture. Hexadecimal 03, indicating that three double words of devicedependent are available. Not used. Hexadecimal device number. Hexadecimal device type, as defined to the system. Not used. Hexadecimal device number. Not used. Hexadecimal 0001, indicating the number of sense bytes present. Device-dependent data, as follows:
64 67
EBCDIC characters TRDT, identifying the product.
A3
68 69 70 & 71 72 79 80 81 87
Hexadecimal 01, indicating the current level of the device-dependent data. Hexadecimal S, indicating the Structure Protocol is being used. Hexadecimal CP number. EBCDIC TDPid. Hexadecimal I/O completion code Not used.
88
Sense byte. If at least Extended Architecture, then:

89 100 101 104
Extended Architecture Interrupt Response Block (IRB), which contains the failing CSW. Extended Status Word (ESW).
For CPs That Do Not Require the CCU Operand in the START Command
The following table provides the format and content of the EREP record for devices of a CP that do not require the CCU operand on the START command:
0 1 25 6 7 8 11 12 15 16 17 19 20 & 21 22 & 23
Class/Source of record. System/Release level. Record switches (not used). Not used. Reserved. System date. System time. Machine version code. CPU serial number. CPU model (for example, 3033). Not used.
A4
24 31 32 39 40 47 48 49 51 52 55 57 59 60 & 61 62 & 63 64 87 88 & 89
TDPid. Failing CCW. Content of CSW after I/O error. Count of double words that record uses for device-dependent data. Secondary control unit address associated with final retry of failing I/O device. Device type associated with failing device. Primary control unit address of device being used when failure occurred. Retry count. Number of bytes of sense data (24). Sense data. Not used.
A5
Appendix A: Channel Processor Device and Channel Error Log Sense Data
Sense Data
For CPs That Require the CCU Operand in the START Command
The following table lists the sense bytes and device status bytes as returned in the CSW for devices of CPs that require the CCU operand on the START command:
Sense Byte Status Byte Description
20 10 08
0E 0E 0E
Bus-out Check (hardware error). Equipment Check (device error). Data Check (software error).
For CPs That Do Not Require the CCU Operand in the START Command
The following table lists sense bytes 0 and 1, along with the corresponding device status byte (in hexadecimal) as returned in the CSW for devices of CPs that do not require the CCU operand on the START command:
Sense Byte 0 1 Status Byte
Description
10 08 80 80 80 80 80 80 80 80 80 80 20
01 05 06 07 08 09 0C 0D 0E 10 11 14 19
0E 0E 0E 0E 0E 0E 0E 0E 0E 0E 0E 0E 0E
CIC hardware error. Bus/Tag in driver fault. Illegal field id for dev 0. Message header size error for dev 0. Message count error for dev 0. Message size error for dev 0. Odd byte xfer for dev 0. Input Queue empty for dev 0 write. Rewind for dev 0 without a Writekey. Dev 1 read stopped before all the data was transferred. Two consecutive dev 0 Writekeys. Unrecognized command byte during Initial Selection sequence. Bad parity on Command byte during Initial Selection or following a Write operation.
A6
Sense Byte 0 1
Status Byte
Description
10 00 00 80 80 80
28 30 33 39 43 44
0D 22 85 0E 0E 0E
CP did not respond to CIC interrupt in allotted time (1 second). IOP Startup byte The CIC has gone from OFFLINE to ONLINE. Write operation exceeded maximum CIC local buffer length. WriteCount specified a max block size too small for the Teradata server WriteKey block size greater than maximum allowed
A7
A8
Appendix B:
Parcel Flavors
This appendix contains details about parcel flavors.
B1
Appendix B: Parcel Flavors What is a Parcel?
What is a Parcel?
A parcel is a discrete logical unit of information consisting of two parts: The parcel header that contains a flavor field and a length field. The parcel body that contains any data associated with the parcel.
Definitions for the parcel headers are located on a release tape as shown below:
For this language . . . Definitions are located in the. . .
IBM Assembler C COBOL PL/I
TRDSPH in library SAMPLIB (MVS), filetype SAMPLE (VM). TRDSPHH in library SAMPLIB (MVS), filetype SAMPLE (VM). TRDSPHC in library SAMPLIB (MVS), filetype SAMPLE (VM). TRDSPHP in library SAMPLIB (MVS), filetype SAMPLE (VM).
Definitions for the parcel flavors and content of the body headers are located on a release tape as shown below:
For this language . . . Definitions are located in the. . .
IBM Assembler
TRDSPB in library SAMPLIB (MVS), filetype SAMPLE (VM).
Parcel Structure
There are two formats of parcel headers. The maximum length of parcels using the first format is 65535 bytes; the maximum length of parcels using the second format is 4,294,967,295. The format of the first is:
Flavor 0
Length 1 2 3 4
Body 65535
maximum
GQ02B014
The format of the second is:
Flavor 0
Unused 1 2 3 4
Length 78
Body 4294967287
maximum
GQ02C014
The two types of parcel headers may be intermixed in the same request or response. A response will only contain a parcel with the enlarged header if at
B2
least one parcel for that request used an enlarged parcel header. Furthermore, parcels whose length is less than or equal to 65535 may use either header format.
Flavor Field
The flavor field indicates the type of parcel and differentiates the two formats of parcel headers. If the leftmost bit is zero, the header is the original, smaller format. If the leftmost bit is one, the header is the enlarged format. The remaining fifteen bits are the parcel flavor.
Table B-1 Parcel Flavors
Flavor 1 3 5 7 9 11 13 17 19 21 23 25 27 31 34 36 38 47 68 Parcel Name Flavor 2 4 6 8 10 12 14 18 20 22 24 26 28 33 35 37 46 49 69 Parcel Name
Req Data KeepRespond Cancel Failure EndStatement FMReq Ok NullField TitleEnd FormatEnd SizeEnd RecStart Rewind Position Logon Run PosEnd IndicData
RunStartup Respond Abort Success Record EndRequest FMRunStartup Field TitleStart FormatStart SizeStart Size RecEnd With EndWith Logoff PosStart Error IndicReq
B3
Appendix B: Parcel Flavors What is a Parcel? Table B-1 (Continued) Parcel Flavors
Flavor 71 85 88 115 117 120 122 124 128 131* 134* 136* 140 142 144 146 148 150 152 154 Parcel Name Flavor 72 86 114 116 118 121 123 125 129 132* 135* 137 141 143 145 147 149 151 153 Parcel Name
DataInfo Options Connect VoteRequest Cmmt2PC CursorHost Flagger XIVRunStartup Multi-TSR Get Methods Single-signon response UserNameRequest MultipartData MultipartIndicData MultipartRecord DataInfoX MultipartReq ElicitData ElicitDataReceived ExtendedKeepRespond
IVRunStartup PrepInfo
VoteTerm Abrt2PC CursorDBC XIndicReq PrepInfoX SP options Methods Response Auth-info UserNameResponse EndMultipartData EndMultipartIndicData EndMultipartRecord MultipartRunStartup ElicitDataMailbox ElicitFile ExtendedRespond
* Used ony between network attached clients and the Gateway. No further description is provided in this document.
Length Field
The length field contains the length in bytes of the entire parcel, which is the total length of the flavor, length, and body fields.
B4
Parcel Body
The parcel body consists of zero or more fields. The number of fields, their names, contents, and lengths depend on the parcel flavor.
B5
Appendix B: Parcel Flavors Parcel Types
Parcel Types
There are two parcel types:
Parcel type . . . Is generated for . . .
Request Response
requests sent to the Teradata server responses sent from the Teradata server to a client
The following two sections describe request and response parcels.
B6
Appendix B: Parcel Flavors Request Parcels: Overview
Request Parcels: Overview

The following table lists the request parcels by flavor, name, use, length, and the names of fields contained in the parcel body.
Table B-2 Request Parcels Flavor Definitions
Flavor Parcel Name Use
1* 2 3* 4 5 6 7
Req RunStartup Data Respond KeepRespond Abort Cancel
Initiates a request (Record Mode) Executes the users startup request (Record Mode) Contains data for a Teradata SQL request (Record Mode) Requests a portion of Teradata SQL response Requests a portion of Teradata SQL response without discarding response Attempts to abort a request Discards Teradata SQL response and closes Teradata SQL request; discards those segments
of a segmented data request that have already been sent.
13 * 14 31 36 37 38
FMReq FMRunStartup Rewind Logon Logoff Run
Initiates a request (Field Mode) Executes the users startup request (Field Mode) Positions spool file pointer to beginning of the spool file Establishes a session Terminates a session Connects to the specified IFP partition (for DBC/1012), Applications Processor (for 3600), or node (for SMP/MPP platforms) Contains data for a Teradata SQL request (Indicator Mode) Initiates a request (Indicator Mode) Sends description of whichever data parcel follows it Executes the users startup request (Indicator Mode)
68 * 69 * 71 * 72
IndicData IndicReq DataInfo IVRunStartup
B7
Appendix B: Parcel Flavors Request Parcels: Overview Table B-2 (Continued) Request Parcels Flavor Definitions
85 88 *
Options Connect
Specifies which PREPARE options are used when a request is sent to the Teradata server Connects to the specified IFP partition (for DBC/1012), Applications Processor (for 3600), or node (for SMP/MPP platforms) Session options Requests a 2PC vote Requests commitment of the current 2PC transaction and returns a vote Requests commitment of the current 2PC in-doubt transaction Aborts the current 2PC transaction Provides cursor information. Indicates a request (Extended Indicator Mode). Executes the users startup request (Extended Indicator Mode). Requests return of the userid assigned to the session. Contains data for an SQL request (Multipart mode) End of data for a request (Multipart mode) Contains data for an SQL request (Multipart Indicator mode) End of data for a request (Multipart Indicator mode) Sends description of subsequent data parcels (Multipart mode) Executes the user's startup request (Multipart mode) Initiates a request (Multipart mode) Requests a portion of Teradata SQL response. Requests a portion of Teradata SQL responsewithout discarding response.
114 115 116 117 118 120 * 123 * 124 136 140 * 141 * 142 * 143 * 146 * 147 * 148 * 153 154
SessionOptions VoteRequest VoteTerm Cmmt2PC Abrt2PC CursorHost XIndicReq XIVRunStartup UserNameRequest MultipartData EndMultipartData MultipartIndicData EndMultipartIndicData DataInfoX MultipartRunStartup MultipartReq ExtendedRespond ExtendedKeepRespond
* Parcel is described in Teradata Call-Level Interface Version 2 for Channel-Attached Systems.
B8
Appendix B: Parcel Flavors Response Parcels: Overview
Response Parcels: Overview

These parcels are generated by the Teradata server. The following table lists the response parcels by flavor, name, and use. Refer to the Teradata Call-Level Interface Version 2 for Channel-Attached Systems for full descriptions of these parcels.
Table B-3 Response Parcels Flavor Definitions
8 9 10
Success Failure Record (Record Mode)
Indicates that the specified Teradata SQL statement completed successfully Indicates that the specified statement has failed and the entire transaction was rolled back Returns one row of selected results
10
Record (Indicator Mode)
Returns one row of selected results
11 12 17 18 19 20 21 22 23 24 25 26
EndStatement EndRequest Ok Field NullField TitleStart TitleEnd FormatStart FormatEnd SizeStart SizeEnd Size
Delimits the end of the results from the specified Teradata SQL statement Delimits the end of a Teradata SQL response to a Teradata SQL request Indicates that the specified Teradata SQL statement completed successfully (Field Mode) Contains returned information (data value, title, format, or echo) Returns a null data value for a field Delimits the start of a set of Title parcels Delimits the end of a set of Title parcels Delimits the start of a set of format-containing Field parcels Delimits the end of a set of format-containing Field parcels Delimits the start of a set of Size parcels Delimits the end of a set of Size parcels Specifies the width of a column of selected results
B9
Appendix B: Parcel Flavors Response Parcels: Overview Table B-3 (Continued) Response Parcels Flavor Definitions
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 Delimits the end of a set of data-value-containing Field and Null-Field parcels or a set of echoed string-containing Field parcels Delimits the start of a set of parcels for the specified WITH clause Specifies the column number being summarized Delimits the end of a set of parcels for the specified WITH clause Returns mailbox (destination) information from the Teradata server Delimits the start of a set of Position parcels Delimits the end of a set of Position parcels Indicates that the specified statement has an error not serious enough to cause rollback Returns a description of the following Indicator Mode Record parcels Returns column information from the Teradata server when a Teradata SQL statement has been sent with a Request Processing Option of Prepare and a Response Mode of Indicator. Returns cursor information. Returns language non-conformances. Returns column information from the Teradata server when a Teradata SQL statement has been sent with a Request Processing Option of Prepare and a Response Mode of Extended. Returns the userid assigned to the session. Returns selected results (Multipart mode) Indicates end of selected results for one row (Multipart mode) Returns a description of subsequent parcels (Multipart mode) Indicates the server address to which elicited data is to be routed
28
RecEnd
33 34 35 39 46 47 49 71 86
With Position EndWith RunResponse PosStart PosEnd Error DataInfo PrepInfo
121 122 125
CursorDBC Flagger PrepInfoX
137 144 * 145 * 146 * 149
UserNameResponse MultipartRecord EndMultipartRecord DataInfoX ElicitDataMailbox
B 10
Appendix B: Parcel Flavors Response Parcels: Overview Table B-3 (Continued) Response Parcels Flavor Definitions
150 * 151 * 152 *
ElicitData ElicitFile ElicitDataReceived
Indicates that data must be supplied Indicates that the contents of a file must be supplied Indicates that elicited data was received by the server.
* Parcel is described in Teradata Call-Level Interface Version 2 for Channel-Attached Systems
B 11
Appendix B: Parcel Flavors Parcel Descriptions
Parcel Descriptions
The following alphabetized sections describe parcels generated by user applications and the Teradata server.
B 12
Appendix B: Parcel Flavors Abort
Abort
Purpose
Terminates processing of the active request for a session. CLIv2 creates this parcel in response to an abort request or to a logoff of a session in which a request is active.
Usage Notes
The Abort parcel is sent in a one-way request asynchronously, with the start request carrying the Teradata SQL request to be aborted.
If . . . Then . . .
the Teradata server is processing the specified request the request had been completed upon receipt of the abort
the request is aborted and the Failure parcel is returned. the abort is ignored.
Field Data
The following table lists field information for Abort Parcel.
Flavor Parcel Body Length Parcel Body Fields
none
B 13
Appendix B: Parcel Flavors Abrt2PC
Abrt2PC
Purpose
Aborts the current transaction for a 2PC session. CLIv2 creates this parcel at the direction of the coordinator. The parcel can be submitted whenever there is an open transaction.
Usage Notes
Use of this parcel requires Teradata RDBMS for UNIX version 2 release 2 (or later), or Teradata DBS for TOS version 1 release 5 (or later). The successful response is a Failure parcel.
If . . . Then . . .
there is no open transaction the session is not in 2PC mode
an Error parcel is returned. a Failure parcel is returned.
Field Data
The following table lists field information for Abrt2PC Parcel.
118
none
B 14
Appendix B: Parcel Flavors Cancel
Cancel
Purpose
Either terminates Teradata server output for the request, or cancels segments of request data previously sent.
Usage Notes
The parcel is generated by CLIv2 at the direction of the application. When used to terminate Teradata server output, this parcel deletes spool files that contain the results of a Teradata request. The response is an End Request parcel. When used to cancel segments of a request, this parcel deletes segments that were previously received by the Teradata server. The response is a Failure parcel.
Field Data
The following table lists field information for Cancel.
none
B 15
Appendix B: Parcel Flavors Cmmt2PC
Cmmt2PC
Purpose
Commits the current in-doubt transaction for a 2PC session.
Usage Notes
Use of this parcel requires Teradata RDBMS for UNIX version 2 release 2 (or later), or Teradata DBS for TOS version 1 release 5 (or later). CLIv2 creates this parcel at the direction of the coordinator. The Cmmt2PC parcel should be submitted after a success response has been returned for a vote request parcel.
If . . . Then . . .
there is no transaction open for the session the current transaction is not in-doubt or not even in 2PC mode to begin with anything else
an Error parcel is returned. a Failure parcel is returned. a Success parcel is returned.
Field Data
The following table lists field information for Cmmt2PC.
117
none
B 16
Appendix B: Parcel Flavors FMRunStartup
FMRunStartup
Purpose
Executes the users Startup request and returns the results in Field Mode.
Usage Notes
If a startup request is not stored with the data base, the response is an Error parcel with error code 3747.
Parcel Data
This parcel is generated by CLIv2 at the direction of the application.
14
none
B 17
Appendix B: Parcel Flavors IVRunStartup
IVRunStartup
Purpose
Executes the users startup request and returns the results in Indicator Mode.
Usage Notes
If a startup request is not stored with the database, the response parcel is an Error parcel with error code 3747. This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the IVRunStartup parcel.
72
none
B 18
Appendix B: Parcel Flavors KeepRespond
KeepRespond
Purpose
Conveys the current length of the input (response) buffer.
Usage Notes
The KeepRespond parcel requests as many response parcels as will fit in the specified MaxMsgSize. If the KeepRespond parcel is used in a start request or continue request and the start response or continue response contains the EndRequest parcel, the spool file is retained on the Teradata server. In general, the spool file is deleted in any of the following situations: A Cancel parcel is issued The EndRequest parcel is returned in response to a continue request that contained a Resp parcel An abort operation occurs A logoff operation occurs
This parcel is generated by CLIv2 at the direction of the application
Parcel Data
The following information applies to the KeepRespond parcel.
MaxMsgSize: 2 byte unsigned integer
Fields
MaxMsgSize is the maximum number of bytes that can be returned to the client in one response. The minimum allowable buffer size is 256 bytes, hence MaxMsgSize must be greater than or equal to 256. The maximum value is 65535.
B 19
Appendix B: Parcel Flavors ExtendedKeepRespond
ExtendedKeepRespond
Purpose
Conveys the current length of the input (response) buffer.
Usage Notes
The ExtendedKeepResponse parcel requests as many response parcels as will fit in the specified MaxMsgSize. If the ExtendedKeepResponse parcel is used in a start request or continue request and the start response or continue response contains the EndRequest parcel, the spool file is retained on the Teradata server. In general, the spool file is deleted in any of the following situations: A Cancel parcel is issued The EndRequest parcel is returned in response to a continue request that contained a Response parcel An abort operation occurs A logoff operation occurs
Parcel Data
The following information applies to the ExtendedKeepResponse parcel.
154
Fields
B 20
Appendix B: Parcel Flavors ExtendedRespond
ExtendedRespond
Purpose
Requests response data from the Teradata server. Typically, it carries the current length of the input (response) buffer.
Usage Notes
When the last record from a spool file is sent in response to a start or continue request containing a Respond parcel, the spool file is deleted. This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the Respond parcel.
Flavor
Parcel Body Length
Parcel Body Fields
153
Fields
B 21
Appendix B: Parcel Flavors Logoff
Logoff
Purpose
Terminates the session.
Usage Notes
This parcel is generated by CLIv2 at the direction of the application
Parcel Data
The following information applies to the Logoff parcel.
37
none
B 22
Appendix B: Parcel Flavors Logon
Logon
Purpose
Establishes a session if the userid and password are valid.
Usage Notes
If an account is not supplied, the default account for the user is used. This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the Logon parcel.
36
278
LogonString: 5 to 278 bytes
Field
LogonString is a character string containing the following elements:
userid, password[, account]
The userid is the users identification. It must consist of at least one character and may consist of as many as 30 characters. Each character may require 1, 2, or 3 bytes, depending on the character set used. Therefore, up to 90 bytes may be necessary to specify the field. The userid may be enclosed in apostrophes, each of which requires 1 byte (2 bytes if Unicode). Therefore, the maximum length is 92 bytes. Note that SQL terminal symbols (such as apostrophes) must always come from the shortest repertoire; that is 1 byte. Terminal symbols are never 3 bytes. The userid and password must be separated by a comma. The password is the users password. It must consist of at least one character, and may consist of as many as 30 characters. Each character may require 1, 2, or 3 bytes, depending on the character set used. Therefore, up to 90 bytes may be necessary to specify the field. The password may be enclosed in quotation marks, each of which requires 1 byte (2 bytes if Unicode). Therefore, the maximum length is 92 bytes. Note that SQL terminal symbols (such as quotation marks) must always come from the shortest repertoire; that is 1 byte. Terminal symbols are never 3 bytes.
B 23
Appendix B: Parcel Flavors Logon
If the account is not omitted, the password and account must be separated by a comma. The userid, password, and account name each consists of characters from the session character set. When supported by the session character set, double-byte characters may be included by preceding each contiguous group of them with the Shift-out control character, X0E, and following this group with the Shift-in control character, X0F. Any TDP identifier and delimiting slash must be specified in the standard EBCDIC character set. Neither commas nor blanks may be specified as double-byte characters. Note: The password is usually required, but it may be optional in the logon string submitted by the application if the site has an exit routine that validates the userid. The account (optional) is the account under which the user is logging on. The account may consist of as many as 30 characters, and it must be enclosed in apostrophes. Any apostrophe in the account name must be represented by two apostrophes. The second apostrophe is not counted toward the limit of 30 characters. Each character may consist of 1, 2, or 3 bytes, depending on the character set used. If the account string consists of 30 apostrophes, and is encoded in Unicode (2byte terminal symbols), 124 bytes are necessary to specify the field. The userid and password must satisfy the lexical characteristics of Teradata SQL words. See the description of lexical characteristics in Teradata DBS Reference Manual (TOS), Volume 1 (Database Design and Administration or Teradata RDBMS SQL Reference.
B 24
Appendix B: Parcel Flavors Multi-TSR
Multi-TSR
Purpose
Provides segments of a request that is too large to fit into the maximum parcel size. This parcel is currently only used for the text of Stored Procedures.
Usage Notes
This parcel is generated by CLIv2 when the Segment Data option is specified by the application.
Parel Data
128
SequenceNumber: 2 bytes Status:1 byte
Fields
The SequenceNumber field specifies the order of the segment relative to other segments. It is a binary value starting at one and increasing by one for each Multi-TSR parcel. The Status field specifies the type of segment. A binary one indicates that this is the last segment. Otherwise the value is a binary zero.
B 25
Appendix B: Parcel Flavors Options
Options
Purpose
Specifies which statement options are used when a request is sent to the Teradata server.
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.
85
10
ResponseMode: 1 byte Function: 1 byte Select-data: 1 byte RFU1: 1 byte RFU2: 1 byte RFU3: 1 byte RFU4: 1 byte RFU5: 1 byte RFU6: 1 byte RFU7: 1 byte
Fields
The following information applies to Options fields. ResponseMode 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 X specifies Extended Mode If this field contains a binary zero, the Teradata server uses the mode specified elsewhere (in the Req, IndicReq, or FMReq parcel) in the request.
B 26
Appendix B: Parcel Flavors Options
When two or more parcels in a request specify conflicting modes, the Teradata server 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: B specifies that a PrepInfo parcel is built for each statement in the request and that the request should be executed B 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. P specifies that a PrepInfo parcel is built for each statement in the request E specifies that the request should be executed X specifies Extended Indicator Mode A binary zero in this field is interpreted as an E. RFU1 through RFU7 are reserved for future use and must be set to binary zero. An error occurs if these fields are not set to binary zero.
B 27
Appendix B: Parcel Flavors Respond
Respond
Purpose
Requests response data from the Teradata server. Typically, it carries the current length of the input (response) buffer.
Usage Notes
When the last record from a spool file is sent in response to a start or continue request containing a Respond parcel, the spool file is deleted. This parcel is generated by CLIv2 at the direction of the application
Parcel Data
The following information applies to the Respond parcel.
Fields
B 28
Appendix B: Parcel Flavors Rewind
Rewind
Purpose
Repositions spool file pointers to the beginning of the spool file. Subsequent Resp or KeepResp parcels return data starting from the beginning of the spool file. This operation may occur at any point when reading a response.
Usage Notes
Parcel Data
The following information applies to the Rewind parcel.
31
none
B 29
Appendix B: Parcel Flavors Run
Run
Purpose
Establishes a connection between an application and Teradata SQL.
Usage Notes
The Run parcel is sent after a logon has been completed or when the application requires a different partition in the Teradata server. This parcel is generated by CLIv2 on behalf of the application. The response to a Run parcel is a RunResponse parcel.
Parcel Data
The following information applies to the Run parcel.
38
16
PartitionName: 16 bytes
Fields
PartitionName is the name of the partition to which start requests are to be sent. If the application submits a partition name with less than 16 bytes, CLIv2 right-pads it with blanks. Valid PartitionName values include the following:
Partition Name Purpose
DBC/SQL RBM MONITOR
For sending Teradata SQL statements.
For communicating with the Resolver Base Module. For communicating with the Performance Monitor.
Note: The RBM and MONITOR partitions are valid only for Teradata RDBMS for UNIX version 2 release 2 (or later), and for Teradata DBS for TOS version 1 release 5 (or later).
B 30
Appendix B: Parcel Flavors RunStartup
RunStartup
Purpose
Executes the users startup request and returns the results in Record Mode.
Usage Notes
If a startup request is not stored with the data base, the response parcel is an Error parcel with error code 3747. This parcel is generated by CLIv2 at the direction of the application
Parcel Data
The following information applies to the RunStartup parcel.
none
B 31
Appendix B: Parcel Flavors SessionOptions
SessionOptions
Purpose
Sets various options for a session.
Parcel Data
The following information applies to the SessionOptions parcel.
114
10
Transaction Semantics: type = CHAR(1) Mode: type = CHAR(1) Language Conformance: type = CHAR(1) DateForm: type = CHAR(1) unused: 6 bytes
Fields
Semantics specifies the semantics to be used for requests within a transaction. Valid settings are:
Setting Description
D T A
Default semantics. Teradata semantics. ANSI semantics.
Mode indicates whether or not the system is in 2PC mode. Two-phase commit is available only for Teradata RDBMS for UNIX version 2 release 2 (or later), and for Teradata DBS for TOS version 1 release 5 (or later). Valid settings are:
Setting Description
2 N
Two-phase commit (2PC) mode. Non-2PC mode.
Conformance specifies whether or not SQL requests are to be checked for conformance with a particular language definition.
B 32
Appendix B: Parcel Flavors SessionOptions
Valid settings are:

Setting Description
N 2 3
No conformance. ANSI entry-level (FIPS 127-2). ANSI intermediate-level (FIPS 127-3). Note: FIPS 127-3 conformance is not supported by the Teradata RDBMS for UNIX release 2.
B 33
Appendix B: Parcel Flavors UserNameRequest
UserNameRequest
Purpose
Requests return of the userid assigned to the session.
Usage Notes
When present, this prcel must be placed immediately after the Connect parcel.
136
None
B 34
Appendix B: Parcel Flavors UserNameResponse
UserNameResponse
Purpose
Returns the userid assigned to the session.
Usage Notes
This parcel may appear anywhere before the only End-request parcel.
137
Useridlength: 2
The Userid-length field is a two-byte unsigned integer containing the number of bytes in the Userid field. The Userid field is a character string encoded in the character set of the associated request, varies in length between 1 and 90 bytes, and contains the userid assigned to the session. The length is contained in the Userid-length field.
Userid: 1 to 90
B 35
Appendix B: Parcel Flavors VoteRequest
VoteRequest
Purpose
Requests a vote in a 2PC session.
Usage Notes
Two-phase commit is available only for Teradata RDBMS for UNIX version 2 release 2 (or later), and for Teradata DBS for TOS version 1 release 5 (or later). The vote request parcel can be sent alone, or in a message (at the end of a sequence of request and data parcels that define a Teradata SQL statement). If the vote request is sent in the same message as a Teradata SQL statement, then the request follows the rules for a multi-statement request; that is, all statements succeed, or all fail. If your program is using the Initiate with Protocol-Function with the vote protocol function, then the VoteRequest parcel is included after the request and data parcels. The response is one of the following: A Success parcel, indicating that the Teradata server voted Yes, and that the transaction is now in-doubt. A Failure parcel, indicating either that the Teradata server has voted No and rolled the transaction back, or that the session is not in 2PC mode. The error code in Failure parcel indicates why the Teradata server did not commit the transaction
Parcel Data
The following information applies to the VoteRequest parcel.
115
64
Coordinator (32 bytes) RunUnitID (32 bytes)
Fields
The Coordinator field contains the text string name of the coordinator for the protocol. The string consists of a two-byte length, followed by a 30-byte name.
B 36
Appendix B: Parcel Flavors VoteRequest
The RunUnitID field contains a text string identifier of the run unit currently active for the session. The string consists of a two-byte length, followed by a 30-byte name.
B 37
Appendix B: Parcel Flavors VoteTerm
VoteTerm
Purpose
Requests a vote-and-terminate action in a 2PC session. The VoteTerm parcel either can be sent alone or in a message (at the end of a sequence of request and data parcels that define a Teradata SQL statement).
Usage Notes
Two-phase commit is available only for Teradata RDBMS for UNIX version 2 release 2 (or later), and for Teradata DBS for TOS version 1 release 5 (or later). If the VoteTerm parcel is used with updates that change existing data, it will always result in a commit. If an immediate commit is not desired, use the VoteRequest parcel instead of the VoteTerm parcel. If the VoteTerm parcel is sent in the same message as a Teradata SQL statement, then the vote and terminate request follows the rules for a multi-statement request (all statements succeed, or all fail). If your program is using the Initiate with Protocol-Function with the vote/terminate function, then the VoteTerm parcel is included after the request and data parcels. The response is one of the following: A Success parcel indicating that the Teradata server has committed the transaction A Failure parcel indicating that the Teradata server has rolled back the transaction or that the session is not in 2PC mode. The error code in the Failure parcel indicates why the Teradata server could not commit the transaction.
Parcel Data
The following information applies to the VoteTerm parcel.
Flavor Parcel BodyLength Parcel Body Fields
116
none
B 38
Appendix B: Parcel Flavors XIVRunStartup
XIVRunStartup
Purpose
Executes the users startup request and returns the results in Extended Indicator Mode.
Usage Notes
If a startup request is not stored with the database, the response parcel is an Error parcel with error code 3747. This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the XIVRunStartup parcel.
Flavor Parcel BodyLength Parcel Body Fields
124
none
B 39
Appendix B: Parcel Flavors XIVRunStartup
B 40
Appendix C:
How to Read the Syntax Diagrams

This appendix describes the rules that apply to the syntax diagrams used in this book.
Notation Conventions
The following table defines the notation used in this section:
Item
Definition / Comments
Letter Number
An uppercase or lowercase alphabetic character ranging from A through Z. A digit ranging from 0 through 9. Do not use commas when entering a number with more than three digits.
C1
Appendix C: How to Read the Syntax Diagrams
Item
Definition / Comments
Word
Variables and reserved words. IF a word is shown in . . . UPPERCASE LETTERS THEN it represents . . . a keyword. Syntax diagrams show all keywords in uppercase, unless operating system restrictions require them to be in lowercase. If a keyword is shown in uppercase, you may enter it in uppercase or mixed case. lowercase letters lowercase italic letters lowercase bold letters UNDERLINED LETTERS a keyword that you must enter in lowercase, such as a UNIX command. a variable such as a column or table name. You must substitute a proper value. a variable that is defined immediately following the diagram that contains it. the default value. This applies both to uppercase and to lowercase words.
Spaces Punctuation
Use one space between items, such as keywords or variables. Enter all punctuation exactly as it appears in the diagram.
Paths
The main path along the syntax diagram begins at the left, 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. Paths that are too long for one line use continuation links. Continuation links are small circles with letters indicating the beginning and end of a link:
A
FE0CA002
C2
When you see a circled letter in a syntax diagram, go to the corresponding circled letter and continue.
Required Items
Required items appear on the main path:
SHOW
FE0CA003
If you can choose from more than one item, the choices appear vertically, in a stack. The first item appears on the main path:
SHOW CONTROLS VERSIONS
FE0CA005
Optional Items
Optional items appear below the main path:
SHOW CONTROLS
FE0CA004
If choosing one of the items is optional, all the choices appear below the main path:
SHOW CONTROLS VERSIONS
FE0CA006
You can choose one of the options, or you can disregard all of the options.
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.
ENABLE ENA TDPSTATS
FE0CA042
In the above syntax, the following formats are valid: SHOW CONTROLS SHOW CONTROL
C3
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.
, ( cname 4 )
FE0CA015
The following rules apply to loops:

IF . . . there is a maximum number of entries allowed THEN . . . the number appears in a circle on the return path. In the example, you may enter cname a maximum of 4 times. 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.
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. A name for the excerpted piece appears between the break marks in boldface type.
C4
The named phrase appears immediately after the complete diagram, as illustrated by the following example.
LOCKING A HAVING con excerpt where_cond , cname , col_pos
JC01A014
excerpt
C5
C6
Appendix D:
Overview of SET USERCS

This appendix provides an overview of how character sets are defined that can be applied using the SET USERCS, command.
D1
Appendix D: Overview of SET USERCS Defining a Character Set
Defining a Character Set

The actual definition of the character set is contained in the file associated with the specified DDNAME. Sequential files with fixed or varying length unspanned record formats are supported. 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.
D2
Appendix D: Overview of SET USERCS Directives
Directives
Each statement contains a directive or is associated with a directive that identifies the purpose of the statement. A directive is analogous to a command but different terminology is used to prevent confusion with true TDP commands. The following directives are supported:
Table D-1 Directives
Directive Function
CHAR
Defines the syntactic characters. Explicitly begins a definition and possibly the encoding scheme.
CHARSET END INCLUDE MONOCASE SANITIZE UNICODE
Ends processing of records in the file. Ignored by TDP, allowing the same file to be used by both CLIv2 and TDP. Defines characters that have both lower and upper case. Defines valid characters for TDP messages sent using operating system facilities. Defines the syntactic characters and characters that have both lower and upper case.
A file describes one or more character sets, although only one description is used by each SET USERCS command. When multiple descriptions are present, each 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 UNICASE directives may appear in any order within a description. If a CHAR, MONOCASE, SANITIZE, or UNICODE directive appears before a CHARSET directive, then a character set description is implicitly begun -- in effect, a CHARSET directive with no operands is assumed.
D3
CHAR
The CHAR directive defines the syntactic characters of importance to TDP. Table D-2 Syntax Definitions
Item Function
| ... <>
Indicates a choice of operands. Indicates the previous syntax element may be repeated zero or more times.
Used to enclose optional syntax elements.
Syntax
CHAR SPACE xx COMMA xx COM xx DBLQUOTE xx DBL xx APOSTROP xx APO x ...
JCM_D001
Usage Notes
The length of each value is determined by the encoding scheme for the character set. For the characters of interest to TDP, the length is always two except for UCS2 encoding, for which the length is four. The CHAR directive may be specified more than once for each character set. If the same character is defined more than once for a character set (either on a single CHAR directive, on multiple CHAR directives, or on a CHAR and a UNICODE directive), the last value is used. All four characters must be defined to form a complete character set description. If no CHARSET directive precedes CHAR, then a character set description is implicitly begun -- in effect, a CHARSET directive with no operands is assumed.
Example
Define the relevant syntactic characters for IBM Code Page 833. CHAR SPACE 40 COMMA 6B APOSTROP 7D DBLQUOTE 7F
CHARSET
The CHARSET directive explicitly begins a definition and possibly the encoding scheme.
D4
Syntax
CHARSET CHAR < NAME NAM charsetname > < ENCODING ENCO A E I R S T U ASCII EBCDIC IBMSOSI BIGFIVE SJIS EUC-CN EUC-JP EUC-KR UCS2 UTF8 >
JCM_D002
Usage
When the NAME operand is specified, if this name does not match the character set name specified on the SET USERCS command, this directive and all directives until the next CHARSET directive are ignored. When the NAME operand is not specified, then this directive is used, which implies that any subsequent CHARSET directives in the file will never be processed since this one will always be used.
Example
Begin definition for IBM Code Page 833, the single-byte component for IBM CCSID 933. CHARSET NAME KOREAN_EBCDIC933 ENCODING IBMSOSI
END
The END directive ends processing of records in the file.
Syntax
END
JCM_D003
Usage Notes
Any remaining records in the file are not read.
Example
END
MONOCASE
The MONOCASE directive optionally defines characters that have both lower and upper case. If this information is not supplied, then no monocasing is performed.
D5
Syntax
MONOCASE MON
JCM_D004
Usage Notes
The actual monocase information is contained on statements that immediately follow the MONOCASE directive. Each such statement has the following syntax:
target_codepoint1<-target_codepoint2>: data_codepoint ... where:
Syntax Element Funciton
target_cod epoint1 target_codepoint2 data_codepoint
Specifies the first character defined on this statement. Optionally specifies the last character defined on this statement. Defines the upper case equivalent for the associated target_codepoint character.
A codepoint is the hexadecimal representation of a character. The number of characters needed to specify a codepoint is dependent on the encoding scheme for the character set. With the current TDP support, the length is always two except for UCS2 encoding, for which the length is 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.
All statements after the MONOCASE directive that contain a colon are associated with the MONOCASE directive. Lack of a colon indicates that the statement is a new directive and ends that MONOCASE directive. The only codepoints that need be specified are those for which upper case equivalents exist. The MONOCASE directive may be specified only once for each character set. The order of data codepoints among different statements is not significant. If the same character is defined more than once for a character set (either on a MONOCASE directive, or on a MONOCASE and a UNICODE directive), the last value is used. If no CHARSET directive precedes MONOCASE, then a character set description is implicitly begun -- in effect, a CHARSET directive with no operands is assumed.
D6
Example
Define the monocase information for IBM Code Page 833, the single-byte component for IBM CCSID 933. MONOCASE 81-89: C1 91-99: D1 A2-A9: E2
SANITIZE
The SANITIZE directive optionally defines valid characters for TDP messages sent using operating system facilities. Since all such facilities support only EBCDIC, the sanitizing process ensures that unsupported or non-EBCDIC characters are replaced by an acceptable character (the Hyphen character (hexadecimal 60) is the TDP convention). If this information is not supplied, then a default is chosen based on the encoding scheme.
Syntax
SANITIZE SAN
JCM_D005
Usage Notes
The actual sanitize information is contained on statements that immediately follow the SANITIZE directive. Each such statement has the following syntax:
target_codepoint1<-target_codepoint2>: data_codepoint ...
where:
target_codepoint1 target_codepoint2
specifies the first character defined on this statement optionally specifies the last character defined on this statement, and data_codepoint defines the replacement character for the associated target_codepoint character.
A codepoint is the hexadecimal representation of a character. The number of characters needed to specify a codepoint is dependent on the encoding scheme for the character set. For the characters of interest to TDP, the length is always two except for UCS2 encoding, for which the length is 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.
D7
All statements after the SANITIZE directive that contain a colon are associated with the SANITIZE directive. Lack of a colon indicates that the statement is a new directive and ends that SANITIZE directive. The SANITIZE directive may be specified only once for each character set. The order of data codepoints among different statements is not significant.", "If the same character is defined more than once for a character set, the last value is used. If no CHARSET directive precedes SANITIZE, then a character set description is implicitly begun -- in effect, a CHARSET directive with no operands is assumed.
Example
Provide the sanitize information for IBM Code Page 833, the single-byte component for IBM CCSID 933. The valid characters which do not correspond to standard EBCDIC are converted to Hyphens
SANITIZE 0E-0F: 4C 42-49: 60 52-59: 60 62-69: 60 72-78: 60 8A-8F: 60 9A-9F: 60 AA-AF: 60 B2: 60 BA-BC: 60 E0: 60 6E 60 60 60 60 60 60
60 60 60 60 60 60
60 60 60 60 60 60
60 60 60 60 60 60
60 60 60 60 60 60
60 60 60 60 60 60 60
60 60
UNICODE
The UNICODE directive defines the syntactic characters and characters that have both lower and upper case. It may be possible to use it to provide the same information as the CHAR and MONOCASE directives. Since UNICODE is required to add a userdefined character set to CLIv2, it is also supported by TDP to potentially simplify use of user-defined character sets. The relevant syntactic characters in the character set are those that have the Unicode codepoints of 0020 (Space), 0022 (Quotation Mark), 0027, (Apostrophe), and 002C (Comma). The monocase information in the character set are those that have the Unicode codepoints of 0061 through 007A (lower case) and 0041 through 005A (upper case). Codepoints beyond those relevant to CHAR and MONOCASE are ignored. If these are not the characteristics of the character set, then CHAR and MONOCASE must be used instead of UNICODE.
D8
Syntax
UNICODE UNI
JCM_D006
Usage Notes
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 ...
where:
target_codepoint1 target_codepoint2
specifies the first character in the user-defined character set that is defined on this statement. 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 TDP, the length is always two except for UCS2 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. 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 for the same purpose more than once for a character set (either on a CHAR directive, on a MONOCASE directive, or on a UNICODE directive), the last value is used. If no CHARSET directive precedes UNICODE, then a character set description is implicitly begun -- in effect, a CHARSET directive with no operands is assumed.
D9
Example
Define the Unicode equivalents for IBM Code Page 833, the single-byte component for IBM CCSID 933. UNICODE 40-47: 0020 48-4F: 11AD 50-57: 0026 58-5F: 11B4 60-67: 002D 68-6F: 110A 70-77: 005B 78-7F: 1112 80-87: 005D 88-8F: 0068 90-97: 001A 98-9F: 0071 A0-A7: 00AF A8-AF: 0079 B0-B7: 005E B8-BF: 001A C0-C7: 007B C8-CF: 0048 D0-D7: 007D D8-DF: 0051 E0-E7: 20A9 E8-EF: 0059 F0-F7: 0030 F8-FF: 0038 001A 1103 001A 11B5 002F 110B 001A 0060 0061 0069 006A 0072 007E 007A 001A 001A 0041 0049 004A 0052 001A 005A 0031 0039 115F 00A2 1104 0021 11B6 00A6 110C 003A 0062 1161 006B 1167 0073 116D 005C 1173 0042 001A 004B 001A 0053 001A 0032 001A 1100 002E 1105 0024 1106 002C 110D 0023 0063 1162 006C 1168 0074 116E 001A 1174 0043 001A 004C 001A 0054 001A 0033 001A 1101 003C 11B0 002A 1107 0025 110E 0040 0064 1163 006D 1169 0075 116F 001A 1175 0044 001A 004D 001A 0055 001A 0034 001A 1115 0028 11B1 0029 1108 005F 110F 0027 0065 1164 006E 116A 0076 1170 001A 001A 0045 001A 004E 001A 0056 001A 0035 001A 1102 002B 11B2 003B 1121 003E 1110 003D 0066 1165 006F 116B 0077 1171 001A 001A 0046 001A 004F 001A 0057 001A 0036 001A 11AC 007C 11B3 00AC 1109 003F 1111 0022 0067 1166 0070 116C 0078 1172 001A 001A 0047 001A 0050 001A 0058 001A 0037 001A
D 10
Index
Numerics 2PC affected TDP commands 120 disabling IRF 617 enabling internal sessions 670 in-doubt sessions committing 614 displaying 647 rollback 696 internal TDP sessions 55 manual in-doubt resolution 119, 617 protocol 119 HSIT routines 25 CLI routines 114 functions 22 how to use 22 HSHSPB requirement 23 HSISPB requirement 23 library 22 updating under MVS 22 updating under VM 22 updating under VOS3 22 Client software communication with Teradata server 13 definition 11 HSCI 11 installation 11 tuning options 36 COMMIT command, TDP 614 Common Storage Area. See CSA Communication character setting for TDP 6102 CP displaying status 639 relationship to IFP 116 shutdown record 313 CSA, global memory management 27
A ADD CELLS command, TDP 67 ADD XMSCELLS command, TDP 67 ADDRESS SPACE UNAVAILABLE MESSAGE IEF352I 517 ATTACH IFP command, TDP 69 Attributes display server attributes 655 Authority granting to issue TDP commands 611 levels of command issuing 518 TDP capabilities 518 where to issue 612 AUTHORIZ command, TDP 518, 611
D DBCAREA fields 31 DBCCMD invoking from a program 59 return codes 510 using 59 DDNAME D2 DETACH IFP command, TDP 616 Diagnostics writing to console, start 683 writing to console, stop 628 DISABLE IRF command, TDP 617 DISABLE LGUX command, TDP 618 DISABLE LOGONS command, TDP 619 DISABLE POOL command, TDP 620 DISABLE SECLOGON command, TDP 621 DISABLE SESSION RESERVE command, TDP 623 DISABLE SMF command, TDP 625 DISABLE TDPSTAT command, TDP 627
C Channel block display number of 634 Channel Processor, definition 116 Channel sharing 311 Character set display default 655 Character set, setting for TDP 699 Character sets list supported sets 655 checksum SET CHECKSUM command 6101 CLI communicating with TDP 21
Index 1
Index
DISABLE TDPSTATS 627 DISABLE TEST command, TDP 628 DISABLE TIME command, TDP 629 DISABLE TMON command, TDP 630 DISABLE TRAP command,TDP 631 DISABLE UAX command, TDP 632 DISABLE USEC command, TDP 633 DISPLAY CCU command,TDP 634 DISPLAY CELLS command, TDP 635 DISPLAY CHECKSUM command, TDP 638 DISPLAY CP command, TDP 639 relationship to DISPLAY IFP command 639 DISPLAY IFP command, TDP 645 DISPLAY INDOUBT command, TDP 647 DISPLAY JOB command, TDP 649 DISPLAY MODULE command, TDP 651 DISPLAY POOL command, TDP 652 DISPLAY QUEUES command, TDP 654 DISPLAY SERVER command 655 DISPLAY SESSIONS command, TDP 657 DISPLAY SMF command, TDP 661 DISPLAY SP command, TDP 662 DISPLAY STORAGE command, TDP 665 DISPLAY TDP command, TDP 666 DISPLAY TDPSTATS command, TDP 669
list server features 655
H Host System Interface to TDP. See HSIT Host System Interface Utility. See HSIU HSI System Parameter Block. See HSISPB HSI time stamps 31 HSIOSSI, associating with TDP 6136 HSISPB INITIAL commands 6124 overriding specifications 6124 tuning options 318 HSIT routines 25 HSIU routines 27 address space termination 28 end of memory cleanup 28 global memory management 27 inter address space services 27
I I/O choosing mode 6131 increasing buffers 6130 mode options 319 ID display logical host 655 IEF352I message ADDRESS SPACE UNAVAILABLE 517 IFP allocating to TDP 69 attaching to TDP 6111 deallocating from TDP 616 displaying status 645 relationship to CP 116 starting 698, 6111 stopping 6121 INITIAL commands, TDP affected by 2PC 120 INITIAL CCU 6126 INITIAL DLYTIME 6127 INITIAL IACMODE 6128 INITIAL IOBUFS 6130 INITIAL IOMODE 6131 INITIAL JOBWAIT 6133 INITIAL LSQA 6134 INITIAL MSGPREF 6135 INITIAL OSSISUFX 6136
E ENABLE IRF command, TDP 670 ENABLE LGUX command, TDP 671 ENABLE LOGONS command, TDP 672 ENABLE POOL command, TDP 673 ENABLE SECLOGON command, TDP 674 ENABLE SESSION RESERVE command, TDP 677 ENABLE SMF command, TDP 679 ENABLE TDPSTATS command, TDP 681 ENABLE TEST command, TDP 683 ENABLE TIME command, TDP 684 ENABLE TMON command, TDP 685 ENABLE TRAP command, TDP 686 ENABLE UAX command, TDP 688 ENABLE USEC command, TDP 689 External Security Manager Interface (security logon function) 414
F Features
Index 2
Index
INITIAL PCSUFX 6137 INITIAL TRUNCRSP 6138 list 6124 Initiate With Protocol-Function function using with VoteTerm parcel B38 IOSDRIVR, using 6132 IRF 56 enabling 670 internal TDP sessions 56
J Job changing wait time 6133 displaying status 649
L LOGOFF command, TDP 690 LOGOFF POOL command, TDP 692 Logoff record 314 Logon disabling 619 disabling to pools 620 enabling 672 enabling to pools 673 violations information 633 LSQA, controlling in address space 6134
M Memory adding cells to main 67 displaying cell information 635 Memory cell optimization 311 usage analysis example 310 Messages 113 MODIFY POOL command, TDP 694 MODIFY SECLOGON command, TDP 695
O Operator commands, TDP ADD CELLS 67 ADD XMSCELLS 67
affected by 2PC 120 ATTACH IFP 69 AUTHORIZ 611 COMMIT 614 DETACH IFP 616 DISABLE IRF 617 DISABLE LGUX 618 DISABLE LOGONS 619 DISABLE POOL 620 DISABLE SECLOGON 621 DISABLE SESSION RESERVE 623 DISABLE SMF 625 DISABLE TDTSTAT 627 DISABLE TEST 628 DISABLE TIME 629 DISABLE TMON 630 DISABLE TRAP 631 DISABLE UAX 632 DISABLE USEC 633 DISPLAY CCU 634 DISPLAY CELLS 635 DISPLAY CP 639 DISPLAY IFP 645 DISPLAY INDOUBT 647 DISPLAY JOB 649 DISPLAY MODULE 651 DISPLAY POOL 652 DISPLAY QUEUES 654 DISPLAY SERVER 655 DISPLAY SESSIONS 657 DISPLAY SMF 661 DISPLAY SP 662 DISPLAY STORAGE 665 DISPLAY TDP 666 DISPLAY TDPSTATS 669 ENABLE IRF 670 ENABLE LGUX 671 ENABLE LOGONS 672 ENABLE POOL 673 ENABLE SECLOGON 674 ENABLE SESSION RESERVE 677 ENABLE SMF 679 ENABLE TDPSTATS 681 ENABLE TEST 683 ENABLE TIME 684 ENABLE TMON 685 ENABLE TRAP 686 ENABLE UAX 688 ENABLE USEC 689 granting authority to issue 611 issuing from CLIv2 applications 514 issuing from MVS 58 issuing from VM 511
Index 3
Index
issuing from VOS3 58 LOGOFF 690 LOGOFF POOL 692 MODIFY POOL 694 MODIFY SECLOGON 695 ROLLBACK 696 RUN 698 SET CHARSET 699 SET COMCHAR 6102 SET MAXSESS 6103 SET STORAGE 6104 SET USERID 6107 SHUTDOWN 6109 START IFP 6111 START POOL 6113 STOP IFP 6121 STOP POOL 6123 where to issue 57, 62
definition 110 disabling logons 620 displaying information 652 enabling 6113 enabling logons 673 ending 692 logging off 112 logging on 110 multiple simultaneous 110 sessions, changing number 694 stopping 6123 Program call cells adding 67 displaying usage 635
Q Queue, displaying status of internal 654, 655
P Parallelism factor display 655 Parcel body B5 Request B6 Resp B21, B28 Response B9 RunStartup B31 type B6 Parcels 113 Performance CP shutdown record 313 general tuning options 36 logoff record 314 measurement MVS 312 SMF records 312 SMS records 312 VM 320 VOS3 312 statistics 37 system options 311 TDP cell optimization 37 TDP cells 36 tuning in VM 320 tuning MVS with I/O options 319 Performance Monitor partition sending requests to B30 Pools R Request parcel, overview B7 Requests 113 backing out 113 Resolver Base Module partition sending requests to B30 Resp parcel B21, B28 Response parcel, overview B9 ROLLBACK command, TDP 696 RUN command, TDP 698
S Security monitoring violations 633 security logon function 414 TDPLGUX 44 VM features 43 Security logon function 414 bypassing 416 disabling 416, 621 enabling 416, 674 modifying 695 operation 414 setup procedure 417 using with session pools 416 using with TDPLGUX 415
Index 4
Index
validated logon function 416 Security Manager Interface (security logon function) 414 Security violations record 315 Segment maximum number 655 maximum size 655 Semantics display 655 Server display attributes 655 Session pools changing number in 694 definition 110 displaying information 652 enabling 6113 logging off 112 logging on 110 logoff 692 multiple simultaneous 110 stopping 6123 Session Processor, definition 116 Sessions definition 19 disabling internal for 2PC 617 displaying status 657 enabling internal 670 forcing off 690 identification 19 in-doubt committing 614 displaying 647 rollback 696 logging on and off 19 logoff record 314 priority levels 117 protocol 118 request types 113 reserve capacity for failure 677 reserved capacity, releasing 623 setting maximum number 6103 SET CHARSET command, TDP 699 SET CHECKSUM command, TDP 6101 SET COMCHAR command, TDP 6102 SET MAXSESS command, TDP 6103 SET STORAGE command, TDP 6104 SET USERID command, TDP 6107 SHUTDOWN command, TDP 6109 SMF recording disabling 625 displaying status 661 enabling 679
SMF shutdown record 37 SMS recording disabling 625 displaying status 661 enabling 679 SMS shutdown record 37 SP, displaying status 662 START IFP command, TDP 6111 START POOL command, TDP 6113 Statistics CP shutdown record 313 logoff record 314 security violations record 315 TDP shutdown record 316 STOP IFP command, TDP 6121 STOP POOL command, TDP 6123 Structure-protocol Termination Record 317 System Parameter Block. See HSISPB
T TDP authorization capabilities 518 channel error logging 329, A2 character set, setting 699 command response types 515 command responses, location on VM 512 communication character, setting 512, 6102 communication mode, changing 6128 communication techniques 210 MVS 210 Program Call 211 SVC 210 VM 211 VOS3 210 communication with BTEQ 24 CPs assigned to 639 definition 115 HSIOSSI association 6136 IFP allocating 69 attaching 6111 deallocating 616 displaying status 645 initializing 54 initializing from TDPPARM 54 internal queues, displaying 654, 655 logon disabling 619 enabling 672 memory management 36 memory statistics, displaying 36
Index 5
Index
message handling 115 message prefix, suppressing 6135 MVS canceling 517 communication techniques 210 security features 41 starting under 52 tuning with HSISPB 318 tuning with I/O mode options 319 operation 51 performance cell usage optimization 311 CP shutdown record 313 logoff record 314 SMF records 312 SMS records 312 statistics 37 system options 311 tuning options 36 session capacity release reserved 623 reserve for failure 677 sessions, setting maximum number 6103 shutdown 517 shutdown record 316 SMF 37 SMS 37 SP status, displaying 662 status, displaying 666 stopping 6109 TDPLGUX disabling 618 enabling 671 TDPNSPCI association 6137 TDPUAX enabling requests to 688 stopping requests to 632 TDPUSEC enabling communication to 689 stopping communication with 633 TDPUTCE disabling calls to 630 enabling calls to 685 throughput, improving 67 user validation 518 userid setting for internal sessions 6107 VM location of command responses 512 performance LOCK PAGE command 325 measurement 320 other tuning options 327 SET FAVOR command 324 SET QDROP OFF command 322 SET QDROP OFF USERS command 323
SET RESEVE TDP command 326 tuning 320 tuning with operator commands 321 security features 43 starting under 53 VOS3 canceling 517 communication techniques 210 security features 41 starting under 52 tuning with HSISPB 318 TDP Operator Message Character Set 516 TDP User Address Space Exit. See TDPUAX TDP User Logon Exit Interface. See TDPLGUX TDP User Security Interface. See TDPUSEC TDP User Transaction Collection Exit. See TDPUTCE TDPINT 617 TDPLGUX customizing 45 disabling 618 enabling 671 installing customized 46 logon violations record 315 operation 44 security functions 44 security violations record 315 using with security logon 415 TDPNSPCI, TDP association 6137 TDPPARM creating your own 55 message routing 55 using to initialize TDP 54 TDPUAX customizing 412 disabling 632 enabling 688 installing customized 413 operation 411 security functions 411 TDPUSEC customizing 48 disabling 633 enabling 689 installing customized 410 operation 48 security functions 48 TDPUTCE collection applications 34 customizing 34 definition 33 disabling 630 enabling 33, 685 MVS, installing customized 35
Index 6
Index
types of calls processed 33 VM, installing customized 35 VOS3, installing customized 35 Teradata server 11 Channel Processor 116 CLI 114 client attachment 12 communicating with 13 pools, logging on 110 resource allocation 117 Session Processor 116 session protocol 118 TEST mode disabling 628 displaying information 658 enabling 628, 683 Time disabling 629 enabling 684 Tuning options HSISPB parameters 318 system 311 TDP 36 VM operator commands 321
U Userid setting for internal TDP sessions 6107 UTC routines 24
V Validated logon function using security logon with 416
Index 7
Index
Index 8

2416

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

2416

Enviado por

Direitos autorais:

Formatos disponíveis

Teradata Director Program

B035-2416-122A December 2002

Changes to This Book

Teradata Director Program Reference

Product Related Publications

Teradata Tools and Utilities Release Definition

Teradata Director Program Reference

Technical Information on the Web

Teradata Director Program Reference

QCF RAS RDBMS SQL SSO TLE TSET WinCLI

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Teradata Director Program Reference

Client Software Overview

The user-to-TDP communication modes are described in Chapter 2.

Installing Client Software

Teradata Director Program Reference

Chapter 1: Client Software Overview

Teradata Server LAN-Attached Clients Mainframe Channel

VM Client: - VM Operating System - CLIv1, CLIv2 - TDP - UTC (IUCV)

Teradata Director Program Reference

Chapter 1: Client Software Overview Communicating with the Teradata Server

Communicating with the Teradata Server

Teradata Director Program Reference

Input Buffer Channel Block

Teradata Director Program Reference

User Address Space Output Buffer

TDP Address Space Request Parcels Other Request Other Request

Input Buffer Channel Block

Figure 1-4 Communicating With TDP Using IUCV

User Virtual Machine Output Buffer

TDP Virtual Machine Request Parcels Other Request Other Request

Input Buffer Channel Block

Teradata Director Program Reference

Chapter 1: Client Software Overview How TDP Returns Results

How TDP Returns Results

Teradata Director Program Reference

User Address Space Output Buffer

TDP Address Space Input Buffer Request Parcel

Figure 1-6 Returning a Response Using PC

User Address Space Output Buffer

TDP Address Space Input Buffer Request Parcel

Teradata Director Program Reference

User Virtual Machine Output Buffer

TDP Virtual Machine Input Buffer Request Parcel

Teradata Director Program Reference

Chapter 1: Client Software Overview Sessions

Sessions Are Logged On and Off

Teradata Director Program Reference

Chapter 1: Client Software Overview Session Pools

Logging Pool Sessions on to the Teradata Server

Multiple Simultaneous Session Pools