IBM CICS Interface for Teradata. Reference

Transcription

1 IBM CICS Interface for Teradata Reference Release B K March 2015

2 The product or products described in this book are licensed products of Teradata Corporation or its affiliates. Teradata, Active Data Warehousing, Active Enterprise Intelligence, Applications-Within, Aprimo Marketing Studio, Aster, BYNET, Claraview, DecisionCast, Gridscale, MyCommerce, QueryGrid, SQL-MapReduce, Teradata Decision Experts, "Teradata Labs" logo, Teradata ServiceConnect, Teradata Source Experts, WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries. Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. Apache, Apache Hadoop, Hadoop, and the yellow elephant logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. Apple, Mac, and OS X all are registered trademarks of Apple Inc. Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda Access, Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and Maximum Support are servicemarks of Axeda Corporation. Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. GoldenGate is a trademark of Oracle. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. Hortonworks, the Hortonworks logo and other Hortonworks trademarks are trademarks of Hortonworks Inc. in the United States and other countries. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. IBM, CICS, RACF, Tivoli, and z/os are registered trademarks of International Business Machines Corporation. Linux is a registered trademark of Linus Torvalds. LSI is a registered trademark of LSI Corporation. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries. NetVault is a trademark or registered trademark of Dell Inc. in the United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates. QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation. Quantum and the Quantum logo are trademarks of Quantum Corporation, registered in the U.S.A. and other countries. Red Hat is a trademark of Red Hat, Inc., registered in the U.S. and other countries. Used under license. SAP is the trademark or registered trademark of SAP AG in Germany and in several other countries. SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. SPARC is a registered trademark of SPARC International, Inc. Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries. Unicode is a registered trademark of Unicode, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and company names mentioned herein may be the trademarks of their respective owners. THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN "AS-IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please teradata-books@lists.teradata.com. Any comments or materials (collectively referred to as "Feedback") sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback. Copyright by Teradata. All Rights Reserved.

3 Preface Purpose This book provides information about CICS Interface for application programs using IBM s Customer Information Control System/Virtual Storage (CICS/VS), which is a Teradata Tools and Utilities product. Teradata Tools and Utilities is a group of products designed to work with Teradata Database. Audience This book is intended for use by CICS application programmers: Supported Releases This book supports the following releases: Teradata Database Teradata Tools and Utilities CICS Interface to the Teradata Database To locate detailed supported-release information: 1 Go to 2 Under Online Publications, click General Search. 3 Type 3119 in the Publication Product ID box. 4 Under Sort By, select Date. 5 Click Search. 6 Open the version of the Teradata Tools and Utilities ##.# Supported Platforms and Product Versions spreadsheet associated with this release. The spreadsheet includes supported Teradata Database versions, platforms, and product release numbers. Prerequisites The following prerequisite knowledge is required for this product: IBM CICS Interface for Teradata Reference, Release

4 Preface Changes to This Book Teradata Database for UNIX Call-Level Interface Version2 Preprocessor2 Changes to This Book The following changes were made to this book in support of the current release. Changes are marked with change bars. For a complete list of changes to the product, see the Teradata Tools and Utilities Release Definition (B ) associated with this release. Date and Release March Description Updated version number and release date. There are no documentation changes resulting from this release. Related Documentation Additional information that supports this product and Teradata Tools and Utilities is available at the web sites listed in the table that follows. Type of Information Description Access to Information Release overview Late information Use the Release Definition for the following information: Overview of all of the products in the release Information received too late to be included in the manuals Operating systems and Teradata Database versions that are certified to work with each product Version numbers of each product and the documentation for each product Information about available training and the support center 1 Go to 2 Under Downloadable Publications, click General Search 3 Type 2029 in the Publication Product ID box. 4 Click Search. 5 Select the appropriate Release Definition from the search results. 4 IBM CICS Interface for Teradata Reference, Release 15.10

