Professional Documents
Culture Documents
2416
2416
2416
Reference
Release 06.09.00
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
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
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.
ii
Preface
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
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:
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
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
LAN
MVS Client: - MVS Operating System - CLIv1, CLIv2 - TDP - UTC (SVC or PC)
FZAPB075
12
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
CLI
Routines
Teradata Server
FZAPB076
14
Chapter 1: Client Software Overview Communicating with the Teradata Server Figure 1-3 Communicating With TDP Using PC
Application
CLI
Routines
Teradata Server
FZAPB077
Application
CLI
Routines
Teradata Server
FZAPB078
15
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
CLI
Routines
FZAPB079
Application
CLI
Routines
FZAPB080
17
Chapter 1: Client Software Overview How TDP Returns Results Figure 1-7 Returning a Response Using IUCV
Application
CLI
Routines
FZAPB081
18
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.
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
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.
1 10
The logon string of the application is checked to determine whether it matches that of any established pool.
IF TDP . . . THEN it . . .
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
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
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.
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
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
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.
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
If the information ends with the four characters ' LSS' (note the blank), then the format identifier and Jobid values are present.
1 15
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.
1 16
A session is assigned the priority level of the user who is logging on.
1 17
Session Protocol
Introduction
Session protocol controls the rate at which data is transferred between an interactive user or application program and the Teradata server.
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
1 19
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.
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
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
22
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.
23
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
24
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
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
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
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
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
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.
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.
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
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.
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.
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.
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
SL
Rz,Ry
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
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.
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.
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
1 2
Invoke TDPUTCE EXEC to assemble the modified TDPUTCE ASSEMBLE. Replace the TDPUTCE entry in TDP LOADLIB.
35
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
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.
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.
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 . . .
0 anything else
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
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
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.
38
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
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.
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 . . .
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
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.
All the SMF/SMS record subtypes are described in further detail in the following sections.
3 12
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
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
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
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
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.
3 18
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
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
3 21
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
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
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.
3 24
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
3 26
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
performance suffer. Placing these devices on dedicated channels eliminates this problem.
3 28
Chapter 3: Performance Measurement Channel Processor Device and Channel Error Logging
3 29
Chapter 3: Performance Measurement Channel Processor Device and Channel Error Logging
3 30
Chapter 4:
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
42
Chapter 4: Security Features Under MVS and VOS3 Security Features Under VM
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
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
Chapter 4: Security Features Under MVS and VOS3 User Logon Exit Interface
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
Chapter 4: Security Features Under MVS and VOS3 User Logon Exit Interface
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.
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
Chapter 4: Security Features Under MVS and VOS3 User Logon Exit Interface
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
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.
48
Chapter 4: Security Features Under MVS and VOS3 User Security Interface
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
Chapter 4: Security Features Under MVS and VOS3 User Security Interface
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
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
Chapter 4: Security Features Under MVS and VOS3 User Address Space Exit
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
Chapter 4: Security Features Under MVS and VOS3 User Address Space Exit
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.
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
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 . . .
4 14
Chapter 4: Security Features Under MVS and VOS3 External Security Manager Interface
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)
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
4 15
Chapter 4: Security Features Under MVS and VOS3 External Security Manager Interface
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
4 16
Chapter 4: Security Features Under MVS and VOS3 External Security Manager Interface
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.
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
Chapter 4: Security Features Under MVS and VOS3 External Security Manager Interface
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) -
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
Chapter 4: Security Features Under MVS and VOS3 External Security Manager Interface
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
Chapter 4: Security Features Under MVS and VOS3 External Security Manager Interface
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
51
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
(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
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.
54
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.
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
57
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
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.
58
where:
Syntax element . . . Is the . . .
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.
where:
Syntax element . . . Is the . . .
tdpid TDPcommand_text
pointer to parmlist. pointer to a 72-byte save area (will be used). return address to calling program. entry address of DBCCMD.
59
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.
5 10
where:
Syntax element . . . Is the . . .
tdpid TDPcommand_text
identifier associated with the TDP (for example, TDP0, TDP1, and so on) to which the command is directed. syntax of the TDP command.
where:
Syntax element . . . Is the . . .
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.
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.
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
5 14
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
5 16
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.
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
AUTHORIZ Command
With the AUTHORIZ command you can grant: Authority to one, many, or all users Any or all of the five authority levels
User Validation
To validate users, TDP performs the following steps:
Step Action
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
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 . . .
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
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
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
63
Chapter 6: TDP Commands TDP Operator Commands Table 6-1 (Continued) TDP Operator Commands
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.
64
Chapter 6: TDP Commands TDP Operator Commands Table 6-1 (Continued) TDP Operator Commands
Command Function
ENABLE SMF
Causes SMF information to be recorded. In the VOS3 environment, applies to SMS records.
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.
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
65
Chapter 6: TDP Commands TDP Operator Commands Table 6-1 (Continued) TDP Operator Commands
Command Function
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
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:
Syntax element . . . Is the . . .
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
Example
ADD CELLS SIZ 80 NUM 16
Completion Message
TDP0527 16 MEMORY CELLS OF SIZE 80 SUCCESSFULLY ADDED
68
ATTACH IFP
Function
Allocates an IFP to a TDP.
Syntax
ATTACH ATT ifpname
FZAPB002
where:
Syntax element . . . Is the . . .
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
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
AUTHORIZ
Function
Grants authority to users at any or all of the five authority levels.
Syntax
AUTHORIZ AU
where:
Syntax element . . . Is the . . .
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.
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
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
Example 1
AU ALL DISPLAY
6 12
COMMENT
Function
Adds comments to the JOBLOG and GTF, if being used.
Syntax
text
FZAPZ001
where:
Syntax element . . . Is the . . .
text
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
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:
Syntax element . . . Is the . . .
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
Example 2
COMMIT SESSION 4321 COORD CICSS2
Completion Message
TDP0402 SESSION 4321 COMMITTED
6 15
DETACH IFP
Function
Deallocates an IFP from a TDP.
Syntax
DETACH DET ifpname
FZAPB004
where:
Syntax element . . . Is the . . .
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
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
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
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
DISABLE POOL
Function
Prevents logons to one or more pools.
Syntax
DISABLE DISA POOL ID poolid ALL
FZAPB008
where:
Syntax element . . . Is the . . .
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
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
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
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
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
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
Example 2
DISA SMF SUB1
Completion Message
TDP0594 SMF RECORDING DISABLED
6 26
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
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
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
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
DISABLE TRAP
Function
Disables a previously-enabled diagnostic trap.
Syntax
DISABLE TRAP NAME name
FE0CA050
where:
Syntax element . . . Is the . . .
name
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
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
Example
DISA UAX
Completion Message
TDP0597 TDP USER ADDRESS SPACE EXIT INTERFACE NOW DISABLED
6 32
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
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
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:
Syntax element . . . Is the . . .
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 . . .
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
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
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
6 37
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
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
where:
Syntax element . . . Is the . . .
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
Communication with the server is not established. Communication with the server has been established.
6 40
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 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
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
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 . . .
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
DISPLAY IFP
Function
Displays the status of IFPs that are allocated to TDP.
Syntax
DISPLAY D IFP ifpname
STATE
FZAPB017
where:
Syntax element . . . Is the . . .
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
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
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:
Syntax element . . . Is the . . .
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
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:
Syntax element . . . Is the . . .
####### rrrrrrr
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:
Syntax element . . . Is the . . .
6 48
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:
Syntax element . . . Is the . . .
jobname
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
6 49
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
DISPLAY MODULE
Function
Displays information about a TDP module.
Syntax
DISPLAY D MODULE name LOCATION
FZAPB092
where:
Syntax element . . . Is the . . .
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
DISPLAY POOL
Function
Lists information and statistics about one or more established session pools.
Syntax
DISPLAY D POOL ALL ID poolid
FZAPB020
where:
Syntax element . . . Is the . . .
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
where:
Column heading . . . Contains the . . .
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
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
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
DISPLAY SERVER
Function
Displays attributes of the server with which TDP is communicating.
Syntax
DISPLAY SERVER FEATURES CHARSETS
KY01A123
where:
Syntax element . . . Is the . . .
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
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
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:
Syntax element . . . Is the . . .
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
IDLE 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
6 58
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
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
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:
Syntax element . . . Is the . . .
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
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
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 . . .
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
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
SWITCH ACTIVE
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
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
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.
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
6 66
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
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
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
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
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:
Usually, one message is displayed for the RBM session and another is displayed for the LOG session.
6 70
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
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
ENABLE POOL
Function
Enables logons to one or more pools.
Syntax
ENABLE ENA POOL ALL ID poolid
FZAPB028
where:
Syntax element . . . Is the . . .
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
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 . . .
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
Completion Message
TDP2108 SECLOGON: ENABLED, DIAGNOSTIC MSGS: DISABLED CLASS: FACILITY
6 75
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
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
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
ENABLE SESSION STATUS
Completion Message
TDP0401 SESSION STATUS HAS BEEN ENABLED
6 78
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
Completion Message
TDP0594 SMF RECORDING ENABLED
6 80
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
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
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
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
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
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. . .
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
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.
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
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
Example
ENA UAX
Completion Message
TDP0597 TDP USER ADDRESS SPACE EXIT INTERFACE ENABLED
6 88
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
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:
Syntax element . . . Is the . . .
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.
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
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.
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
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:
Syntax element . . . Is the . . .
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
Completion Messages
When LOGOFF POOL . . . This message is displayed . . .
TDP0877 LOGOFF POOL INITIATED FOR POOL ID: poolid TDP0878 POOL ID: poolid STOPPING
6 93
MODIFY POOL
Function
Increases or decreases the number of sessions in a pool.
Syntax
MODIFY POOL ID poolid NUM number
FZAPB038
where:
Syntax element . . . Is the . . .
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
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
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:
Syntax element . . . Is the . . .
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
Completion Message
TDP0403 SESSION 3253 ROLLED BACK
6 97
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
SET CHARSET
Function
Establishes the character set with which userids and logon strings are specified in TDP commands.
Syntax
where:
Syntax element . . . Is the . . .
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
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
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
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:
Syntax element . . . Is the . . .
comchar
OFF
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
SET MAXSESS
Function
Establishes the maximum number of concurrent sessions that TDP will allow.
Syntax
SET MAXSESS MAXS number_of_sessions
FZAPB044
where:
Syntax element . . . Is the . . .
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
SET STORAGE
Function
Changes the virtual storage limits used by TDP.
Syntax
SET STORAGE CP nnnn
FE0CA048
where:
Syntax element . . . Is the . . .
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
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
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
Example
SET USERCS KOREAN_EBCDIC933 DDNAME TDPCS
Completion
TDP2832 KOREAN_EBCDIC933 HAS BEEN DEFINED
6 106
SET USERID
Function
Changes the Database userid that TDP uses to establish its internal sessions.
Syntax
SET USERID name
FZAPB042
where:
Syntax element . . . Is the . . .
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
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
SHUTDOWN
Function
Stops TDP operation.
Syntax
SHUTDOWN ORDERLY O CANCEL QUICK
FZAPB045
where:
Syntax element . . . Is the specification to . . .
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 . . .
Orderly Quick
To obtain a dump in . . .
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
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
START IFP
Function
Causes TDP to begin communicating with an IFP.
Syntax
START STA ifpname CIC CCU
FZAPB091
where:
Syntax element . . . Is the . . .
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
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
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
B runstring ID poolid
C character_set_name D session_attributes
where:
Syntax element . . . Is the . . .
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.
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
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
Note that these session pools are established only after IFP6B0 and IFP6B2 are started.
6 120
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:
Syntax element . . . Is the . . .
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
Completion Messages
TDP1363 STOP IFP COMMAND ACCEPTED
6 122
STOP POOL
Function
Ends one or more session pools in an orderly manner.
Syntax
STOP STO POOL ID poolid ALL
FZAPB049
where:
Syntax element . . . Is the . . .
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
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
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
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
INITIAL CCU
Function
Changes limits used during operation of CCU-type CPs.
Syntax
INITIAL CCU MAXBLKNM n MAXBLKSZ n MAXCKSUM n
FE0CQ049
where:
Syntax element . . . Is the . . .
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
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:
Syntax element . . . Is the . . .
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
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:
Syntax element . . . Is the . . .
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
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
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:
Syntax element . . . Is the . . .
number
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
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
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
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:
Syntax element . . . Is the . . .
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
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
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
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 . . .
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
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
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:
Syntax element . . . Is the . . .
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
INITIAL TRUNCRSP
Function
Specifies if response truncation is to be indicated by a return code.
Syntax
INITIAL TRUNCRSP RC NORC
FE0CA051
where:
Syntax element . . . Is the . . .
RC
NORC
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:
A1
Appendix A: Channel Processor Device and Channel Error Log Sample EREP Record
IDENTITY- TDP3 01 33 D0 E0 60 00 00 14
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
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:
Byte # (Dec) Content Description
64 67
A3
Appendix A: Channel Processor Device and Channel Error Log Record Format
Byte # (Dec) Content Description
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
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:
Byte # (Dec) Content Description
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
Appendix A: Channel Processor Device and Channel Error Log Record Format
Byte # (Dec) Content Description
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
Appendix A: Channel Processor Device and Channel Error Log Sense Data
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
Appendix A: Channel Processor Device and Channel Error Log Sense Data
A8
Appendix B:
Parcel Flavors
This appendix contains details about parcel flavors.
B1
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. . .
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
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
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
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
B6
1* 2 3* 4 5 6 7
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
13 * 14 31 36 37 38
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
B7
Appendix B: Parcel Flavors Request Parcels: Overview Table B-2 (Continued) Request Parcels Flavor Definitions
Flavor Parcel Name Use
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
B8
8 9 10
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
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
Flavor Parcel Name Use
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
B 10
Appendix B: Parcel Flavors Response Parcels: Overview Table B-3 (Continued) Response Parcels Flavor Definitions
Flavor Parcel Name Use
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.
B 11
Parcel Descriptions
The following alphabetized sections describe parcels generated by user applications and the Teradata server.
B 12
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
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 . . .
Field Data
The following table lists field information for Abrt2PC Parcel.
Flavor Parcel Body Length Parcel Body Fields
118
none
B 14
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.
Flavor Parcel Body Length Parcel Body Fields
none
B 15
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
Field Data
The following table lists field information for Cmmt2PC.
Flavor Parcel Body Length Parcel Body Fields
117
none
B 16
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.
Flavor Parcel Body Length Parcel Body Fields
14
none
B 17
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.
Flavor Parcel Body Length Parcel Body Fields
72
none
B 18
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
Parcel Data
The following information applies to the KeepRespond parcel.
Flavor Parcel Body Length Parcel Body Fields
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
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.
Flavor Parcel Body Length Parcel Body Fields
154
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 4294967295.
B 20
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
153
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 4294967295.
B 21
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.
Flavor Parcel Body Length Parcel Body Fields
37
none
B 22
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.
Flavor Parcel Body Length Parcel Body Fields
36
278
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
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
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
Flavor Parcel Body Length Parcel Body Fields
128
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
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.
Flavor Parcel Body Length Parcel Body Fields
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
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
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.
Flavor Parcel Body Length Parcel Body Fields
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 28
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
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the Rewind parcel.
Flavor Parcel Body Length Parcel Body Fields
31
none
B 29
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.
Flavor Parcel Body Length Parcel Body Fields
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
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
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.
Flavor Parcel Body Length Parcel Body Fields
none
B 31
SessionOptions
Purpose
Sets various options for a session.
Parcel Data
The following information applies to the SessionOptions parcel.
Flavor Parcel Body Length Parcel Body Fields
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
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
Conformance specifies whether or not SQL requests are to be checked for conformance with a particular language definition.
B 32
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
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.
Flavor Parcel Body Length Parcel Body Fields
136
None
B 34
UserNameResponse
Purpose
Returns the userid assigned to the session.
Usage Notes
This parcel may appear anywhere before the only End-request parcel.
Flavor Parcel Body Length Parcel Body Fields
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
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.
Flavor Parcel Body Length Parcel Body Fields
115
64
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
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
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
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
B 40
Appendix C:
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
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
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:
D1
D2
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.
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
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:
Syntax Element Funciton
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:
Syntax Element Funciton
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
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
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
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
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
Index 7
Index
Index 8