5 Preface Related Documentation Type of Information Description Access to Information Additional product information CD-ROM images General information about Teradata Use the Teradata Information Products web site to view or download specific manuals that supply related or additional information to this manual. Access a link to a downloadable CD-ROM image of all customer documentation for this release. Customers are authorized to create CD-ROMs for their use from this image. The Teradata home page provides links to numerous sources of information about Teradata. Links include: Executive reports, case studies of customer experiences with Teradata, and thought leadership Technical information, solutions, and expert advice Press releases, mentions, and media resources 1 Go to 2 Under the Downloadable Publications subcategory, Browse by Category, click Data Warehousing. 3 Do one of the following: For a list of Teradata Tools and Utilities documents, click Teradata Tools and Utilities, and then select an item under Releases or Products. Select a link to any of the data warehousing publications categories listed. Other books related to IBM CICS Interface for Teradata are: Teradata Director Program Reference B Teradata Call-Level Interface Version 2 Reference for Mainframe-Attached Systems B Teradata Tools and Utilities for IBM z/os Installation Guide B Utilities B Go to 2 Under the Downloadable Publications subcategory, Browse by Category, click Data Warehousing. 3 Click Documentation CD Images Teradata Database and Teradata Tools & Utilities. 1 Go to Teradata.com. 2 Select a link. IBM CICS Interface for Teradata Reference, Release

6 Preface Product Safety Information Product Safety Information This document may contain information addressing product safety practices related to data or property damage, identified by the word Notice. A notice indicates a situation which, if not avoided, could result in damage to property, such as equipment or data, but not related to personal injury. Example: Notice: Improper use of the Reconfiguration utility can result in data loss. 6 IBM CICS Interface for Teradata Reference, Release 15.10

7 Table of Contents Preface Purpose Audience Supported Releases Prerequisites Changes to This Book Related Documentation Product Safety Information Chapter 1: Overview of the CICS Interface Assumptions For the System Programmer For the Application Programmer Installation Glossary of Terms CICS Interface Application Development in the Teradata Environment Components of the CICS Interface The Long-Running Transaction DBCCICS The CLI Stub CLI Support Routines Task End/Exit Routine CICS Command Transactions for the Teradata Database Chapter 2: CICS Interface Operation Starting the Interface Messages Displayed IBM CICS Interface for Teradata Reference, Release

8 Table of Contents Verifying an Active Interface Startup Processing Initialization Process Shutting Down the Interface Syntax Orderly Shutdown Immediate Shutdown Shutdown Display and Recovery Restarting the Interface Messages Displayed Verifying an Active Interface Error Processing and Recovery Control Block Display Displaying Session Information Example Display Displaying Module History/Version Example Session Control Logging a Session Off Disabling Logons Enabling Logons Controlling TDP Connections for 2PC Commit Mode Monitoring Memory Controlling Memory SIZE and MAX OVRC and OVRK DMEM Command: Some Usage Notes CICS Memory Management Maintaining Session Context Controlling Memory Usage Minimizing Memory Overhead The HSHSPBC Area Allocating Buffers Releasing Buffers DAFC Command Syntax START Option STOP Option STOP QUIESCE STOP FORCE STATUS Option IBM CICS Interface for Teradata Reference, Release 15.10

9 Table of Contents Chapter 3: Teradata Database Application Development Passing Control between Programs Conversational Pseudo-Conversational Passing Information between Compile Units Rules for CLIv Rules for Preprocessor Rules for CLIv Rules for Preprocessor Distinction between Compile Units and Programs Example The Effect of Locks on Requests Locks and Non-2PC Applications Locks and 2PC Applications Using Preprocessors Accessing the CICS Interface Using the COBOL Preprocessor Using the COBOL Preprocessor STOP RUN Using the PL/I Preprocessor Using Teradata Sessions Session Pooling Synchronizing Resources Synchronizing Resources for Non-2PC Applications Teradata Database Synchronization Strategy Synchronizing Resources for 2PC Applications CICS and 2PC A CICS Transaction with the 2PC Protocol In-Doubt Resolution Automatic In-Doubt Resolution Manual In-Doubt Resolution Multiple Sessions and 2PC Using TDP Session Pools with 2PC Session Pool Logoff Processing CICS/ESA Support Migrating Existing Teradata Database Applications Attachment Facility How the Attachment Facility Allocates Storage above 16 Megabytes Debugging and Testing IBM CICS Interface for Teradata Reference, Release

10 Table of Contents INTERTEST Appendix A: Sample CICS COBOL Program Sample Program Code Program Setup Program Execution Executing the Sample Program COBOL JCL Appendix B: Sample CICS PL/I Program Program Code Program Setup Program Execution Executing the Sample Program PL/I JCL Appendix C: Sample CICS Programs for 2PC PC PL/I Sample Using Preprocessor PC COBOL Sample Using Preprocessor PC COBOL Sample Using CLIv Appendix D: Additions to the CICS Startup JCL Appendix E: How to Read the Syntax Diagrams Syntax Diagram Conventions IBM CICS Interface for Teradata Reference, Release 15.10

11 Table of Contents Index IBM CICS Interface for Teradata Reference, Release

12 Table of Contents 12 IBM CICS Interface for Teradata Reference, Release 15.10

13 List of Figures Figure 1: 2PC CICS Processing Example IBM CICS Interface for Teradata Reference, Release

14 List of Figures 14 IBM CICS Interface for Teradata Reference, Release 15.10

15 List of Tables Table 1: Glossary of Terms Table 2: Command Transactions Table 3: Parameters Supplied to the HSHSPBC Macro Table 4: Definitions of Parameters Supplied to the HSHSPBC Macro Table 5: Migration Consideration Table 6: INTERTEST Name Values IBM CICS Interface for Teradata Reference, Release

16 List of Tables 16 IBM CICS Interface for Teradata Reference, Release 15.10

17 CHAPTER 1 Overview of the CICS Interface This chapter describes the conceptual structure of the CICS (Customer Information Control System) Interface for applications using IBM s CICS to access a Teradata Database. Assumptions For the System Programmer This reference assumes you have a working knowledge of the Customer Information Control System (CICS/OS/VS, CICS/MVS, CICS/ESA, or CICS Transaction Server), abbreviated in this reference as CICS. For the Application Programmer For application programmers, this reference assumes you have a working knowledge of CICS, as well as: Teradata Call-Level Interface Version1 or Version2, or Teradata Preprocessor1 or Preprocessor2. Installation This reference assumes that CICS has been installed on a channel-attached mainframe running MVS (Multiple Virtual Storage) operating system. Interface installation is not discussed in this reference. For information on the installation of the CICS Interface, see Teradata Tools and Utilities for IBM z/os Installation Guide (B ). IBM CICS Interface for Teradata Reference, Release

18 Chapter 1: Overview of the CICS Interface Glossary of Terms Glossary of Terms The CICS terms in Table 1 describe the structure and operation of the CICS Interface: Table 1: Glossary of Terms Term Task Transaction Transaction, Command Transaction, Conversational Transaction, Pseudo-Conversational Transid Definition A unit of processing required for the execution of a particular transaction. A unit of processing that consists of one or more application programs started by a single request. A Teradata-supplied transaction that manages the operation of the CICS Interface. A CICS transaction characterized by dialog with a user. Such a transaction waits for user input and responds with output data. A CICS transaction designed to appear to the user as a continuous conversation occurring as part of a single transaction. Unlike a conversational transaction, a pseudo-conversational transaction does not use CICS resources while waiting for user input. The four-character abbreviation of a CICS Interface transaction. Same as CICS transid. CICS Interface The CICS Interface enables CICS macro (CICS/OS/VS 1.7 and CICS/MVS 2.1 only) or command-level (CICS/OS/VS 1.7 and higher) application programs to access Teradata Database resources. Application Development in the Teradata Environment Customer-written CICS application programs may use one of the following: Call-Level Interface (CLI), version1 or version2 At present, two versions of CLI exist. Both have callable routines. In this reference, CLI refers to both CLI version1 (CLIv1) and CLI version2 (CLIv2), unless otherwise stated. New applications should use CLIv2. Customers are encouraged to convert existing applications using CLIv1 to CLIv2. Teradata language preprocessors At present, two preprocessor versions are supported: Preprocessor1, and the DB2-compatible Preprocessor2. Both translate embedded Teradata SQL statements and preprocessor directives into client language statements that perform the requested functions. 18 IBM CICS Interface for Teradata Reference, Release 15.10

19 Chapter 1: Overview of the CICS Interface Components of the CICS Interface New applications should use Preprocessor2. Customers are encouraged to convert existing applications using Preprocessor1 to Preprocessor2. Note: The CICS Interface is compatible with the CICS/ESA 3.3 storage protection feature, the CICS/ESA 4.1 transaction isolation feature, and the CICS Transaction Server. A CICS transaction can access any number of Teradata Databases using the standard CLI Connect function. Components of the CICS Interface The CICS Interface consists of the following components: The long-running transaction The CLI stub CLI support routines Task end/exit routine CICS command transactions for the Teradata Database Each of the above components is described in the sections below. The Long-Running Transaction DBCCICS The Teradata program called DBCCICS, the long-running CICS Interface transaction for accessing the Teradata Database, provides storage and context management services for CICS transactions (both conversational and pseudo-conversational) that access the Teradata Database. During initialization of the CICS Interface, DBCCICS loads both CLI and preprocessor runtime code. All CICS transactions for the Teradata Database, whether they use CLI directly or language preprocessors, share a single copy of this code. CLI uses CICS shared storage for its control blocks and data buffers. For pseudo-conversational applications, session and request context are automatically preserved across pseudo-conversational boundaries. This memory is released by the CICS Interface upon termination of the pseudo-conversation or transaction abend. The four-character transid for DBCCICS is DBCC. The CLI Stub The CLI stub consists of minimum-function routines that are link-edited with an application program to access the CLI runtime code. IBM CICS Interface for Teradata Reference, Release

20 Chapter 1: Overview of the CICS Interface CLI Support Routines The CLI stub has multiple entry points, all of which have the same names as CLI routines used in batch mode. The stub routine locates the corresponding CLI runtime module and then invokes the routine using branch entry. CLI Support Routines CLI support routines consist of CLI runtime code and that part of DBCCICS used to obtain and relinquish memory. CLI support routines perform CICS-specific processing, such as obtaining storage and waiting for work. Task End/Exit Routine The task end/exit routine is a CICS TRUE (Task Related User Exit) that uses the TASKSTART option in order to obtain control at transaction initiation and termination. The task end/exit routine determines if the ending transaction owns Teradata Database sessions and/or memory. If it does, the task end/exit routine logs off the session and releases memory. Note: Task end/exit routine processing does not occur for the end of pseudo-conversational transactions because session context is preserved across pseudo-conversational boundaries. CICS Command Transactions for the Teradata Database CICS command transactions for accessing the Teradata Database enable the operator using the CICS Interface to perform the following tasks: Start the CICS Interface Stop the CICS Interface Display Teradata Database session information Display the history and level of a particular CLI interface module Monitor and control the two-phase commit TDP connections Enable logons to the Teradata Database Disable logons to the Teradata Database Force the logoff of a particular Teradata session Display memory statistics Revise memory allocations, as required. 20 IBM CICS Interface for Teradata Reference, Release 15.10

21 CHAPTER 2 CICS Interface Operation This chapter describes the operation of the CICS Interface and the command transactions available for managing its operation. The command transactions are invoked through a four-character transid. These are listed by function in Table 2 and discussed in the order shown below: Table 2: Command Transactions Transid DRCN DSCN DSES DMHL DLGF DENA DISA Definition Start/restart the CICS interface Shutdown the CICS interface Display Teradata Database session information Display module history and version level Logoff a specific Teradata Database session Enable Teradata Database logons Disable Teradata Database logons DMEM Display memory statistics Revise memory allocations DAFC Monitor and control TDP connections named in DBCDLT for 2PC (two-phase commit) connections Note: The use of CEDF with CICS command transactions is not supported. For help on how to read syntax diagrams, see Appendix E: How to Read the Syntax Diagrams.. Starting the Interface The CICS Interface can be started in one of two ways: By adding the Teradata-supplied DFHPLT entry for DBCDRCN to the DFHPLTPI entries and reassembling the DFHPLTPI. This ensures that when CICS initializes, CICS automatically initializes the CICS Interface. IBM CICS Interface for Teradata Reference, Release

22 Chapter 2: CICS Interface Operation Startup Processing By entering on the command line the transid DRCN, as shown below: DRCN HB01A001 Messages Displayed Entering DRCN manually initializes the CICS Interface by invoking the Startup transaction. The following message is displayed to report that the CICS Interface is being restarted: DCI0100 DBCCICS INTERFACE INITIALIZING No other message is displayed to report that the interface has been restarted, but the following message is written to the MVS operator s console indicating that the interface is active: DCI0110 DBCCICS INITIALIZATION COMPLETE -- INTERFACE ACTIVE Verifying an Active Interface The following master terminal transaction verifies that the CICS Interface is active: CEMT INQUIRE TASK Notice: Do not use CEMT to force the DBCC transaction. DBCC must be shut down using the DSCN transaction to successfully perform shutdown cleanup. The use of the CEMT FORCE command can cause transaction hangs or abends and may require a CICS restart before the interface can be used again. Startup Processing Initialization Process During CICS startup processing, the Teradata-supplied program called DBCDRCN starts the transid DBCC. DBCC invokes the Teradata-supplied program called DBCCICS, a long-running CICS transaction, to perform the actual initialization of the CICS Interface. The Teradata program, DBCCICS, performs the following initialization stages: 1 Establishes a routine to trap and handle interface abends. 2 Enables the task end/exit routine. 3 Initializes the free storage chains as specified in the control block HSHSPBC (optional). 4 Loads the single-shared copy of the CLI and preprocessor runtime. 5 Waits for requests to freemain memory from transactions using the interface. 22 IBM CICS Interface for Teradata Reference, Release 15.10

23 Chapter 2: CICS Interface Operation Shutting Down the Interface 6 Waits for a request from DSCN to shut down the interface. 7 Starts the 2PC (two-phase commit) connections to TDPs whose entry in the DBCDLT specify START = YES. Shutting Down the Interface Use the Teradata-supplied DSCN transaction to shut down the CICS Interface. You can use DSCN to perform: orderly, or immediate (forced) shutdown of the interface. You should add an entry for program DBCDSCN to the DFHPLTSD entries so that the interface will shut down automatically during CICS termination. Syntax DSCN IMM = NO N YES Y HB01B002 Orderly and immediate shutdown of the CICS Interface are explained in the sections below. Orderly Shutdown An orderly shutdown results from one of the following: DBCDSCN is invoked by PLTSD during normal CICS termination. The DSCN command, with IMM (immediate) set to N, is issued by an authorized CICS terminal operator. The following message is issued to the terminal from which the shutdown is invoked: DCI0150: DBCCICS INTERFACE IS SHUTTING DOWN The following stages occur during an orderly shutdown: 1 Currently active CICS transactions accessing the Teradata Database are allowed to run to completion. Shutdown proceeds once resources owned by these transactions are released, either: explicitly by application request, or implicitly by transaction or conversation termination. IBM CICS Interface for Teradata Reference, Release

24 Chapter 2: CICS Interface Operation Immediate Shutdown If these transactions already have a session logged on at the time that interface shutdown is initiated, the transactions can do any of the following things: issue new requests, logon new sessions, or perform other actions. 2 CLIv2 or Preprocessor2 resources owned by terminals that are involved in a pseudo-conversation but which do not have a CICS transaction active are released. The session(s) are logged off and the memory is released. 3 It is not possible to release CLIv1 or Preprocessor1 resources owned by idle terminals within a pseudo-conversation because of differences in CLIv1 and Preprocessor 1 implementation. Thus, interface shutdown will not complete until these resources are explicitly released by a transaction executing from the terminal or implicitly by termination of the pseudo-conversation. DLGF can be used to log off the sessions but it will not release the resources. 4 The 2PC (two-phase commit) connections are stopped after all resources are released. 5 The task-related user exit is disabled for task start. Any transaction that attempts to use the CICS Interface following an orderly shutdown is rejected with a non-zero return code, indicating that the interface is inactive. Immediate Shutdown You can use the transid DSCN to shut down the CICS Interface immediately, even if an orderly shutdown had already been requested. To shut down the interface immediately, enter the DSCN command, with IMM (immediate) set to Y, on the command line. The following message is issued to report an immediate shutdown: DCI0151: DBCCICS INTERFACE IS SHUTTING DOWN IMMEDIATELY The following stages occur during an immediate shutdown: 1 Logons are disabled. Any subsequent attempts to use the interface are rejected with a non-zero return code that indicates that the interface is unavailable. Application abend AEY9 or ASP7 is also possible for applications using two-phase commit mode session. 2 All running Teradata Database sessions are logged off. Any in-flight units of work are rolled back. Two-phase commit sessions that are in the process of syncpoint may be left in-doubt. 24 IBM CICS Interface for Teradata Reference, Release 15.10

25 Chapter 2: CICS Interface Operation Shutdown Display and Recovery If so, the in-doubt must be resolved as soon as possible since the in-doubt session(s) may be holding locks on database objects. 3 The task-related user exit is disabled for task start. Shutdown Display and Recovery Any transaction that attempts to use the CICS Interface following a normal or immediate shutdown is rejected with a non-zero return code, indicating the interface is inactive. After the interface shuts down, the following message is written to the operator s console and to the CICS Transient Data Queue CSMT: DCI0111: DBCCICS INTERFACE TERMINATED Notice: Never terminate DBCCICS using a CEMT FORCE command. DBCC must be shut down by using the DSCN transaction to successfully perform shutdown cleanup. Use of CEMT FORCE can cause transactions to hang or abend and may require a CICS restart before the interface can be used again. IF the CICS Interface... THEN... abends terminates in such a way that sessions are still logged on to the Teradata Database the abend is detected and an exit routine obtains control. The exit routine performs the same processing as normal or immediate shutdown (the exit routine logs off all sessions and informs all users that the interface has abnormally shut down). the TDP LOGOFF command can be used from the MVS operator console to logoff such sessions. a CEMT FORCE command may have to be used to terminate Teradata Database transactions that are hung. Restarting the Interface Following either an orderly or an immediate shutdown of the CICS Interface, the interface may be restarted manually by entering on DRCN command transid, as shown below: DRCN HB01A001 IBM CICS Interface for Teradata Reference, Release

26 Chapter 2: CICS Interface Operation Error Processing and Recovery Messages Displayed The following message is displayed to report that the CICS Interface is being restarted: DCI0100 DBCCICS INTERFACE INITIALIZING Verifying an Active Interface No other message is displayed to report that the interface has been restarted. However, the following message is written to the operator console and to the CICS Transient Data Queue CSMT to indicate that the interface has been activated: DCI0110 DBCCICS INITIALIZATION COMPLETE -- INTERFACE ACTIVE The following master terminal transaction verifies that the CICS Interface is active: CEMT INQUIRE TASK Error Processing and Recovery Errors that affect the CICS Interface processing can occur in the following areas: CICS address space TDP address space Teradata Database If a CICS address space fails, all sessions logged on by the failed CICS are logged off and any uncommitted database changes are rolled back. DBCCICS, TDP, and Teradata Database failures and failure options are discussed in Teradata Call-Level Interface Version 2 Reference for Mainframe-Attached Systems (B ). Control Block Display The CICS Interface can display the following Teradata Database information: Session information Module history and version level Displaying Session Information To display information about all sessions currently logged onto the Teradata Database through CICS, enter the following command transid. DSES HB01A IBM CICS Interface for Teradata Reference, Release 15.10

27 Chapter 2: CICS Interface Operation Control Block Display Example Display The DSES transaction displays information on all the Teradata sessions logged on from the CICS region from which the command is entered. Below is an example of the display the DSES transaction produces. Leading zeros have been suppressed. Teradata Database--CICS SESSION CROSS REFERENCE DISPLAY TRAN TASK# TERM TDP SESS# REQUEST# FUNCTION STA IBUSZ OBUSZ #START #CONT H A4B CONNECT INC H A4D STARTREQ INC HICE i55 STARTREQ INC The headings in the example are defined as follows: Heading TRAN TASK# TERM TDP SESS# REQUEST# FUNCTION STA IBUSZ OBUSZ #START #CONT Definition The CICS transaction ID of the last transaction that issued a request on this session The CICS task ID number of the last transaction that issued a request on the session The terminal ID that owns the session if the transaction is started from a terminal. This field contains blanks if the transaction is not started from a terminal The TDPID of the TDP through which the transaction has established the Teradata session The number of the Teradata session (in decimal) The number of the last Teradata request (in decimal) The last CLI function that was issued on this session The status of the last request issued on this session, including CMP (complete) or INC (incomplete) The size (in bytes) of the application s fetch buffer The size (in bytes) of the application s request buffer The count of all Teradata start requests initiated on the session The count of all Teradata continue requests issued on the session DSES uses Basic Mapping Support (BMS) paging. This enables the operator to page through the DSES output using BMS paging commands. IBM CICS Interface for Teradata Reference, Release

28 Chapter 2: CICS Interface Operation Displaying Module History/Version Teradata recommends that the terminals from which operators issue the DSES transid are defined to CICS with Automatic Transaction Initiation (ATI) so that after invoking DSES, the CICS paging facility can display the first output page. If the DSES output does not fit on one screen, you can display additional screens by using the CICS operator paging commands. Normal CICS paging conventions apply. Displaying Module History/Version Module history and version level can be displayed by entering the following command transid: DMHL modulename HB01A004 where: Syntax element... Is the... modulename name of any CLI module, usually having a prefix of CXI or DBC. The information provided by the DMHL transaction shows the identification of the module. Example The following is an example of the information the DMHL transaction provides. DMHL CXIGRC CXIGRC COMPILED at on 10/18/88 HSI V.L=1.79, OS=MVS-SP13 Session Control The CICS Interface can perform the following operations: Log off a particular session. Disable logons to the Teradata Database by transactions in the CICS address space. Enable logons to the Teradata Database by any CICS transaction. 28 IBM CICS Interface for Teradata Reference, Release 15.10

29 Chapter 2: CICS Interface Operation Session Control Logging a Session Off A particular session can be logged off by entering the following command transid: DLGF SES = sessnum, TDP = n xxxx HB01B005 where: Syntax element... Is a... sessnum decimal number that identifies the session to be logged off. n digit (0 to 9). xxxx four-character TDPID. The sequence of events is as follows: 1 The DLGF transaction logs off a session on the Teradata Database. 2 Uncommitted database changes are rolled back but DLGF does not terminate the CICS transaction or free any buffers or other storage associated with the transaction s session. 3 The next time the transaction attempts to access the Teradata Database, the transaction is informed that the session no longer exists. 4 The Teradata session-related storage, which is associated with the transaction, is released only when the transaction is terminated. 5 If more than one TDP is active and a particular TDP is identified, the session is logged off from that TDP. 6 Although each session number within each TDP is unique, several TDPs may have sessions that have the same session numbers, causing a possible conflict during logoff. The TDPID resolves this ambiguity. Note: The session number arguments for all transactions changed to decimal (from hexadecimal) in release 3.1 of this interface. Disabling Logons You can disable logons to the Teradata Database (by transactions in the CICS address space) by entering the following command transid: DISA HB01A007 IBM CICS Interface for Teradata Reference, Release

30 Chapter 2: CICS Interface Operation Controlling TDP Connections for 2PC Commit Mode Enabling Logons The DISA transaction allows current sessions to continue until completed. If a transaction attempts to log on to the Teradata Database after DISA is issued, a nonzero return code (280) is returned to the requesting transaction. You can enable logons to the Teradata Database (by any CICS transaction) by entering the following command transid: DENA HB01A006 Controlling TDP Connections for 2PC Commit Mode The DAFC transaction is used to monitor or control TDP connections for all TDPs named in the DBC List Table (DBCDLT). The DBCDLT is prepared by your site during the installation process, and defines all TDPs with which Teradata applications may communicate in two-phase commit mode. Monitoring Memory You can monitor and control dynamically the memory HSHSPBC allocates for CLI by entering the DMEM command transit without the SET option: DMEM SET (name) SIZE (size) MAX (max ) SIZE (size) MAX (max ) HB01A IBM CICS Interface for Teradata Reference, Release 15.10

31 Chapter 2: CICS Interface Operation Monitoring Memory The DMEM transaction (with no options) displays the current allocation of memory so that it can be changed, as required, and provides a map, DBCMAPM, displayed on the screen as follows: where: Heading SIZE MIN MAX #FRE ALOC GETM USED OVRC OVRK >MAX Definition Installation-specified buffer size This column is no longer meaningful, since free blocks are no longer pre-allocated. Blocks are allocated by GETMAIN to satisfy application requests and then placed on the free chain when released. A block to be released that is placed on the free chain if the sum of the ALOC plus #FRE is less than MAX Number of blocks currently on the free chain Number of blocks currently in use by applications (not including #FRE) Number of getmains because of an empty free chain Number of times control blocks were obtained, including getmain and successful use of free blocks Number of over-allocations (requests assigned a larger buffer than required) Over-allocated kilobytes; that is, the sum of the number of over-allocated bytes Number of requests (with respect to the OVRC) and the number of requests (with respect to the OVRK) for buffers greater than the HSHSPBC-specified maximum IBM CICS Interface for Teradata Reference, Release

32 Chapter 2: CICS Interface Operation Controlling Memory Controlling Memory You can control memory in the CICS Interface by changing any or all of the following values: SIZE MAX OVRC OVRK SIZE and MAX You can change the values of SIZE and MAX by: Overtyping new values on the screen, or Entering DMEM and the SET option, as shown below: DMEM SET (name) SIZE (size) MAX (max ) SIZE (size) MAX (max ) HB01A008 where: Syntax element... Is the... name size max name of the block: TRXB, SESB, HRQB, TSCH, HRCB, or BUFx (where x is 1 through 8). size of the buffer to be allocated. desired maximum value. CLIv1 uses TSCH and HRCB. There is one TSCH per CICS transaction, and one HRCB per outstanding Teradata Database request per Teradata session. There is always a minimum of one HRCB per Teradata session, even if there are no outstanding Teradata requests. CLIv2 uses TRXB, SESB, and HRQB. There is one: TRXB per CICS transaction SESB per Teradata session HRQB per Teradata outstanding request. 32 IBM CICS Interface for Teradata Reference, Release 15.10

33 Chapter 2: CICS Interface Operation DMEM Command: Some Usage Notes OVRC and OVRK The values of OVRC and OVRK can be used to adjust the size of buffers defined in the HSHSPBC. For example, if two buffer sizes, one 4K and one 8K, are specified in the HSHSPBC, and the DMEM display (before shutdown) shows an OVRC = 2000 and an OVRK = 4000 for 8K buffers, then dividing the value of OVRK by the value of OVRC (for example, 4000/2000) yields the average over-allocation (in kilobytes) for 8K buffers. Subtracting the average over-allocation (for example, 2K) from the buffer size for which over-allocation has occurred (for example, 8K) yields the average buffer size (for example, 6K) that in fact reflects the actual buffer size being requested. Knowing the average buffer size of buffers being requested makes it possible to adjust the HSHSPBC for efficient use of memory. DMEM Command: Some Usage Notes When you use the DMEM command transit, remember the following: The DMEM counters are stable for the life of CICS. This means that the counts and the free chain contents are maintained across DBCC restarts. Free blocks of storage are not pre-allocated during DBCC initialization. This means that the MIN column is not significant. Blocks are placed on the free chain when released if the sum of #FRE plus ALOC is less than MAX. All storage used by CLI is shared storage and is not accounted for under the TCA of the requesting application. For CICS releases prior to CICS/ESA 3.2, all memory used is below the 16 MB line. Therefore, large numbers for MAX can result in virtual storage impact below the line. For CICS release CICS/ESA 3.2 and above, the free chain is only used for blocks that are above the 16 MB line. The response buffers for AMODE 24 applications may be below the line. For these, use of the free chain will be bypassed, but the DMEM counter will be updated. CICS Memory Management CLI manages memory for CICS by performing the following operation: Maintaining session context for conversational and pseudo-conversational transactions Minimizing overhead for GETMAIN and FREEMAIN memory routines IBM CICS Interface for Teradata Reference, Release

34 Chapter 2: CICS Interface Operation CICS Memory Management Maintaining Session Context CLI obtains and manages resources on behalf of calling transactions. These resources include Teradata sessions and memory, such as control blocks and buffers. The control blocks are structured to isolate the resources by owner. For transactions that are... The owner is... terminal-related (may be pseudo-conversational) non-terminal-related the terminal. the transaction. The resources are obtained at the time of the application request. Resources are released... When they are associated with... explicitly by the application implicitly at the end of the transaction at the end of the conversation ordinary transactions. non-terminal-related transactions. terminal-related transactions. Controlling Memory Usage The CICS interface provides a mechanism to monitor and control CLI use of memory. In particular, CICS getmain/freemain overhead can be reduced by using the HSHSPBC and the DMEM command to maintain a number of control blocks and buffers on a free chain to satisfy application requests. When allocating memory, CLI first attempts to satisfy the request from the free chain. If the chain is empty, a CICS getmain is used to obtain the memory. Statistics are maintained and are displayed with DMEM to monitor and control CLI memory usage. Refer to Controlling Memory on page 32. Minimizing Memory Overhead To reduce overhead associated with CICS transactions accessing the Teradata Database, the CICS Interface can be made to use previously acquired storage pre-allocated memory. Thus, at connect time, the CLI can simply obtain the necessary control blocks and buffers from a free chain jointly managed by DBCCICS and CLI under installation control (HSHSPBC-specified). This mechanism trades virtual storage against CPU overhead, providing the customer site with a mechanism to control and monitor memory management. 34 IBM CICS Interface for Teradata Reference, Release 15.10