Your SlideShare is downloading. ×
  • Like
MainframeConnect™ for DB2/MVS-CICS Installation and ...
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Now you can save presentations on your phone or tablet

Available for both IPhone and Android

Text the download link to your phone

Standard text messaging rates apply

MainframeConnect™ for DB2/MVS-CICS Installation and ...

  • 1,154 views
Published

 

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
1,154
On SlideShare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
17
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. MainframeConnect™ for DB2/MVS-CICS Installation and Administration Guide MainframeConnect for DB2/MVS-CICS version 11.1.1 Document ID: 36525-01-1111-01 Last Revised: September 30, 1997
  • 2. Document ID: 36525-01-1111 This publication pertains to MainframeConnect for DB2/MVS-CICS version 11.1.1 of the Sybase database management software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement. Document Orders To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845. Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. Copyright © 1989–1997 by Sybase, Inc. All rights reserved. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc. Sybase Trademarks Sybase, the Sybase logo, APT-FORMS, Certified SYBASE Professional, Data Workbench, First Impression, InfoMaker, PowerBuilder, Powersoft, Replication Server, S-Designor, SQL Advantage, SQL Debug, SQL SMART, SQL Solutions, Transact-SQL, VisualWriter, and VQL are registered trademarks of Sybase, Inc. Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server, Adaptive Server Monitor, ADA Workbench, AnswerBase, Application Manager, AppModeler, APT-Build, APT-Edit, APT-Execute, APT-Library, APT-Translator, APT Workbench, Backup Server, BayCam, Bit-Wise, ClearConnect, Client-Library, Client Services, CodeBank, Column Design, Connection Manager, DataArchitect, Database Analyzer, DataExpress, Data Pipeline, DataWindow, DB-Library, dbQ, Developers Workbench, DirectConnect, Distribution Agent, Distribution Director, Dynamo, Embedded SQL, EMS, Enterprise Client/Server, Enterprise Connect, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, EWA, Formula One, Gateway Manager, GeoPoint, ImpactNow, InformationConnect, InstaHelp, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase, Logical Memory Manager, MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MethodSet, Net-Gateway, NetImpact, Net-Library, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT-Execute, PC DB-Net, PC Net Library, Power++, Power AMC, PowerBuilt, PowerBuilt with
  • 3. PowerBuilder, PowerDesigner, Power J, PowerScript, PowerSite, PowerSocket, Powersoft Portfolio, Power Through Knowledge, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, Quickstart Datamart, Replication Agent, Replication Driver, Replication Server Manager, Report-Execute, Report Workbench, Resource Manager, RW-DisplayLib, RW-Library, SAFE, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL Anywhere, SQL Central, SQL Code Checker, SQL Edit, SQL Edit/TPU, SQL Modeler, SQL Remote, SQL Server, SQL Server/CFT, SQL Server/DBM, SQL Server Manager, SQL Server SNMP SubAgent, SQL Station, SQL Toolset, Sybase Client/Server Interfaces, Sybase Development Framework, Sybase Gateways, Sybase IQ, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase Synergy Program, Sybase Virtual Server Architecture, Sybase User Workbench, SybaseWare, SyBooks, System 10, System 11, the System XI logo, SystemTools, Tabular Data Stream, The Architecture for Change, The Enterprise Client/Server Company, The Model for Client/Server Solutions, The Online Information Center, Translation Toolkit, Turning Imagination Into Reality, Unibom, Unilib, Uninull, Unisep, Unistring, Viewer, Visual Components, VisualSpeller, WarehouseArchitect, WarehouseNow, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, and XA-Server are trademarks of Sybase, Inc. 6/97 All other company and product names used herein may be trademarks or registered trademarks of their respective companies. Restricted Rights Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies. Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.
  • 4. Table of Contents About this Book Who Should Read This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Syntax and Style Conventions in this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Syntax Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Style Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii How to Get Help Using Sybase Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Sybase Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Contacting Sybase Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . xix Sending Log and Trace Files to Sybase Technical Support. . . . . . . . . . xx Sybase Professional Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Other Sources of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Online Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii Sybase Certifications and EBFs on the Web . . . . . . . . . . . . . . . . . . . . . . . xxii Sybase OpenLine and PrivateLine on CompuServe . . . . . . . . . . . . . . . . xxiii Fax-on-Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv If You Have Questions About this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv Planning 1. Understanding Enterprise Connect What is Enterprise Connect?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Enterprise Connect and Previous Sybase Products. . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Enterprise Connect Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 MainframeConnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 DirectConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 DirectConnect Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 DirectConnect Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Open ServerConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Open ClientConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 ClearConnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 Enterprise Connect Processing Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Products Used with Enterprise Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 Related Sybase Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 Related IBM Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 MainframeConnect for DB2/MVS-CICS Install & Admin Guide v
  • 5. MainframeConnect for DB2/MVS-CICS version 11.1.1 2. Understanding MainframeConnect MainframeConnect Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 MainframeConnect Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Components of MainframeConnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Transaction Processor AMD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Host Request Library DB2 Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Communication with Other Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Other Mainframe Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 DirectConnect for MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Other Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 MainframeConnect Communication Path . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 3. Planning Your Installation What Can You Install with This Product? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Installation Task Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Preinstallation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Checking the Personnel Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Checking the System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Checking Special System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Considering Performance Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Using SDLC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Using Token Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 RU Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Checking the Mainframe Access Components. . . . . . . . . . . . . . . . . . . . . . 3-6 Checking the Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Checking Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Checking the VTAM and NCP Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Checking the CICS Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 4. Migrating from Previous Installations Understanding Migration Considerations with MainframeConnect . . . . . . . . . . . . . . 4-1 New Default Transaction Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 CSAs and RSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Preparing to Upgrade to MainframeConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Removing a Prior Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Assigning Library Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Preserving Customized Messages on AMD2CAMX . . . . . . . . . . . . . . . . . 4-3 vi Table of Contents
  • 6. MainframeConnect for DB2/MVS-CICS version 11.1.1 Installing 5. Installing the MainframeConnect Tape Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Post-Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Authorizing Users for the Application Plan . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Authorizing Users for DB2 Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Authorizing Users for System Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 Verifying Your Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 Contents of the MainframeConnect Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 COPY Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 CTRL Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 DBRM Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 JCL Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 LOADLIB Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 MACLIB Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 SOURCE Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 What’s Next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 6. Installing Catalog Stored Procedures for Transaction Router Service Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 Contents of the MainframeConnect TRS Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 TRS.CTRL Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 TRS.DBRM Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 TRS.JCL Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 TRS.LOAD Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 What’s Next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 Configuring & Customizing 7. Configuring MainframeConnect Changing the MainframeConnect Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 Understanding the Configuration Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 Transaction ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 Request exit name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Result exit name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Parse exit name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Group ID exit name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 MainframeConnect for DB2/MVS-CICS Install & Admin Guide vii
  • 7. MainframeConnect for DB2/MVS-CICS version 11.1.1 Host request library ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 Temp storage queue type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 DateTime results type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7 What’s Next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7 8. Customizing MainframeConnect Messages Understanding the AMD2 Message Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 Translate Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 Example of Translate Table Source Code . . . . . . . . . . . . . . . . . . . . . . . 8-2 Translate Table Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 Text Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 Example of Text Table Source Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 National Languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 Message Variable Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6 Changing the AMD2 Message Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 Adding Entries for New SQLCODEs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 Adding or Changing Messages for a Parse Exit Routine . . . . . . . . . . . . . 8-8 Customizing Message Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9 Eliminating Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10 Changing Message Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10 Coding AMD2 Message Table Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 Changing the Translate Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 Adding a Translate Table Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 Modifying a Translate Table Entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 Changing the Text Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12 Rules for Text Table Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12 Modifying a Message in the Text Table . . . . . . . . . . . . . . . . . . . . . . . . 8-13 Adding a Message to the Text Table . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13 Adding a Language to the Text Table . . . . . . . . . . . . . . . . . . . . . . . . . 8-13 9. User Exits User Exits in MainframeConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Request/Result Validation Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Understanding Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 Enabling Request/Result Validation Exits . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 Using the Sample Validation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 Understanding the Exit Communication Area. . . . . . . . . . . . . . . . . . . . . . 9-5 Common Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Writing a Request Validation Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7 Writing a Result Validation Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8 viii Table of Contents
  • 8. MainframeConnect for DB2/MVS-CICS version 11.1.1 Using the Group ID Exit Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10 Understanding Group ID Exit Name Processing. . . . . . . . . . . . . . . . . . . 9-10 Parse Exit Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 Understanding the Parse Exit Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 Calling the Parse Exit from AMD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 Processing Batched SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 Processing User-Defined Transactions . . . . . . . . . . . . . . . . . . . . . . . . 9-13 Returning to AMD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 The Parse Exit Common Area. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 Layout of the AMD2XCOB Copy Book . . . . . . . . . . . . . . . . . . . . . . . 9-14 CICS Common Area Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15 Getting Ready to Code Your Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16 Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16 Sample Parse Exit Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16 Coding Your Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16 Altering the SQL Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17 Acquiring Additional Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18 Assigning a Return Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19 Selecting an Error Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19 Compiling and Link-Editing Your Routine . . . . . . . . . . . . . . . . . . . . . . . 9-20 Enabling Your Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20 Troubleshooting 10. Troubleshooting Verifying Connectivity After Installing MainframeConnect . . . . . . . . . . . . . . . . . . . . 10-1 Where to Start Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 Common Problems and Suggested Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 Configuration Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 Cannot Establish a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 Session Established, but the Transaction Does Not Run . . . . . . . . . 10-4 SDLC Line or Token Ring is Not Up . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4 SDLC Link and PU are Active, but the LU Is Not Active. . . . . . . . . 10-4 Mainframe Network Operational Failure . . . . . . . . . . . . . . . . . . . . . . . . . 10-5 Network Session or Line Failures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5 Preventative Measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6 DirectConnect Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7 DirectConnect Communications with MainframeConnect . . . . . . . . . . 10-8 MainframeConnect for DB2/MVS-CICS Install & Admin Guide ix
  • 9. MainframeConnect for DB2/MVS-CICS version 11.1.1 SNA LU 6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8 TCP/IP Uplink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8 Mainframe Communications with DirectConnect. . . . . . . . . . . . . . . . . . 10-9 VTAM/NCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9 TCP/IP for MVS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9 TCP/IP Sockets Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9 CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9 MainframeConnect for DB2/MVS-CICS. . . . . . . . . . . . . . . . . . . . . . . . . 10-10 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11 Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14 Processing Flow and Enterprise Connect Requirements . . . . . . . . . . . 10-14 Process Flow During Attention Sequences . . . . . . . . . . . . . . . . . . . . . . . 10-17 Appendixes A. Error Messages Understanding the Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Message Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 MainframeConnect Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Messages Mapped to SQL Server Messages . . . . . . . . . . . . . . . . . . . A-2 How Errors are Logged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 Defining Log Files to CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 Interpreting the Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 MainframeConnect Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5 B. DB2 Database Administrator Information for TRS Stored Procedures and DBMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Keeping Server and Stored Procedure Information Current . . . . . . . . . . . . . . . . . . . . B-1 New Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Stored Procedure Names on DirectCONNECT . . . . . . . . . . . . . . . . . . . . . B-2 Glossary Index x Table of Contents
  • 10. List of Figures Figure 2-1: MainframeConnect communication path ..................................................................2-7 Figure 7-1: Mainframe Connect Configuration Tran ID Selection screen .................................7-2 Figure 7-2: Mainframe Connect Configuration screen.................................................................7-3 Figure 10-1: Open ServerConnect and DirectConnect support components ...........................10-7 Figure 10-2: MainframeConnect and DirectConnect support components ............................10-11 Figure 10-3: Processing flow: client-to-DirectConnect-to-mainframe......................................10-14 MainframeConnect for DB2/MVS-CICS Install & Admin Guide xi
  • 11. MainframeConnect for DB2/MVS-CICS version 11.1.1 xii List of Figures
  • 12. List of Tables Table 1: Syntax conventions..................................................................................................... xviii Table 2: Style Conventions....................................................................................................... xviii Table 1-1: Enterprise Connect and corresponding predecessors..............................................1-1 Table 1-2: MainframeConnect predecessors ................................................................................1-3 Table 1-3: DirectConnect predecessors .........................................................................................1-4 Table 1-4: TRS predecessor.............................................................................................................1-5 Table 1-5: MCC predecessors .........................................................................................................1-6 Table 1-6: Open ServerConnect predecessor ...............................................................................1-7 Table 1-7: Open ClientConnect predecessor ................................................................................1-8 Table 1-8: Related Sybase products.............................................................................................1-11 Table 1-9: Related IBM products .................................................................................................1-12 Table 3-1: Installation process ........................................................................................................3-1 Table 3-2: Mainframe Access components...................................................................................3-6 Table 4-1: Sybase resources ............................................................................................................4-3 Table 5-1: COPY library ..................................................................................................................5-6 Table 5-2: CTRL library...................................................................................................................5-6 Table 5-3: DBRM library .................................................................................................................5-7 Table 5-4: JCL library.......................................................................................................................5-7 Table 5-5: LOADLIB library ...........................................................................................................5-7 Table 5-6: MACLIB library .............................................................................................................5-8 Table 5-7: SOURCE library .............................................................................................................5-9 Table 6-1: TRSCTRL library............................................................................................................6-3 Table 6-2: TRS.DBRM library .........................................................................................................6-4 Table 6-3: TRS.JCL library ..............................................................................................................6-5 Table 6-4: TRS.LOAD library .........................................................................................................6-5 Table 7-1: Types of temporary storage queues ............................................................................7-5 Table 8-1: Message table members ................................................................................................8-2 Table 8-2: Message variable indicators and values.....................................................................8-6 Table 8-3: Adding entries for new SQLCODEs ...........................................................................8-7 Table 8-4: Adding or changing messages for a parse exit routine............................................8-8 Table 8-5: Customizing message text............................................................................................8-9 Table 8-6: Eliminating messages..................................................................................................8-10 Table 8-7: Changing message logging ........................................................................................8-10 Table 8-8: Changing the AMD2 message table..........................................................................8-11 Table 9-1: Common Exit Communication Area Fields...............................................................9-7 Table 9-2: Request Validation Communication Area Fields......................................................9-7 Table 9-3: Result Validation Communication Area Fields.........................................................9-9 Table 9-4: Altering values in common area fields.....................................................................9-12 MainframeConnect for DB2/MVS-CICS Install & Admin Guide xiii
  • 13. MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 9-5: CICS Common Area Fields ........................................................................................9-15 Table A-1: Abbreviations for message text ................................................................................. A-4 Table B-1: DB2 Database administrator-maintained tables ...................................................... B-1 xiv List of Tables
  • 14. About this Book This book describes how to install and configure MainframeConnect for DB2/MVS-CICS version 11.1.1 (also referred to as MainframeConnect). It includes planning considerations, installation instructions, configuration instructions, and troubleshooting information. This preface includes the following topics: • “Who Should Read This Book” on page xv • “How to Use This Guide” on page xv • “Related Documents” on page xvii • “Syntax and Style Conventions in this Book” on page xvii • “How to Get Help Using Sybase Products” on page xix • “Other Sources of Information” on page xxi • “If You Have Questions About this Book” on page xxiv Who Should Read This Book These specific guidelines and step-by-step instructions are intended for those who install, configure, and maintain Sybase mainframe client/server components on an IBM System/390 mainframe. This guide is for anyone who performs tasks, such as a: • CICS system programmer • DB2 database administrator • DirectConnect administrator This guide assumes you have a working knowledge of system administration for your environment. For an MVS-CICS environment, for example, you should be familiar with MVS and CICS system administrative procedures, such as defining CICS resources and VTAM definitions. How to Use This Guide This guide consists of five sections: planning, installing, configuring, troubleshooting, and appendixes. The first four sections contain MainframeConnect for DB2/MVS-CICS Install & Admin Guide xv
  • 15. How to Use This Guide MainframeConnect for DB2/MVS-CICS version 11.1.1 chapters that describe sets of tasks. The last section contains useful reference information. MainframeConnect requires the Open ServerConnect for CICS/MVS base tape to be installed. Therefore, the Open ServerConnect for CICS/MVS base tape is shipped with MainframeConnect. You will find instructions for installing the Open ServerConnect for CICS/MVS base tape in the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS, which is also shipped with MainframeConnect. The following table shows tasks you perform using this guide and the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS. The Open ServerConnect Installation and Administration Guide for IBM CICS/MVS is abbreviated in the following table as “OSC guide.” To See Understand Enterprise Connect products Chapter 1 MainframeConnect components Chapter 2 Plan Installation and configuration Chapter 3 Migration from OmniSQL Access Module Version 10.1 or MDI Chapter 4 Access Server for MVS-CICS Version 2.3 or later Install Libraries from the Open ServerConnect CICS/MVS base tape OSC Guide Libraries from the MainframeConnect tape Chapter 5 CSP libraries for TRS from the MainframeConnect tape Chapter 6 Libraries from the Japanese Conversion Module tape OSC Guide Configure MainframeConnect to communicate with DirectConnect Chapter 7 AMD2 messages for MainframeConnect Chapter 8 Understand and write user exit routines Chapter 9 Troubleshoot Problems with client access to data on the mainframe Chapter 10 Compile and Link Sample programs OSC Guide Customize Global and single byte character set (SBCS) options OSC Guide DB2 database administrator-maintained tables Appendix B Reference MainframeConnect-specific messages Appendix A Security information OSC Guide Default translation tables to customize SBCSs OSC Guide Unfamiliar terms and acronyms Glossary xvi About this Book
  • 16. MainframeConnect for DB2/MVS-CICS version 11.1.1 Related Documents Related Documents To install and administer MainframeConnect, in addition to this book, you need the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS, which ships with MainframeConnect. For the latest product information, refer to the release bulletins for MainframeConnect and Open ServerConnect. You may also need to refer to the following related documentation: • DirectConnect for MVS Connectivity Guide • DirectConnect for MVS Installation Guide • DirectConnect for MVS Access Service User’s Guide • DirectConnect Transaction Router Service User’s Guide • DirectConnect Server Administration Guide • DirectConnect Error Message Guide • DirectConnect Configuration Tool User Guide • DirectConnect Configuration Tool Installation Guide • Open ServerConnect Programmer’s Reference for Remote Stored Procedures • Open ClientConnect Programmer’s Reference for Client Services Applications • Open ClientConnect and Open ServerConnect Messages and Codes Syntax and Style Conventions in this Book This section describes the syntax and style conventions used in this book. ® Note All references to SQL Server in this book also apply to Adaptive Server. Syntax Conventions Syntax statements that display options for a command look like this: COMMAND [object_name, [ {TRUE | FALSE} ] ] MainframeConnect for DB2/MVS-CICS Install & Admin Guide xvii
  • 17. Syntax and Style Conventions in this Book MainframeConnect for DB2/MVS-CICS version 11.1.1 The following table explains the syntax conventions used in this guide. Table 1: Syntax conventions Symbol () Parentheses indicate that parentheses are included as part of the command. {} Braces indicate that you must choose at least one of the enclosed options. Do not type the braces when you type the option. [] Brackets indicate that you can choose one or more of the enclosed options, or none. Do not type the brackets when you type the options. | The vertical bar indicates that you can select only one of the options shown. Do not type the bar in your command. , The comma indicates that you can choose one or more of the options shown. Separate each choice by using a comma as part of the command. Style Conventions The following style conventions are used in this book: Table 2: Style Conventions This type of information Looks like this Directories and files econnectServerNamecfg Programs, utilities, procedures, and snrfck commands Properties Allocate Options connect Code examples and text on screen this font Commands you should enter this font Variables you should replace with the this font appropriate value for your system when entering a command All other names and terms are in regular typeface. xviii About this Book
  • 18. MainframeConnect for DB2/MVS-CICS version 11.1.1 How to Get Help Using Sybase Products How to Get Help Using Sybase Products Each Sybase installation that has purchased a support contract has one or more designated people who are authorized to contact Sybase Technical Support. If you cannot resolve a problem using the manuals or online help, please have the designated person contact Sybase Technical Support or the Sybase subsidiary in your area. If you need help using a Sybase product, the following resources are available: • Sybase Technical Support • Sybase Professional Services • Other sources of information Sybase Technical Support Sybase Technical Support provides various forms of customer assistance, including the following services: • Identifying problems. • Offering a fix, if available. • Documenting software problems and enhancement suggestions in our customer support database. • Communicating status information on open problems. • Sharing information on new products or releases of existing products. In addition, Sybase system engineers are available for technical assistance in various geographical territories. The following subsections explain how to contact Sybase Technical Support and how to send log and trace files, if necessary. Contacting Sybase Technical Support You can contact Sybase Technical Support by phone or electronic mail (e-mail). Before you contact Sybase Technical Support, complete these steps: 1. Thoroughly review the documentation, especially all troubleshooting sections. 2. Be prepared to generate a trace, if requested to do so by Technical Support. MainframeConnect for DB2/MVS-CICS Install & Admin Guide xix
  • 19. How to Get Help Using Sybase Products MainframeConnect for DB2/MVS-CICS version 11.1.1 Contacting by Phone You can reach Sybase Technical Support by calling (800) 8SYBASE. Hours are 5:00 AM to 6:30 PM, Monday through Friday, Mountain Standard or Daylight Savings Time (MST or MDT), except holidays. ® Note Outside the continental United States and Canada, obtain the correct telephone numbers from your sales representative and record them here for future reference:______________________________. Contacting by E-Mail Send an e-mail to Sybase Technical Support in the following circumstances: • If you have a general question that is not urgent, for instance, a question about configuration planning. • If you need help with a product outside of the working hours of Sybase Technical Support, you can send an e-mail to be received as soon as personnel become available. Use this address to send e-mail to Sybase Technical Support: icdtech@sybase.com Sending Log and Trace Files to Sybase Technical Support You can send log and trace files or other documents to Sybase Technical Support using the Sybase file transfer protocol or the Bulletin Board Service. Using File Transfer Protocol (ftp) To place trace output or other documents on the Sybase ftp server: 1. Save your trace output as an ASCII file. 2. In the directory where the file resides, type ftp at the command line. 3. When prompted, provide the following information: - Sybase server = ftp.sybase.com - ID = anonymous - Password = your e-mail address xx About this Book
  • 20. MainframeConnect for DB2/MVS-CICS version 11.1.1 Other Sources of Information 4. Type: cd /pub/incoming/wcss 5. To change to binary mode, type: bin 6. Place one or more files into the directory. - To place one file in the directory, type: put filename - To place multiple files in the directory, type mput filename filename filename When prompted, type Y and press Enter to transfer each file. 7. Notify Sybase Technical Support of the exact name of the file(s) you sent to the server. (Remember that the Unix system is case- sensitive.) Using the Bulletin Board Service (BBS) To send log and trace files to Sybase Technical Support or to receive software fixes using the BBS: 1. Call (303) 413-4285. 2. Use parameters 8-1-N and a baud rate of 300-14400. Sybase Professional Services Sybase Professional Services offers on-site consulting and training programs to help you maximize the benefits of our products. For more information, call (303) 486-7700. ® Note Outside the continental United States and Canada, obtain the correct telephone numbers from your sales representative and record them here for future reference:______________________________. Other Sources of Information Other sources of information include: • Online documentation MainframeConnect for DB2/MVS-CICS Install & Admin Guide xxi
  • 21. Other Sources of Information MainframeConnect for DB2/MVS-CICS version 11.1.1 • Sybase certifications and Emergency Bug Fixes (EBFs) on the Web • Sybase OpenLine and PrivateLine on Compuserve • Fax-on-Demand Online Documentation Use the SyBooks™ and SyBooks-on-the-Web online resources to learn more about your product. Accessing SyBooks SyBooks documentation is on the CD that comes with your software. The DynaText browser, also included on the CD, allows you to access technical information about your product in an easy-to-use format. Refer to Installing SyBooks in your documentation package for instructions on installing and starting SyBooks. Accessing SyBooks-on-the-Web SyBooks-on-the-Web is an HTML version of SyBooks that you can access using a standard Web browser. To use SyBooks-on-the-Web, go to http://www.sybase.com and choose Documentation. Sybase Certifications and EBFs on the Web Sybase certifications and EBFs are available through the Sybase Technical Information Library. Accessing Product Certifications 1. Point your Web browser to the Technical Information Library at the following URL: http://techinfo.sybase.com 2. In the Browse section, choose the Hot entry. 3. Choose the topic that interests you. xxii About this Book
  • 22. MainframeConnect for DB2/MVS-CICS version 11.1.1 Other Sources of Information Accessing EBFs through SupportPlus ® Note To access EBFs, you must be a registered SupportPlus user. See “Registering as a SupportPlus User” on page xxiii for registration instructions. 1. Go to the following URL: http://techinfo.sybase.com 2. In the Browse section, choose the Hot entry. 3. Choose the EBF Rollups entry. You can research EBFs using the Technical Information Library, and you can download EBFs using Electronic Software Distribution (ESD). 4. Follow the instructions associated with the SupportPlusSM Online Services entries. Registering as a SupportPlus User To use SupportPlus, you need: • A Web browser that supports the Secure Sockets Layer (SSL), such as Netscape Navigator 1.2 or later • An active support license • A named technical support contact • Your user ID and password To register as a SupportPlus user: 1. Go to the Sybase home page at the following URL: www.sybase.com 2. Choose Technical Support. 3. Choose Enterprise Technical Support. 4. Choose register for SupportPlus. Sybase OpenLine and PrivateLine on CompuServe Sybase OpenLine and PrivateLine are the Sybase question and answer forums on CompuServe. To access Sybase OpenLine: MainframeConnect for DB2/MVS-CICS Install & Admin Guide xxiii
  • 23. If You Have Questions About this Book MainframeConnect for DB2/MVS-CICS version 11.1.1 1. Connect to CompuServe using the normal procedures for your site. 2. At any menu prompt, type: go sybase Fax-on-Demand Use Fax-on-Demand to receive Certification Reports, Release Summaries, Sample Programs, Technical News Letters (TNL), and Technical White Papers. To use Fax-on-Demand: 1. Call (800) 423-8737. Outside the United States and Canada, call (303) 575-6132. 2. Choose option 2 and follow the recorded instructions. If You Have Questions About this Book If you have questions, comments, or suggestions about this book, contact the Sybase documentation group directly by e-mail at: icd_doc@sybase.com Feel free to forward any information, comments, or questions about: • Missing, incorrect, or unclear information • Information you found particularly useful • Organization or style We will respond as promptly as possible by e-mail. Your feedback helps us provide more accurate, detailed, and easy-to-use documentation. ® Note Please send comments about product features, functionality, or problems to your system engineer or Sybase Technical Support. To order additional copies of Enterprise Connect documentation, see “Document Orders” on the disclaimer page following the title page. xxiv About this Book
  • 24. Planning
  • 25. 1 Understanding Enterprise Connect 1. This chapter provides an overview of the Enterprise Connect™ products, including how MainframeConnect™ relates to other Enterprise Connect products. It includes the following topics: • What is Enterprise Connect? 1-1 • Enterprise Connect and Previous Sybase Products 1-1 • Enterprise Connect Product Overview 1-2 • Enterprise Connect Processing Environment 1-10 • Products Used with Enterprise Connect 1-11 What is Enterprise Connect? Enterprise Connect is a set of Sybase® products that provides a common, enterprise-wide architecture that supports the development of distributed computing applications. Enterprise Connect provides the following services: • Access to distributed databases • Mainframe integration • Batch and real-time information delivery • Object interfaces • Transaction services • Internet services Enterprise Connect and Previous Sybase Products Enterprise Connect refers to the new generation of Sybase middleware, as well as its predecessors. The following table maps Enterprise Connect products to their corresponding predecessors: Table 1-1: Enterprise Connect and corresponding predecessors Enterprise Connect Sybase Net-Gateway MDI Database Gateway DirectConnect™ Net-Gateway™ Database Gateway • Access Services • (dynamic SQL access within • (dynamic SQL access within Net-Gateway) Database Gateway) MainframeConnect for DB2/MVS-CICS Install & Admin Guide 1-1
  • 26. Enterprise Connect Product Overview MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 1-1: Enterprise Connect and corresponding predecessors Enterprise Connect Sybase Net-Gateway MDI Database Gateway • Transaction Router Service • Mainframe Server Gateway • n/a (TRS) (MSG) • Mainframe Client Connect • Mainframe Client Gateway • Database Gateway Access (MCC) (MCG) Server • DirectConnect Configuration • n/a • Gateway Manager Tool Open ServerConnect™ Open Server/Mainframe MDI Access Server (RSPs) Open ClientConnect™ Open Client/Mainframe MDI Access Server (CSAs) MainframeConnect for OmniSQL Access Module™ for MDI Access Server (DB2) DB2/MVS-CICS DB2-CICS Enterprise Connect Product Overview This section explains the following products and their components, as well as their predecessor products: • MainframeConnect • DirectConnect • DirectConnect Configuration Tool • Open ServerConnect • Open ClientConnect • ClearConnect MainframeConnect MainframeConnect is mainframe software that works with DirectConnect or Net-Gateway 3.0 or later to provide access to mainframe data. It performs the following functions: • Supports full read-write, dynamic SQL access to data • Allows applications to use cursors for flexible and efficient result set processing • Permits the use of long-running transactions against mainframe databases • Allows applications to use dynamic events to map SQL to a static plan 1-2 Understanding Enterprise Connect
  • 27. MainframeConnect for DB2/MVS-CICS version 11.1.1 Enterprise Connect Product Overview Client applications access MainframeConnect directly through a DirectConnect Access Service or DirectConnect TRS. Client applications access MainframeConnect indirectly through OmniConnect™ or a Sybase SQL Server™ remote procedure call (RPC). ® Note MainframeConnect is available only for Multiple Virtual Storage (MVS)/Customer Information Control System (CICS) environments. For IMS TM and native MVS environments, use OmniSQL Access Module for DB2-IMS TM and MVS. The following table provides migration information about the MainframeConnect predecessor products. Table 1-2: MainframeConnect predecessors Product Migration information OmniSQL MainframeConnect for DB2/MVS-CICS replaces Access Module OmniSQL Access Module for DB2-CICS. It does not for DB2-CICS replace OmniSQL Access Module for DB2-IMS TM and MVS. You can use either Net-Gateway MSG 3.0 or later or DirectConnect TRS with MainframeConnect for DB2/MVS-CICS. MDI Access MainframeConnect for DB2/MVS-CICS replaces MDI Server Access Server. DirectConnect DirectConnect is Open Server™-based software that supports Database Library (DB-Library), Client Library (CT-Library), and Open Database Connectivity (ODBC) application programming interfaces (APIs). DirectConnect serves as a fundamental building block for database middleware applications. DirectConnect products are local area network (LAN)-based middleware gateways and servers that provide access to non-Sybase data and applications. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 1-3
  • 28. Enterprise Connect Product Overview MainframeConnect for DB2/MVS-CICS version 11.1.1 DirectConnect provides the following middleware services for decision support and online transaction processing (OLTP) applications: • Access Services, which provide access to non-Sybase data sources. The Access Service for MVS is the recommended path for accessing MVS data using SQL. (Access Services use MainframeConnect.) • Transaction Router Service (TRS), which is used when the mainframe acts as a server and provides access from the LAN to the mainframe over a Systems Network Architecture (SNA) or Transmission Control Protocol/Internet Protocol (TCP/IP) network. (TRS uses Open ServerConnect.) • Mainframe Client Connect (MCC), which is used when the mainframe acts as a client and supports access from the mainframe to the LAN over an SNA or TCP/IP network. Open ClientConnect uses MCC. The following table provides migration information about the DirectConnect predecessor products. Table 1-3: DirectConnect predecessors Product Migration information Net-Gateway DirectConnect and its TRS and MCC components replace Net-Gateway and its MSG and MCG components. Net-Gateway 3.0 or later provides the same functionality as DirectConnect using TRS and MCC if Open ServerConnect (or Open Server/Mainframe) and Open ClientConnect (or Open Client/Mainframe) reside on the mainframe. Specifically, Net-Gateway 3.0 or later routes requests: • from the LAN to the mainframe (using MSG) • from the mainframe to the LAN (using MCG) Database DirectConnect replaces the Database Gateway. Gateway DirectConnect Components This section explains the components of DirectConnect: Access Services, Transaction Router Service, and Mainframe Client Connect. 1-4 Understanding Enterprise Connect
  • 29. MainframeConnect for DB2/MVS-CICS version 11.1.1 Enterprise Connect Product Overview Access Services An access service is a logical server application, used with an access service library, to which clients connect. Each DirectConnect server can have multiple access services. For more information about access services and access service libraries, see the DirectConnect for MVS Access Service User’s Guide. Transaction Router Service (TRS) TRS is used when the mainframe acts as a transaction server. It routes requests from remote clients to Open ServerConnect transactions. Optionally, it can also route requests to MainframeConnect for DB2/MVS-CICS (or OmniSQL Access Module for DB2-CICS), and return results to the clients. The following table provides migration information about the TRS predecessor product. Table 1-4: TRS predecessor Product Migration information Mainframe DirectConnect and its TRS component replace Server Gateway Net-Gateway and its MSG component. (MSG) Net-Gateway 3.0 or later and MSG provide the same functionality as TRS. Specifically, MSG is available to route requests from the LAN using Open ServerConnect (or Open Server/Mainframe) to the mainframe. Mainframe Client Connect (MCC) MCC, a component of DirectConnect, is used when the mainframe acts as a client. It is a LAN-based program that lets mainframe Open ClientConnect applications connect to LAN servers. It performs data and protocol translation between SNA/LU 6.2 (APPC) and TCP/IP with the LAN network protocols. When accessing LAN-based data from the mainframe through SNA, MCC is required. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 1-5
  • 30. Enterprise Connect Product Overview MainframeConnect for DB2/MVS-CICS version 11.1.1 The following table provides migration information about the MCC predecessor products. Table 1-5: MCC predecessors Product Migration information Mainframe DirectConnect and its MCC component replace Client Gateway Net-Gateway and its MCG component. (MCG) Net-Gateway 3.0 or later and MCG provide the same functionality as MCC. Specifically, MCG is available to route requests from the mainframe using Open ClientConnect (or Open Client/Mainframe) to the LAN. Database DirectConnect and MCC replace the Database Gateway Gateway Access Access Server. Server DirectConnect Configuration Tool DirectConnect Configuration Tool is an Open Client™-based graphical user interface (GUI) systems management tool for administering data access through DirectConnect. DirectConnect Configuration Tool runs on Windows 3.1, Windows 95, or Windows NT. It provides the following capabilities: • Remote start, stop, and configuration of DirectConnect • Dynamic configuration of services • Drag-and-drop service creation and copying • Remote log filtering and downloading • Heartbeat services ® Note DirectConnect Configuration Tool is not currently available for use with Mainframe Client Connect. Open ServerConnect Open ServerConnect is a programming environment that lets you create mainframe transactions that are accessible to Sybase client applications. To provide this access, Open ServerConnect uses the following basic interfaces: 1-6 Understanding Enterprise Connect
  • 31. MainframeConnect for DB2/MVS-CICS version 11.1.1 Enterprise Connect Product Overview • The traditional Open Server programming environment (for new customers and Sybase-heritage customers using new applications) • The Remote Stored Procedure (RSP) programming environment (only for MDI-heritage customers using their old applications) These transactions provide access to virtually any MVS data source and are used for a variety of functions, including: • Accessing existing mainframe applications • Initiating mainframe batch jobs • Providing source data for data transfer operations • Providing data mapped to a table within OmniConnect, thus allowing results to be accessed or joined with data from other targets LAN-side client applications access Open ServerConnect transactions directly through DirectConnect or indirectly through OmniConnect or a Sybase SQL Server remote procedure call (RPC). The following table provides migration information about the Open ServerConnect predecessor products. Table 1-6: Open ServerConnect predecessor Product Migration information Open Server/ Open ServerConnect replaces Open Server/Mainframe. Mainframe Note: If you still use Open Server/Mainframe at your site, cursor processing is unavailable. Cursor processing is available only with Open ServerConnect, releases 3.1 and later. MDI Access Open ServerConnect replaces MDI Access Server (RSPs) Server Open ClientConnect Open ClientConnect is a programming environment that lets you create mainframe applications that access LAN data residing on a Sybase SQL Server or any other supported data source. It allows you to treat the mainframe as just another node on a LAN. Open ClientConnect uses the following APIs: MainframeConnect for DB2/MVS-CICS Install & Admin Guide 1-7
  • 32. Enterprise Connect Product Overview MainframeConnect for DB2/MVS-CICS version 11.1.1 • The traditional Open Client programming environment (for new customers and Sybase-heritage customers using new applications) • The Client Services Application (CSA) programming environment (only for MDI-heritage customers using their old applications) The following table provides migration information about the Open ClientConnect predecessor products. Table 1-7: Open ClientConnect predecessor Product Migration information Open Client/ Open ClientConnect replaces Open Client/Mainframe. Mainframe Note: If you still use Open Client/Mainframe at your site, you cannot customize the code pages; that functionality is available only with Open ClientConnect, releases 3.1 and later. MDI Access Open ClientConnect replaces MDI Access Server (CSAs) Server ClearConnect ClearConnect is a Windows-based ODBC driver that supports direct client-to-host access to IBM Database2 (DB2) data. ClearConnect uses Distributed Relational Database Architecture (DRDA) for connectivity and runs on the client, allowing client applications to connect to any DRDA-enabled DB2. ClearConnect accesses the following data: • IBM mainframe data residing in DB2 • LAN data residing on AS/400, DB2/NT, DB2/AIX, DB2/Solaris, and DB2/HPUX • IBM mainframe legacy data (VSAM, IDMS, ADABAS, IMS) when used with Platinum InfoHub release With ClearConnect, client applications such as Powerbuilder, Microsoft Access, Visual Basic, and other ODBC applications can directly query and update DB2 databases. ClearConnect has the following capabilities: • Allows ODBC applications and 4GL tools to access DB2-DRDA databases 1-8 Understanding Enterprise Connect
  • 33. MainframeConnect for DB2/MVS-CICS version 11.1.1 Enterprise Connect Product Overview • Supports the latest IBM DRDA database interoperability standard (DRDA Level 3) • Supports the ODBC 2.0 and 2.5 APIs • Supports both 16-bit and 32-bit Wintel clients • Provides fast, easy installation using standard ODBC administrator GUI tools ClearConnect provides a point-to-point solution for project teams and workgroups requiring access to DB2 data. As projects grow and client volume increases, ClearConnect provides an easy migration to a larger-scale solution, such as DirectConnect for MVS. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 1-9
  • 34. Enterprise Connect Processing Environment MainframeConnect for DB2/MVS-CICS version 11.1.1 Enterprise Connect Processing Environment The Enterprise Connect products enable desktop computer and workstation users to communicate with mainframes in a client/server environment. The Enterprise Connect processing environment consists of several hardware and software components, such as the following: Hardware/ Components software Hardware • One or more SQL Server or Open Server platforms • One or more platforms running DirectConnect • One or more IBM mainframes Software • Communications software from other • LU 6.2 support vendors • IBM TCP/IP support • Interlink TCP/IP support • MQ series support • CICS/MVS • IMS TM • VTAM and NCP • Database management systems on remote servers • MVS Sybase • Open ClientConnect (or Open Client/Mainframe) software • SQL Server • DirectConnect (or Net-Gateway) • Open Server • Open ServerConnect (or Open Server/Mainframe) • MainframeConnect for DB2/MVS-CICS (or OmniSQL Access Module for DB2-CICS) ® Note Not all these software products are required at your site. 1-10 Understanding Enterprise Connect
  • 35. MainframeConnect for DB2/MVS-CICS version 11.1.1 Products Used with Enterprise Connect Products Used with Enterprise Connect This section lists and briefly explains the related Sybase and IBM products. Related Sybase Products Enterprise Connect can be used with most Sybase products to connect mainframe applications with remote clients and servers. The products in Table 1-8: Related Sybase products are frequently used as clients and/or servers with the Enterprise Connect set. You need Sybase, IBM, and vendor communications documentation to configure, install, and manage Enterprise Connect products. You may need additional IBM and vendor manuals for your particular configuration. Be sure you have the necessary IBM manuals on hand before you begin to configure , as well as the Open ClientConnect and Open ServerConnect Messages and Codes guide for your mainframe products. Table 1-8: Related Sybase products Product Description SQL Server With SQL Server acting as a server, clients using Open ClientConnect can send requests to a named SQL Server through Mainframe Client Connect. SQL Server, the Sybase relational database management system (RDBMS), can act as a client or server. Networked clients can call SQL Server stored procedures that send requests to Open ServerConnect or MainframeConnect for DB2/MVS-CICS (or OmniSQL Access Module for DB2-CICS) on the mainframe. The DirectConnect administrator can configure the TRS to require all client requests to be routed through SQL Server. Note: All references to SQL Server also apply to Adaptive Server. OmniConnect OmniConnect translates Sybase SQL syntax into statements that DB2 can process. MainframeConnect for DB2-MVS/CICS applies the request from OmniConnect to DB2 and returns results. Sites that need to run the same applications without modifications against both SQL Server and DB2 can use OmniConnect as a server. Open Client Open Client is a Sybase connectivity product that provides customer client applications, third-party products, and other Sybase products with the interfaces needed to communicate with Sybase servers and Open Server applications, including Open ServerConnect, OmniSQL Access Module for DB2-CICS, MainframeConnect for DB2/MVS-CICS, DirectConnect Access Service, and DirectConnect TRS. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 1-11
  • 36. Products Used with Enterprise Connect MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 1-8: Related Sybase products (continued) Product Description Open Server Open Server provides the tools and interfaces needed to create a custom server (called an Open Server application). Open ServerConnect uses Open Server architecture to allow the mainframe to act as a server. Open ClientConnect clients can send requests to Open Server applications on the local area network (LAN) through Mainframe Client Connect, or directly through Intersystem Communication (ISC) if requests are being sent to Open ServerConnect in a separate region. Note: Open ServerConnect and Open ClientConnect are available for CICS, IMS TM, and native MVS. Replication Server® Replication Server keeps copies of data up-to-date at multiple sites so that clients can access local data instead of remote, centralized databases. Replication Agent™ Replication Agent is a functional component of the replication model that conveys updates made to primary data sources to a Replication Server. Related IBM Products Enterprise Connect uses a number of IBM mainframe software products to allow mainframes to act as clients and servers. The most important of these products are listed in Table 1-9: Related IBM products. Table 1-9: Related IBM products Product Description APPC/LU 6.2 A program-to-program communication protocol. Open (Advanced Program-to-Program ServerConnect, Open ClientConnect, Communication facility/Logical Unit Type DB2 Access Module, and MainframeConnect for 6.2.) DB2/MVS-CICS can all use APPC to communicate through DirectConnect. C/370 An application programming language. Open Client Client-Library is available for C. CICS A transaction monitor on the mainframe. Open (Customer Information Control System) ServerConnect, Open ClientConnect, and MainframeConnect for DB2/MVS-CICS are all available for CICS. DB2 (Database 2) A relational database on the mainframe that uses SQL. Enterprise Connect clients can send requests to DB2. 1-12 Understanding Enterprise Connect
  • 37. MainframeConnect for DB2/MVS-CICS version 11.1.1 Products Used with Enterprise Connect Table 1-9: Related IBM products (continued) Product Description IMS TM A transaction monitor and data communication system (Information Management System on the mainframe. Open ServerConnect, Open Transaction Manager) ClientConnect, and the OmniSQL Access Module for DB2-CICS are all available for IMS TM. OS PL/I Version II An application programming language. Open Client Client-Library and Open Server Gateway-Library are both available for PL/I. TCP/IP A communication protocol in general use. Open (Transmission Control Protocol/Internet ServerConnect, Open ClientConnect, the OmniSQL Protocol) Access Module for DB2-CICS, and MainframeConnect for DB2/MVS-CICS, can all use TCP/IP to communicate through DirectConnect. VS COBOL II An application programming language. Open Client Client-Library and Open Server Gateway-Library are both available for COBOL. VTAM A mainframe access method used with SNA. (Virtual Telecommunications Access Method) Mainframe-based Enterprise Connect products run in a VTAM environment. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 1-13
  • 38. Products Used with Enterprise Connect MainframeConnect for DB2/MVS-CICS version 11.1.1 1-14 Understanding Enterprise Connect
  • 39. 2 Understanding MainframeConnect 2. MainframeConnect is part of the Sybase Enterprise Connect product set, which consists of mainframe and non-mainframe products. MainframeConnect software provides client applications access to DB2 and other data sources on an IBM mainframe running MVS/CICS. MainframeConnect is a unified version of two previous products: • MDI Access Server for MVS-CICS Version 2.5 • OmniSQL Access Module Version 10.1 This chapter provides an overview of MainframeConnect and contains the following sections: • MainframeConnect Functionality 2-1 • MainframeConnect Communication 2-3 MainframeConnect Functionality MainframeConnect works with DirectConnect, which is a separate Sybase product that provides the communication link between a mainframe and a remote network of clients. Together, they support the features described in the following subsections. Multiple Connectivity and Protocols MainframeConnect supports multiple protocols: • SNA LU 6.2 Connectivity • TCP/IP Connectivity (for Open Server and DB2), which is supported using the CICS Sockets Interface with the IBM MVS TCP/IP product Long-Running Transactions MainframeConnect supports user-defined, long-running transactions. Because transactions can remain active after all results are sent, multiple requests can participate in the same unit of work. Therefore, you have more control over individual or group commits or rollbacks on mainframe databases. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 2-1
  • 40. MainframeConnect Functionality MainframeConnect for DB2/MVS-CICS version 11.1.1 Internationalization MainframeConnect supports the following character sets: • ascii_8, iso-1 • cp-850 • cp-437, eucjis • SJIS • dec-kanji • roman8 (for HP) • mac • cp819 (UNIX ascii iso_1) • cp500 (mainframe ebcdic iso_1) In addition, messages are provided in multiple languages. You can specify a national language, such as U.S. English, French, or German, for messages. Character Set Customization MainframeConnect provides character sets that you can customize if you want to change languages. You can create up to 99 new character sets by modifying the shipped base tables. Access to Relational and Non-Relational Data In addition to relational data support, MainframeConnect provides access to non-relational data through RSPs and RPCs. RSPs require Open ServerConnect API. For more information, see the Open ServerConnect Programmer’s Reference. RSP, PL/1, and COBAL versions of this guide are available. Dynamic SQL DB2 Data Access MainframeConnect supports the following: • Cursor events and dynamic events • Updates and inquiries against DB2 data using DB2 dynamic SQL • Dynamic access to DB2 data and CICS programs 2-2 Understanding MainframeConnect
  • 41. MainframeConnect for DB2/MVS-CICS version 11.1.1 MainframeConnect Communication Non-Truncated Columns MainframeConnect supports columns for LONG V ARCHAR and LONG V ARBINARY without truncation. In addition, truncation is not required for data returned from datatypes LONG VARCHAR and LONG V ARBINARY, if the LONG V ARCHAR is greater than 255 bytes. User Datatypes Client applications can process user datatypes that return descriptive information about DB2 columns. Exit Routines MainframeConnect provides request exit, result exit, and parse exit routines. Other Features MainframeConnect also supports the following features: • Translation between DB2 and Sybase datatypes and error codes • DB2 catalog queries • 31-digit decimals; MainframeConnect supports the DB2 extension to its decimal datatype, DECIMAL(31,31) • LONG VARCHARs (literal strings greater than 254 bytes) can be embedded in an insert or update language statement MainframeConnect Communication This section lists the products MainframeConnect communicates with and explains the communication path. Components of MainframeConnect The MainframeConnect product consists of the transaction AMD2 and uses the Host Request Library DB2 Table, both of which reside on the mainframe. ® Note AMD2 was formerly SYRT (Sybase Request Tool) or MDI. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 2-3
  • 42. MainframeConnect Communication MainframeConnect for DB2/MVS-CICS version 11.1.1 Transaction Processor AMD2 AMD2 is the default name of the CICS transaction in MainframeConnect that allows clients to submit SQL statements to DB2. ® Note A separate CICS region with AMD2 installed is required for each DB2 subsystem accessed. DirectConnect invokes AMD2 when it sends a client SQL request to the mainframe. AMD2 then submits the SQL request to DB2, using the DB2 dynamic SQL facility. AMD2 returns DB2 results and messages to DirectConnect and then terminates. However, in the case of long transactions or allocate on connect, AMD2 terminates only after the client explicitly ends the transaction. Host Request Library DB2 Table The host request library is a DB2 table for centrally storing SQL statements. This library makes the requests available to all DirectConnect users. MainframeConnect retrieves the specified SQL request from the host request library and submits the request to DB2 for processing. MainframeConnect returns the results of the request to the client application. Communication with Other Products MainframeConnect and DirectConnect handle the communications between the client application, DB2, and other products. The products discussed in the following sections comprise the major parts of the communication path from a client to DB2. They affect either the processing or the content of client requests. Other Mainframe Products MainframeConnect interacts with these mainframe products: • DB2 2-4 Understanding MainframeConnect
  • 43. MainframeConnect for DB2/MVS-CICS version 11.1.1 MainframeConnect Communication • CICS • MVS • VTAM and Network Control Program (NCP) • TCP/IP for MVS • Resource Access Control Facility (RACF), Advanced Communications Function 2 (ACF2), or TopSecret • SNA LU 6.2 DirectConnect for MVS Client application requests use DirectConnect to access MainframeConnect on the mainframe. Client application requests are initiated by Sybase and third-party, client applications. Connectivity between DirectConnect and MainframeConnect is achieved using SNA LU 6.2 or TCP/IP connectivity and the Tabular Data Stream (TDS) protocol. See the DirectConnect for MVS Connectivity Guide for more information. Client Applications Client applications send requests to DirectConnect (or to other servers for forwarding to DirectConnect). Client requests can be sent through ODBC, DB-Library, CT-Library, or Open Client applications; for example, isql, Data Workbench, APT Workbench, and front-end products from independent software vendors. DirectConnect provides the link between MainframeConnect and the clients. Thus, after MainframeConnect is installed and configured, the clients do not need to consider communication issues with MainframeConnect. Other Servers OmniConnect, SQL Server, and Replication Server are separate Sybase products that work with DirectConnect and can be optional parts of the MainframeConnect communication path. MainframeConnect Communication Path For client access to DB2 data, MainframeConnect must be installed on the mainframe and DirectConnect must be installed on a LAN MainframeConnect for DB2/MVS-CICS Install & Admin Guide 2-5
  • 44. MainframeConnect Communication MainframeConnect for DB2/MVS-CICS version 11.1.1 server. MainframeConnect and DirectConnect work together to provide DB2 data to clients as follows: 1. A client sends SQL requests to DirectConnect. 2. DirectConnect forwards the requests to the CICS transaction (AMD2) on the mainframe (using SNA or TCP/IP connectivity on the LAN server). 3. AMD2 processes the client SQL requests using the dynamic SQL capabilities of DB2. 4. AMD2 returns the DB2 result sets and messages to DirectConnect (using SNA or TCP/IP connectivity on the LAN server). 5. DirectConnect returns the results and messages to the client. See the following figure for an illustration of this process. 2-6 Understanding MainframeConnect
  • 45. MainframeConnect for DB2/MVS-CICS version 11.1.1 MainframeConnect Communication Figure 2-1: MainframeConnect communication path MainframeConnect for DB2/MVS-CICS Install & Admin Guide 2-7
  • 46. MainframeConnect Communication MainframeConnect for DB2/MVS-CICS version 11.1.1 2-8 Understanding MainframeConnect
  • 47. 3 Planning Your Installation 3. Before you install MainframeConnect, you should know what you will install, understand the installation tasks, and complete a preinstallation checklist. This chapter provides this information in the following sections: • What Can You Install with This Product? 3-1 • Installation Task Summary 3-1 • Preinstallation Checklist 3-2 What Can You Install with This Product? MainframeConnect ships with the following tapes: • The MainframeConnect tape • Open ServerConnect for CICS/MVS base tape, which contains files for LU 6.2 and TCP/IP environment connections • The optional Japanese Conversion Module tape ® Note Instructions for installing the Open ServerConnect for CICS/MVS base tape and the Japanese Conversion Module tape are in the Open ServerConnect for IBM CICS/MVS Installation and Administration Guide, which ships with MainframeConnect. Installation Task Summary The following table shows the tasks you perform to plan, install, and configure MainframeConnect. It also includes the location in this guide of specific information about each task. Table 3-1: Installation process Task Described In Review the installation tasks and complete This chapter the preinstallation checklist. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 3-1
  • 48. Preinstallation Checklist MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 3-1: Installation process (continued) Task Described In Migrate from OmniSQL Access Module Chapter 4, “Migrating from Version 10.1 or MDI Access Server for MVS- Previous Installations” CICS Version 2.3 or later. Install the Open ServerConnect for Open ServerConnect for IBM CICS/MVS base tape. CICS/MVS Installation and Administration Guide Install the MainframeConnect tape. Chapter 5, “Installing the MainframeConnect Tape” Optionally, install the Catalog Stored Chapter 6, “Installing Catalog Procedures (CSPs) for Transaction Router Stored Procedures for Service Library (TRS). Transaction Router Service” Optionally, install the Japanese Conversion Open ServerConnect for IBM Module. CICS/MVS Installation and Administration Guide Configure MainframeConnect to Chapter 7, “Configuring communicate with DirectConnect. MainframeConnect” Optionally, set up the levels of security with Open ServerConnect for IBM which you want to work and coordinate CICS/MVS Installation and them with the DirectConnect administrator. Administration Guide Preinstallation Checklist Before you install any of the MainframeConnect tapes, complete the preinstallation checklist, which instructs you to check: 1. Personnel requirements 2. System requirements 3. Special system requirements 4. Performance upgrades 5. Mainframe Access Product components 6. Space requirements 7. Connectivity 8. VTAM and NCP definitions 9. CICS configuration 3-2 Planning Your Installation
  • 49. MainframeConnect for DB2/MVS-CICS version 11.1.1 Preinstallation Checklist ® Note To determine whether any new release levels or bug fixes of vendor or Sybase products are required, call Sybase Technical Support (see “Contacting Sybase Technical Support” on page xix). In addition, you should consult the latest Release Bulletin for the current information. The following sections describe each item in the preinstallation checklist in detail. Checking the Personnel Requirements You need the following persons to install the MainframeConnect base tape. • A VTAM-knowledgeable person, with the correct authority to make system changes, who can spend a minimum of an hour during the installation. • A DB2 database administrator, with the correct authority to make system changes, who can spend a minimum of an hour during the installation. • A security administrator, who may be required if an external security product inhibits MainframeConnect installation. • A CICS system programmer, who can perform any necessary CICS programming tasks. Checking the System Requirements Verify that you have the following compatible platform and operating system components before you install MainframeConnect: • An OS/390 or MVS/ESA environment running on an IBM System/390 mainframe adequate to support CICS and DB2. • A CICS/VS or CICS/ESA system running on an IBM System/390 mainframe. • A DB2 application running on an IBM System/390 mainframe. • VTAM running on an IBM System/390 mainframe. • One of the following versions of NCP: - NCP, Version 4.5 for 3725 and parallel session support - NCP, Version 5.2 for 3745 and parallel session support MainframeConnect for DB2/MVS-CICS Install & Admin Guide 3-3
  • 50. Preinstallation Checklist MainframeConnect for DB2/MVS-CICS version 11.1.1 • For DB2 access, DSNC (an IBM transaction that provides DB2 access for CICS transactions) must be running in the CICS region. • For APPC connections, no additional host software is required. • Up-to-date vendor products. Checking Special System Requirements The following may also be required, depending on your system configuration: • If you are using a channel-attached 3174 model 11L (cluster controller) and want to use parallel sessions, the following special requirements apply: - VTAM, Version 3.4 or later. - MVS/ESA. - Appropriate applied RPQs. Contact IBM for details on this configuration. - Microcode Level “C”. - APPN LIC Feature. Contact IBM for appropriate details on this configuration. ® Note If the channel-attached control unit is not an IBM product (but is a Harris, McData, or other brand product instead), contact the appropriate vendor for any special requirements for the unit. • If your site uses IBM RACF, make sure you have the appropriate updates to support APPC. • If your site uses ACF2 or Top Secret security packages from Computer Associates, we strongly suggest that you contact the vendor before proceeding with your LU 6.2 installation (see the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS to ensure that you have the release, user modifications, and fixes necessary to support APPC processing. • If you are using ACF2 Release 5.2, you need to obtain and apply APAR UM87688 from Computer Associates. 3-4 Planning Your Installation
  • 51. MainframeConnect for DB2/MVS-CICS version 11.1.1 Preinstallation Checklist Considering Performance Upgrades On the mainframe, you should run subsystem versions that offer the best performance. You should upgrade to the latest versions of MVS and CICS. Check with IBM for the latest performance modifications. Communications can slow down when the mainframe sends large volumes of data back to the DirectConnect server. The line speed between DirectConnect and the mainframe is critical in determining the overall transaction throughput. Using SDLC If you are using Slow and moderate SDLC lines yield low-to-moderate transaction TCP/IP, skip rates. For short and simple queries, SDLC lines of 9.6K, 19.2K, and this section 56K bytes per second typically yield 2–15 concurrent transactions per second. If you are using SDLC, consider upgrading the SDLC link speed or adding more SDLC links. Using Token Ring If you are using If you need to send large volumes of data or run large numbers of SDLC, skip concurrent transactions, use a higher speed connection, such as a this section Token Ring. For example, when you transfer very large amounts of data (over 10,000 bps), install a Token Ring LAN connection, through a 3172, 3174, or 3745, to the clients and servers. Before doing this, verify that the vendor’s hardware provides this type of LAN support. RU Size For short transactions, a smaller RU size is more resourceful. When you set the RU size in the CICS Session Definition, make sure you specify the same size in the VTAM network definition for your Token Ring or in the NCP group definition for your SDLC line. For controllers such as 3174s, you must set the MAXDATA or the PU and the IFIELD or IFRAME size to be at least as large as the RUSIZE plus the number of bytes needed for headers, such as 1024 (RUSIZE) + 9. Using this example, you would set MAXDATA=1033 and IFRAME=1033. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 3-5
  • 52. Preinstallation Checklist MainframeConnect for DB2/MVS-CICS version 11.1.1 Checking the Mainframe Access Components Verify that you have the compatible mainframe access components shown in the following table before you install MainframeConnect for DB2/MVS-CICS release 11.1.1. Table 3-2: Mainframe Access components Component Release Level Open ServerConnect for CICS/MVS 3.1 or above Japanese Conversion Module 3.1 or above (which is only available upon request) DirectConnect for MVS 11.1 or above Checking the Space Requirements Verify that you have the Direct Access Storage Device (DASD) requirement before you install the MainframeConnect tape. For MainframeConnect, you need 37 tracks on a 3390 disk driver. Checking Connectivity This guide assumes the following tasks to check connectivity between the mainframe, server, and LAN are complete: 1. For the LAN connection, the server was defined and its connectivity was validated on the LAN. The LAN is up and running. 2. For the mainframe connection, the SNA LU 6.2 or TCP/IP connection to the mainframe was defined and tested. 3. For server communications, the communications on the server side were defined and configured. 4. For LAN communications, the communications on the LAN side were defined and tested. The DirectConnect for MVS Connectivity Guide contains instructions for the preceding connectivity steps. 3-6 Planning Your Installation
  • 53. MainframeConnect for DB2/MVS-CICS version 11.1.1 Preinstallation Checklist Checking the VTAM and NCP Definitions This guide assumes the appropriate definitions are included in the VTAM and NCP installations. For details, see the DirectConnect for MVS Connectivity Guide. Checking the CICS Configuration Make sure the CICS environmental values are appropriate and the connection session pairs are set up. For details, see the DirectConnect for MVS Connectivity Guide. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 3-7
  • 54. Preinstallation Checklist MainframeConnect for DB2/MVS-CICS version 11.1.1 3-8 Planning Your Installation
  • 55. 4 Migrating from Previous Installations 4. Review this chapter if you are migrating to MainframeConnect from one of the following products: • MDI Access Server for MVS-CICS Version 2.3 or later • OmniSQL Access Module for DB2-CICS Version 10.1 This chapter contains the following sections, which include information about migrating from either of these products: • Understanding Migration Considerations with MainframeConnect 4-1 • Preparing to Upgrade to MainframeConnect 4-2 Understanding Migration Considerations with MainframeConnect If you upgrade from MDI Access Server for MVS-CICS or OmniSQL Access Module for DB2-CICS, you will find the following differences in MainframeConnect. New Default Transaction Name The default transaction name for MainframeConnect for DB2/MVS- CICS release 11.1.1 is AMD2, which replaces the following names: • MDI for MDI Access Server for MVS-CICS • SYRT for OmniSQL Access Module for DB2-CICS. CSAs and RSPs If you have existing CSAs or RSPs, you must link-edit them with the new program stubs distributed with Open ClientConnect or Open ServerConnect. See the following guides for more information: • Open ClientConnect Programmer’s Reference for Client Services Applications • Open ServerConnect Programmer’s Reference for Remote Stored Procedures MainframeConnect for DB2/MVS-CICS Install & Admin Guide 4-1
  • 56. Preparing to Upgrade to MainframeConnect MainframeConnect for DB2/MVS-CICS version 11.1.1 Preparing to Upgrade to MainframeConnect If your site has a prior release of OmniSQL Access Module for DB2- CICS or MDI Access Server for MVS-CICS, consider removing the old groups and deleting old library members. ® Note OmniSQL Access Module for DB2-CICS or MDI Access Server for MVS- CICS can run in the same CICS region. You may also want to add customized messages to the AMD2 message module AMD2CAMX. See Chapter 8, “Customizing MainframeConnect Messages,” for more information. ® Note The documentation for each MainframeConnect component is listed in “Related Documents” on page xvii. Removing a Prior Product The Sybase resources defined to CICS during MainframeConnect installation are contained in a group. If you want to remove a prior product, you can use CEDA (the IBM-supplied transaction for performing resource definition online) to delete the group, and then remove the group from your list. Keep the following in mind: • If you install MainframeConnect on top of an existing product, you do not need to delete groups from a previous release prior to installation. • If previous versions of Open Client/Open Server are installed, you must delete these prior versions before you install the new versions. For more information, see the following guides: - Open ClientConnect Installation and Administration Guide for IBM CICS/MVS - Open ServerConnect Installation and Administration for IBM CICS/MVS 4-2 Migrating from Previous Installations
  • 57. MainframeConnect for DB2/MVS-CICS version 11.1.1 Preparing to Upgrade to MainframeConnect The following table lists group names and corresponding product names from this release and prior releases. Table 4-1: Sybase resources To Remove this Product Release Delete this Group Open Server for CICS-API 2.x SYAPGRP Open ServerConnect-API 3.x Open Gateway for DB2 1.0, 2.0 SYCAGRP Open Client for CICS 1.0, 2.x SYCTGRP Open ClientConnect 2.0.x Japanese Conversion Module 2.1, 3.x SYKAGRP Open Server for CICS 1.0, 2.x SYOSGRP Open ServerConnect for CICS 3.x SQL Gateway for DB2 1.0, 2.0 SYRTGRP Open ServerConnect for TCP/IP 3.x SYTSGRP Assigning Library Names The shipped library names are unique for this release. If you upgrade, determine whether you want to use the existing library names at your site. Then, do one of the following: • To keep old names, back up all files from the prior release of the product. If you plan to continue to use the old Sybase library names, delete all members after backing them up, and then install the new members with the new version using the new names. • To use new names, you do not have to remove previous releases from your Sybase libraries because the default names shipped with this release are unique. However, you can change the names to follow naming standards at your site as long as you avoid using any existing names. Preserving Customized Messages on AMD2CAMX Customized messages are a part of the AMD2 message module, AMD2CAMX. Previous mainframe access product releases supplied messages through DB2 Version 1.3. Depending on the DB2 version at your site, consider the following: MainframeConnect for DB2/MVS-CICS Install & Admin Guide 4-3
  • 58. Preparing to Upgrade to MainframeConnect MainframeConnect for DB2/MVS-CICS version 11.1.1 • If your site has not added customized messages (other than updating those supplied as standard for DB2 Version 3.1), you can install MainframeConnect release 11.1.1 without first preserving your customized messages. The MainframeConnect message table includes messages supplied through DB2 Version 4.1. Customized messages are always added to the messages supplied by MainframeConnect; they usually do not replace them. • If your site added customized messages that are not just DB2 standard messages, preserve them now if you do not want the installation process to overwrite them. You can then add your customized messages to AMD2CAMX message table after installing this release. For more information, see “Adding Entries for New SQLCODEs” in Chapter 8, “Customizing MainframeConnect Messages.” After you complete and test the upgrade, replace the old LOADLIB name with the new one in the DFHRPL concatenation, which is in the CICS start-up procedure for that CICS region. These installation steps are described in the following chapters: • Base tape installation chapter in the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS. • Step 5 in “Installation Steps” on page 5-1 in Chapter 5, “Installing the MainframeConnect Tape.” 4-4 Migrating from Previous Installations
  • 59. Installing
  • 60. 5 Installing the MainframeConnect Tape 5. This chapter contains instructions for installing the MainframeConnect tape. x WARNING! You must install the Open ServerConnect for CICS/MVS base tape before you install MainframeConnect. See the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS for instructions. The sections in this chapter are: • Installation Steps 5-1 • Post-Installation Steps 5-4 • Contents of the MainframeConnect Library 5-6 • What’s Next? 5-9 Installation Steps A CICS system programmer, a DB2 database administrator, and a DirectConnect administrator are required to successfully install the MainframeConnect tape. Make sure that these persons are prepared to perform their respective tasks. This is a margin Before you begin this installation, read all the steps. To help you caption identify who is responsible for which steps, margin captions indicate the type of system programmer or administrator who performs the steps that follow. CICS System 1. Retrieve the JCL that copies the MainframeConnect libraries Programmer from the tape by entering the following JCL and submitting the job. You can use the default values or change them to be specific MainframeConnect for DB2/MVS-CICS Install & Admin Guide 5-1
  • 61. Installation Steps MainframeConnect for DB2/MVS-CICS version 11.1.1 to your site. A reminder to verify the defaults appears on the right. //JOBNAME JOB (ACCTNR,ACCTINFO),‘UNLOAD MC’ <== VERIFY //* //* Retrieve the JCL that copies the Sybase libraries from //* the installation tape, MFC111, to disk. //* //GENER EXEC PGM=IEBGENER //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT1 DD DSN=SYBASE.AMD2111.TAPEJCL, // DISP=(OLD,KEEP), // UNIT=3480, <== VERIFY // LABEL=(1,SL),VOL=SER=MFC111 //SYSUT2 DD DSN=SYBASE.AMD2111.CICSDB2.TAPEJCL, <== VERIFY // UNIT=SYSDA,VOL=SER=SYB001, <== VERIFY // DISP=(,CATLG,DELETE), // SPACE=(3120,(10,3)) 2. Retrieve MainframeConnect from the tape into DASD by editing and submitting the JCL from the TAPEJCL file you unloaded in step 1. Editing instructions are in the JCL. 3. If the VSAM log files are not defined, define the AMD2 transaction VSAM logfiles by editing and submitting JCL member AMD2LOG. x WARNING! If you change the logfile default names in step 3, be sure you also change the default names in step 4. 4. If you use RDO (Resource Definition Online) to define resources at your site, edit and submit CTRL member AMD2RDO3 (for CICS Version 3) or AMD2RDO (for CICS Version 4 or later) according to the instructions contained in the CTRL library. This job defines all Sybase resources to CICS through RDO using the DFHCSDUB utility. If you do not use RDO to define resources, create the appropriate FCT, PCT, and PPT definitions based on the information in the member AMD2RDO or AMD2RDO3. 5. Edit your CICS start-up procedure, including the MainframeConnect LOADLIB library in the DFHRPL 5-2 Installing the MainframeConnect Tape
  • 62. MainframeConnect for DB2/MVS-CICS version 11.1.1 Installation Steps concatenation. Coordinate with the DB2 database administrator (step 6) before recycling the CICS region (step 12). ® Note If you plan to install the MainframeConnect Catalog Stored Procedures (CSPs) for use with TRS, use the installation steps in Chapter 6, ‘‘Installing Catalog Stored Procedures for Transaction Router Service.’’ ® Note The following steps pertain to DB2 database administration. If you change default names, be sure the new names conform to your site’s conventions, particularly for plan names and authorizations. DB2 Database 6. Include AMD2HRCT macro entries from the CTRL library in your Administrator RCT table, generate the table, and stop and start DSNC to activate these changes ® Note If you change the default plan names in this step, be sure to use the new names in step 7. 7. Create a collection ID by issuing the following SQL to DB2 in a utility, such as TSO batch or SPUFI: GRANT PACKADM ON COLLECTION SYAMD2 TO userid 8. Bind the application plan by running job BINDPLAN in the JCL library, adding a CACHE SIZE of 0 for performance. ® Note The asterisk and period (*.) before SYAMD2.* in the PKLIST parameter of the BINDPLAN job may not be required. 9. Bind the AMD2 package by running job BINDPKG in the JCL library. 10. Create a permanent VSAM configuration dataset by modifying and running job AMD2CFG in the JCL library. CICS System 11. Optional. Alter the message table using AMD2CAMX in the Programmer SOURCE library as a prototype. Then, assemble and link the message table using AMD2CAMX from the JCL library. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 5-3
  • 63. Post-Installation Steps MainframeConnect for DB2/MVS-CICS version 11.1.1 For details on changing the message table, see Chapter 8, “Customizing MainframeConnect Messages.” 12. If necessary, recycle your CICS region. Post-Installation Steps After you install MainframeConnect, the DB2 data administrator should perform the post-installation tasks listed in this chapter. These tasks includes: • Authorizing users for the application plan • Authorizing users for DB2 packages • Authorizing users for system tables • Verifying your installation Authorizing Users for the Application Plan All users who will use MainframeConnect to access DB2 must be authorized to execute the DB2 application plan. This is the application plan you created containing all your DB2 packages. You can grant the privilege to all DB2 users or to specific users. To issue the GRANT statement, you can use either of the following forms: GRANT EXECUTE ON PLAN planname TO userid GRANT EXECUTE ON PLAN planname TO PUBLIC where planname is the name of the DB2 application plan. Authorizing Users for DB2 Packages You must grant EXECUTE authority on the packages you created. Use one of the following forms: GRANT EXECUTE ON PACKAGE AMD2.* TO userid GRANT EXECUTE ON PACKAGE AMD2.AMD2DB2 TO userid GRANT EXECUTE ON PACKAGE AMD2.* TO PUBLIC GRANT EXECUTE ON PACKAGE AMD2.AMD2DB2 TO PUBLIC 5-4 Installing the MainframeConnect Tape
  • 64. MainframeConnect for DB2/MVS-CICS version 11.1.1 Post-Installation Steps Authorizing Users for System Tables If the DirectConnect for MVS users need to access catalog information from system tables and you are using catalog stored procedures (CSPs), then you must authorize users to select from the following tables: • SYSIBM.SYSCOLAUTH • SYSIBM.SYSCOLUMNS • SYSIBM.SYSDATABASE • SYSIBM.FOREIGNKEYS • SYSIBM.SYSINDEXES • SYSIBM.SYSKEYS • SYSIBM.SYSRELS • SYSIBM.SYSSYNONYMS • SYSIBM.SYSTABAUTH • SYSIBM.SYSTABLES Some front-end applications access these system tables directly. See the application documentation for more information. Additionally, all users accessing DB2 must be granted the appropriate authorizations on the tables they will use. Verifying Your Installation Before you configure MainframeConnect, verify that the link between MainframeConnect and DB2 is functioning correctly by accessing MainframeConnect. To do this, sign on to CICS, clear the screen, and enter: AMD2 You should receive a message similar to the following: MainframeConnect for DB2/MVS-CICS/11.1.1 (CRS 50) DB2 test successful If AMD2 cannot access DB2, a message appears showing the DB2 SQLCODE; for example: MainframeConnect for DB2/MVS-CICS/11.1.1 (CRS 50) DB2 Error was detected the SQL code is -805 See your DB2 manuals for definitions of SQL codes. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 5-5
  • 65. Contents of the MainframeConnect Library MainframeConnect for DB2/MVS-CICS version 11.1.1 Contents of the MainframeConnect Library Tables 5-1 through 5-7 describe the contents of the libraries you load from the MainframeConnect tape. Step numbers that appear in parentheses indicate steps in this chapter in which members from a particular library are used. COPY Library The COPY library contains the COBOL copybook. Table 5-1: COPY library Member Description AMD2CCPX COBOL copybook for the parse exit routine CTRL Library The CTRL library contains macro definitions for files, transactions, programs, and plans for AMD2 to CICS. It also contains SPUFI input statements (step 4 in “Installation Steps” on page 5-1 and step 6 in “Installation Steps” on page 5-1). Table 5-2: CTRL library Member Description AMD2HRCT CICS macro definitions for the AMD2 plans (if you change the plan names, you must edit this member) AMD2RDO RDO definitions for CICS Version 4.x AMD2RDO3 RDO definitions for CICS Version 3.x CREATPKG DB2 statement for creating a collection ID HOSTLIB Script for creating the host resident request library SPPROC Script for creating the sp_proc and sp_proc_columns tables for the corresponding CSPs 5-6 Installing the MainframeConnect Tape
  • 66. MainframeConnect for DB2/MVS-CICS version 11.1.1 Contents of the MainframeConnect Library DBRM Library The DBRM library contains member AMD2DB2, which the job BINDPLAN in the JCL library binds into a package in DB2. Table 5-3: DBRM library Member Description AMD2DB2 DBRMS for AMD2 JCL Library The JCL library contains JCL for performing various functions while installing the MainframeConnect tape (step 3 on “Installation Steps” on page 5-1 and steps 8, 9, and 10 in “Installation Steps” on page 5-1). Table 5-4: JCL library Member Description AMD2CFG JCL for defining the configuration file AMD2CAMX JCL to assemble the AMD2 message table AMD2LOG JCL to define the AMD2 log files AMD2PXIT JCL to compile and link AMD2CCPX, found in the SOURCE library BINDPKG JCL for binding packages BINDPLAN JCL for binding plans CSDLOAD JCL for loading the RDO definitions TRSJCL JCL for loading the TRS files from the tape LOADLIB Library The LOADLIB library contains pregenerated tables and programs for error messages. Table 5-5: LOADLIB library Member Description AMD2ACE Required for pre-CICS 3.3 for group ID support MainframeConnect for DB2/MVS-CICS Install & Admin Guide 5-7
  • 67. Contents of the MainframeConnect Library MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 5-5: LOADLIB library Member Description AMD2ACF2 ACF2 group ID support AMD2CAMX AMD2 message table AMD2CFG Configuration program AMD2CHAB Abend handler AMD2CICS AMD2 program AMD2DSN Error handler for AMD2 AMD2M01 AMCF configuration map AMD2RACF RACF group ID support AMD2SPM Map for SPTEST AMD2SPT SPTEST program for testing RSPs AMD2TOP Top Secret group ID support MACLIB Library The MACLIB library contains macros for working with message text and SQL codes. Table 5-6: MACLIB library Member Description EXITAREA Macro for request and result exits SYRTMAMT AMD2 macro for message text SYRTMAMX AMD2 macro for message attributes and SQL codes 5-8 Installing the MainframeConnect Tape
  • 68. MainframeConnect for DB2/MVS-CICS version 11.1.1 What’s Next? SOURCE Library The SOURCE library contains a sample COBOL program and the assembler source for the AMD2 message table (step 11 in “Installation Steps” on page 5-1). Table 5-7: SOURCE library Member Description AMD2CAMX Assembler source for AMD2 message table AMD2PXIT Sample COBOL program using the AMD2 parse exit What’s Next? If you need to install the CSPs for use with TRS, proceed to Chapter 6, ‘‘Installing Catalog Stored Procedures for Transaction Router Service.’’ If you need to install the Japanese Conversion Module, proceed to the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS. If you are ready to configure MainframeConnect, proceed to Chapter 7, ‘‘Configuring MainframeConnect.’’ MainframeConnect for DB2/MVS-CICS Install & Admin Guide 5-9
  • 69. What’s Next? MainframeConnect for DB2/MVS-CICS version 11.1.1 5-10 Installing the MainframeConnect Tape
  • 70. 6 Installing Catalog Stored Procedures for Transaction Router Service 6. If you are not Complete the steps in this chapter only if you plan to use the using TRS, skip MainframeConnect CSPs for use with TRS. The MainframeConnect to the next installation tape contains Sybase-defined tables that store requested chapter CSP information that is not available in the DB2 catalog. This chapter contains the following sections: • Installation Steps 6-1 • Contents of the MainframeConnect TRS Library 6-3 Installation Steps A CICS systems programmer, a DB2 database administrator, and a DirectConnect administrator are required to successfully install the TRS CSPs from the MainframeConnect tape. Make sure that these persons are prepared to perform their respective tasks. This is a margin Before you begin this installation, read all the steps. To help you caption identify who is responsible for which steps, margin captions indicate the type of systems programmer or administrator who performs the steps that follow. CICS System 1. Retrieve the TRS CSP libraries from the tape onto DASD by Programmer editing and submitting the TRSJCL file from the JCL you unloaded in step 1 in “Installation Steps” on page 5-1. Editing instructions are in the JCL. 2. If you use RDO (Resource Definition Online) to define resources at your site, edit and submit TRSJCL member, TRSCSD, in the SYBASE.AMD2111.CICSDB2.TRS.JCL library. This job defines all TRS resources to CICS through RDO using the DFHCSDUP utility. If you do not use RDO to define resources, create the appropriate FCT, PCT, and PPT definitions based on the information in the member TRSCSD in the TRSCTRL library. 3. Edit your CICS start-up procedure, including the MainframeConnect TRS.LOADLIB library in the DFHRPL concatenation. Coordinate with the DB2 database administrator (step 4) before recycling the CICS region (step 8). MainframeConnect for DB2/MVS-CICS Install & Admin Guide 6-1
  • 71. Installation Steps MainframeConnect for DB2/MVS-CICS version 11.1.1 ® Note The following steps pertain to DB2 database administration. If you change default names, be sure the new names conform to your site’s conventions, particularly for plan names and authorizations. DB2 Database 4. Include TRSRCT macro entries from the TRS.CTRL library in your Administrator RCT table, generate the table, and stop and start DSNC to activate these changes. ® Note If you change the default plan names in this step, be sure to use the new names in step 7. 5. Use member TRSDROP in the TRS.CTRL library as input to SPUFI to drop the tables and views (which you create in the next step). 6. Create tables and views for the CSPs as input to SPUFI using member TRSCREAT or TRSCREA2 in the TRS.CTRL library. The following helps you decide the member to use: - TRSCREAT checks whether the current user has some privilege on a requested object using the current sqlid. If the current sqlid does not have permissions, granted either explicitly or to PUBLIC, then the CSPs do not return information. - TRSCREA2 enables faster CSP processing because it does not check that the current user has some privilege on a requested object. However, the implications are: a) Anyone who can execute the CSP can obtain information about all DB2 objects, even if that user does not have privileges on those objects. b) accessible_table in sp_server_info is ineffective. c) The default owner names apply. For example, if you omit table owner, the default is still the current sqlid. If you find it necessary to rerun TRSCREAT or TRSCREA2, use TRSDROP first. 7. Bind the application plan by running job TRSBIND in the JCL library, adding a CACHE SIZE of 0 for performance. CICS System 8. If necessary, recycle your CICS region. Programmer 6-2 Installing Catalog Stored Procedures for Transaction Router Service
  • 72. MainframeConnect for DB2/MVS-CICS version 11.1.1 Contents of the MainframeConnect TRS Library DirectConnect 9. To test the installation on the LAN, from TRS, execute CSPs. For Administrator more information, see the DirectConnect Transaction Router Service User’s Guide. Contents of the MainframeConnect TRS Library Tables 6-1 through 6-4 describe the contents of the TRS libraries you load from the MainframeConnect tape. Step numbers that appear in parentheses indicate steps in this chapter in which members from a particular library are used. TRS.CTRL Library The TRS.CTRL library contains macro definitions for files, transactions, programs, and plans for TRS to CICS. It also contains SPUFI input statements (steps 4, 5, and 6 on “Installation Steps” on page 6-1). Table 6-1: TRSCTRL library Member Function TRSCREAT For sites that require restricted access to the DB2 catalog, SPUFI input statements that create the views and tables that the CSP uses. If you do not require this restriction, use TRSCREA2. TRSCREA2 For sites that do not require restricted access to the DB2 catalog, SPUFI input statements to create the views and tables the that CSP program uses. If you do require restricted access, use TRSCREAT. TRSCSD The CSD data for the TRSCSD job in TRSJCL. TRSDROP SPUFI input statements to drop the tables and views created in member TRSCREAT or TRSCREA2. TRSGRANT SPUFI input statements to grant execute authority to CSPs, which use SYB1PLAN. If you change the plan names, you must edit this member. TRSRCT The CICS macro definitions for the CSP and AMD2 plans. If you change the plan names, you must edit this member. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 6-3
  • 73. Contents of the MainframeConnect TRS Library MainframeConnect for DB2/MVS-CICS version 11.1.1 TRS.DBRM Library The DBRM library contains members that are bound into SYB1PLAN, which the job TRSBIND in the TRS.JCL library (BINDTRS member in library DWM.AMD2.V043.CNTL) binds into a package in step 5 in “Installation Steps” on page 6-1. Table 6-2: TRS.DBRM library Member Function SYBACO00 A DB2 CSP DBRM SYBACO01 A DB2 CSP DBRM SYBACP00 A DB2 CSP DBRM SYBADB00 A DB2 CSP DBRM SYBADT00 A DB2 CSP DBRM SYBAFK00 A DB2 CSP DBRM SYBAGNAM A DB2 CSP DBRM SYBAPK00 A DB2 CSP DBRM SYBASC00 A DB2 CSP DBRM SYBASI00 A DB2 CSP DBRM SYBASL00 A DB2 CSP DBRM SYBASP00 A DB2 CSP DBRM SYBAST00 A DB2 CSP DBRM SYBATB00 A DB2 CSP DBRM SYBATB01 A DB2 CSP DBRM SYBATB02 A DB2 CSP DBRM SYBATP00 A DB2 CSP DBRM 6-4 Installing Catalog Stored Procedures for Transaction Router Service
  • 74. MainframeConnect for DB2/MVS-CICS version 11.1.1 What’s Next? TRS.JCL Library The TRSJCL library contains JCL for performing various functions while installing the MainframeConnect tape (step 2 in “Installation Steps” on page 6-1). Table 6-3: TRS.JCL library Member Function TRSBIND JCL to bind the CSP and AMD2 plans TRSCSD JCL to load the CSD with the RDO definitions TRS.LOAD Library The TRS.LOAD library contains pregenerated tables and programs for error messages (step 3 in “Installation Steps” on page 6-1). Table 6-4: TRS.LOAD library Member Function SYBCAPAB The sp_capabilities CSP program SYBTHRED The sp_thread_props CSP program SYCACERR The error handler for CSPs SYCACPGM The CSP program What’s Next? If you need to install the Japanese Conversion Model, proceed to the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS. If you are ready to configure MainframeConnect, proceed to Chapter 7, ‘‘Configuring MainframeConnect.’’ MainframeConnect for DB2/MVS-CICS Install & Admin Guide 6-5
  • 75. What’s Next? MainframeConnect for DB2/MVS-CICS version 11.1.1 6-6 Installing Catalog Stored Procedures for Transaction Router Service
  • 76. Configuring & Customizing
  • 77. 7 Configuring MainframeConnect 7. After you install the MainframeConnect tapes and complete the post-installation tasks, you are ready to configure MainframeConnect for your site. This chapter summarizes the changes you make to enable communication between MainframeConnect and DirectConnect. The sections in this chapter are: • Changing the MainframeConnect Configuration 7-1 • Understanding the Configuration Properties 7-3 • What’s Next? 7-7 Changing the MainframeConnect Configuration Use the MainframeConnect Configuration Tran ID Selection screen and the MainframeConnect Configuration screens to alter the MainframeConnect configuration settings, as necessary. The settings are automatically saved in the configuration dataset. ® Note When you change configuration properties in the MainframeConnect Configuration screen, the new values remain in effect until they are changed again. To change the MainframeConnect configuration settings, follow these steps: 1. From a 3270 screen, sign on to CICS, clear the screen, and enter the following command: AMCF The MainframeConnect Configuration Tran ID Selection screen appears as shown in Figure 7-1. This screen enables you to select the transaction ID for which you want to change the configuration or it begins the process of configuring a new transaction ID. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 7-1
  • 78. Changing the MainframeConnect Configuration MainframeConnect for DB2/MVS-CICS version 11.1.1 Figure 7-1: MainframeConnect Configuration Tran ID Selection screen ® Note The first time the previous screen appears, no Profile Name entries appear. 2. Either select the transaction ID from the list and press Enter, or press F4 to add a new transaction ID. The MainframeConnect Configuration screen appears as shown in Figure 7-2: 7-2 Configuring MainframeConnect
  • 79. MainframeConnect for DB2/MVS-CICS version 11.1.1 Understanding the Configuration Properties Figure 7-2: MainframeConnect Configuration screen 3. Change the settings to the values you prefer (as explained in “Understanding the Configuration Properties”), and press Enter. ® Note When you add a new transaction ID, the Transaction ID field is blank. You must enter a 4-character transaction ID in the Transaction ID box. Understanding the Configuration Properties This section describes the configuration properties you can set in the MainframeConnect Configuration screen. Transaction ID The Transaction ID is the tran id that you selected in the MainframeConnect Configuration Tran ID Selection screen in step 1 MainframeConnect for DB2/MVS-CICS Install & Admin Guide 7-3
  • 80. Understanding the Configuration Properties MainframeConnect for DB2/MVS-CICS version 11.1.1 or, if you are adding a transaction ID, it is blank so that you can fill it in. Request exit name The Request exit name specifies the name of the request validation exit program. The name can contain up to eight characters. If a request validation exit program does not exist, specify NONE (the default). For more information, see “Request/Result Validation Exits” in Chapter 9, “User Exits.” Result exit name The Result exit name specifies the name of the result validation exit program. The name can contain up to eight characters. If a result validation exit program does not exist, specify NONE (the default). For more information, see “Request/Result Validation Exits” in Chapter 9, “User Exits.” Parse exit name The Parse exit name identifies the CICS program to be linked to from AMD2 as a parse exit routine. The name can contain up to eight characters. If a parse exit routine does not exist, specify NONE (the default). For more information, see “Parse Exit Routine” in Chapter 9, “User Exits.” Group ID exit name The Group ID exit name is used by CSPs to supply them with all of the user’s group IDs. The CSPs then reflect the true authorizations of the user. If you are using the RACF, ACF2, or Top Secret security packages (see the Open ServerConnect for IBM CICS/MVS Installation and Administration Guide for information about security), use one of the supplied exits. If you are not using one of these security 7-4 Configuring MainframeConnect
  • 81. MainframeConnect for DB2/MVS-CICS version 11.1.1 Understanding the Configuration Properties packages, you can write an exit program to build a list of group IDs as input to CSPs. We provide the following Group ID exit names for RACF, Top Secret, and ACF2: • AMD2RACF for RACF • AMD2TS for Top Secret • AMD2ACF2 for ACF2 In addition, you can specify either the name of a user-written exit or NONE (the default). For information about building an exit program, see “Getting Ready to Code Your Routine” in Chapter 9, “User Exits.” Host request library ID The Host request library ID specifies the qualifier used for the AMD2- HOSTLIB table. The qualifier name can contain up to 25 characters. The default is SYBASE. Temp storage queue type This option indicates the temporary storage queues to be used for results being sent to the client. Specify one of the settings shown in the following table. Table 7-1: Types of temporary storage queues Type of Setting MainframeConnect for DB2 Action and Note Storage MAIN Main Writes all results to main temporary storage before sending them to the client. After the result is sent, temporary storage queues are deleted unless the mainframe debug option is set on the LAN using the LAN set command. AUX Auxiliary See the action and notes for the MAIN setting, except that the auxiliary temporary storage is used. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 7-5
  • 82. Understanding the Configuration Properties MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 7-1: Types of temporary storage queues (continued) Type of Setting MainframeConnect for DB2 Action and Note Storage NONE None Sends results to the client without writing them to (default) temporary storage. This decreases the result wait Note: and the overall transmission time, especially for Temporary large transfer operations. This setting also saves storage is temporary storage space, which would be needed only used for results. for data going to a This setting has the following disadvantages: client. • If a processing error occurs, data has already been sent to the client. • This setting cannot be used with a result exit. • When accessing DB2, DB2 threads and locals can be held longer because they are allocated for the time required to transmit the results over the APPC link, rather than the time required to write the results to temporary storage. Estimating Temporary Storage The amount of temporary storage required is determined by the size of the result set to be returned. For example, if 150,000 rows of 1200 bytes are to be returned, 180,000,000 bytes of temporary storage are required to hold the result set. • If Temp storage queue type is set to MAIN, this storage must be available in main memory. • If Temp storage queue type is set to AUX, this storage must be available on DASD. Determining Main Memory Storage In addition, CICS keeps an 8-byte temporary storage ID in main memory for each temporary storage record written to either main memory or DASD (auxiliary storage). Use the following algorithm to determine the number of bytes of main memory storage you need: • The block size divided by the record size equals the number of records per block. • The number of records divided by the number of records per block equals the number of blocks written to temporary storage. 7-6 Configuring MainframeConnect
  • 83. MainframeConnect for DB2/MVS-CICS version 11.1.1 What’s Next? • The number of blocks written to temporary storage multiplied by the 8-byte storage ID equals the number of bytes of main storage. For example: 1. 4096 bytes (block size) divided by 200 bytes (record size) equals 20 records per block. 2. 150,000 records divided by 20 records per block equals 7500 blocks written to temporary storage. 3. 7500 blocks written to temporary storage multiplied by 8 bytes equals 60,000 bytes of main storage. The amount of temporary storage required for each concurrent use can be determined by the following formula: # rows * size of each row (# bytes for results - main/aux) + # bytes of main storage (determined in algorithm above) ______________________________ # bytes required for each user For example, if multiple users request 150,000 rows concurrently, then temporary storage and main memory requirements must be multiplied by the number of concurrent users. DateTime results type The DateTime results type option specifies the format that MainframeConnect uses to return DB2 timestamps, time, and date result columns to TRS only. Two values are valid: • DB2 (the default) returns timestamps in the standard DB2 timestamp format of YYYY-MM-DD-HH.MM.SS.ssssss, where YYYY is the year, MM is the month, DD is the day, HH is the hour, MM is the minute, SS.ssssss is the number of seconds. For example, a DB2 value might return 1996-12-31-11.42.22.123456. • TRO returns timestamps in a format that is compatible with OmniConnect communication with DirectConnect Transaction Router Service (or Net-Gateway Version 3.0.1) using OmniConnect’s Access Server Class. TRO format is YYYYMMDD HH:MM:SS:ss, where the abbreviations are similar to the DB2 abbreviations. Using the example from the DB2 value, the TRO value returns 19961231 11:42:22:12. What’s Next? You have finished installing and configuring MainframeConnect. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 7-7
  • 84. What’s Next? MainframeConnect for DB2/MVS-CICS version 11.1.1 If you want to change the message table that was installed with MainframeConnect, see Chapter 8, “Customizing MainframeConnect Messages.” If you want to read more information about the request and result exits and the parse exit routine, see Chapter 9, “User Exits.” 7-8 Configuring MainframeConnect
  • 85. 8 Customizing MainframeConnect Messages 8. The AMD2 message table in MainframeConnect determines the messages returned to the client application. You can modify the AMD2 message table to customize messages using single-byte character sets (SBCSs) for your site or to accommodate new SQLCODEs generated by updated versions of DB2. ® Note You cannot customize Japanese or other double-byte character set (DBCS) languages, which are handled by the Japanese Conversion Module. For more information, see the installation chapter for the Japanese Conversion Module in the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS. This chapter describes the AMD2 message table and explains how to make changes and additions to the existing messages. It includes the following sections: • Understanding the AMD2 Message Table 8-1 • Changing the AMD2 Message Table 8-7 • Coding AMD2 Message Table Changes 8-11 Understanding the AMD2 Message Table The AMD2 message table consists of two separate tables that share a common property: the message number. The tables function together to return messages to the client. • The translate table associates DB2 SQLCODEs with message numbers and sets the attributes of errors. You can edit the translate table to add messages or to change their attributes. (Attributes include the message number, the error severity, and so on.) As shipped, the AMD2 message table contains entries for SQLCODEs returned by version 3.1 of DB2. • The text table associates message numbers with message text. You can edit the text table to change the text of messages. You can also expand it to provide message text in additional languages. Message text for U.S. English, German, and French is provided with the product. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 8-1
  • 86. Understanding the AMD2 Message Table MainframeConnect for DB2/MVS-CICS version 11.1.1 The AMD2 message table is generated during installation as one module, AMD2CAMX, which contains all the AMD2 messages and message attributes. AMD2CAMX is built with two macros, SYRTMAMX and SYRTMAMT, and it is composed of two CSECTS, SYRTMAMX and SYRTMAMT. The following table shows the members of the translate and text tables. Table 8-1: Message table members Message Table LOAD Module MACRO Library SOURCE Library Translate table AMD2CAMX SYRTMAMX AMD2CAMX Text table AMD2CAMX SYRTMAMT AMD2CAMX Translate Table The translate table is the first table used in processing AMD2 messages. When DB2 returns a SQLCODE, AMD2 searches the translate table by the SQLCODE to determine the resulting output message number (MSGNR) and other attributes associated with the SQLCODE. For non-DB2 errors, AMD2 searches the translate table by MSGNR to determine the other message attributes associated with the error. Example of Translate Table Source Code The editable SOURCE library member (AMD2CAMX) of the translate table contains a series of SYRTMAMX macro entries, such as those shown in the following example: SYRTMAMX TYPE=ENTRY, * SQLCODE=+802, * MSGNR=30001, * LEVEL=11, * STATEC=22, * STATESC=3, * LOG=N, * SQLFATAL=N * 8-2 Customizing MainframeConnect Messages
  • 87. MainframeConnect for DB2/MVS-CICS version 11.1.1 Understanding the AMD2 Message Table SYRTMAMX TYPE=ENTRY, * SQLCODE=-007, * MSGNR=102, * LEVEL=11, * STATEC=31, * STATESC=503, * LOG=N, * SQLFATAL=N Translate Table Properties Each SYRTMAMX macro entry in the translate table consists of the following DB2 error message properties. TYPE The TYPE property indicates whether the SYRTMAMX macro entry is the initial (INITIAL) or final (FINAL) entry in the translate table, or is one of the entries in between (ENTRY). Therefore, TYPE=INITIAL occurs once at the beginning of the translate table; TYPE=FINAL occurs once at the end of the table. Examples of the TYPE=INITIAL and TYPE=FINAL are shown as follows: SYRTMAMX TYPE=INITIAL ... (additional entries not shown) SYRTMAMX TYPE=FINAL x WARNING! Do not change the INITIAL or FINAL value. SQLCODE The SQLCODE property contains the SQLCODE, a numeric status indicator returned by DB2. For messages that DB2 does not generate, such as internal error messages that AMD2 generates, this value is always 0. This property contains three digits and a plus (+) or minus (-) sign. MSGNR The text table uses the message number to identify the appropriate message to send to the client. It represents a single SQLCODE or a group of SQLCODEs about similar situations. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 8-3
  • 88. Understanding the AMD2 Message Table MainframeConnect for DB2/MVS-CICS version 11.1.1 x WARNING! Do not change the number of non-DB2 messages (those with SQLCODE equal to 0 and MSGNR greater than or equal to 32000). LEVEL The LEVEL property indicates the severity of the error. It corresponds to the following SQL Server severity levels: 01–10 Status information 11–16 Client application errors 17–18 Non-fatal software or hardware errors 19–24 Fatal system errors STATEC The STATEC class property, a 2-byte field, provides more information about DB2 errors. For non-DB2 errors, the value is 0. STATESC The STATESC subclass property, a 3-byte field, provides more information about DB2 errors. For non-DB2 errors, the value is 0. LOG The LOG (logging instruction) property indicates whether to log the error in the AMD2LOG file. We recommend logging serious errors. To turn logging on, specify the Y value. To turn logging off, specify the N value. SQLFATAL The SQLFATAL (fatal error) property indicates whether AMD2 accepts more client requests in the current invocation. Y means that yes, the error is fatal, and therefore, no further requests are accepted from the current client connection. N means that no, the error is not fatal and requests are processed as usual. Text Table The text table is the part of the AMD2 message table that determines the text of a message by connecting message text with message numbers. For each language, there is a message number and 8-4 Customizing MainframeConnect Messages
  • 89. MainframeConnect for DB2/MVS-CICS version 11.1.1 Understanding the AMD2 Message Table associated text that corresponds to each message number in the translate table. After translate table processing, AMD2 searches the text table by language and message number to determine the message text to send to the client. Example of Text Table Source Code The editable SOURCE library member AMD2CAMX in the text table contains a series of SYRTMAMT entries, one for each language. Each SYRTMAMT entry contains a listing of message numbers and associated text. Portions of the text table are shown in the following example: * Message text * *-------------------------------------------------* SYRTMAMT TYPE=INITIAL * SYRTMAMT TYPE=ENTRY,LANG=us_english, * 102,'Incorrect syntax (DB2 %s failed: %S)', * 103,'String is too long (DB2 %s failed: %S)', * 105,'Unclosed quote (DB2 %s failed: %S)', * ... (additional entries not shown) * SYRTMAMT TYPE=ENTRY,LANG=german, * 102,'Falsche Syntax (DB2 %s * fehlgeschlagen: %S)', * 103,'Zeichenkette zu lang (DB2 %s * fehlgeschlagen:%S)', * 105,'Schlieendes Anfhrungszeichen fehlt * (DB2 %s * fehlgeschlagen:%S)', * ... (additional entries not shown) * SYRTMAMT TYPE=ENTRY,LANG=french, * 102,'Syntaxe incorrecte (chec de DB2 %s : %S)',* 103,'Chane trop longue (chec de DB2 %s : %S)', * 105,'Guillemet fermant manquant(chec de DB2 * %s :%S)', * ... (additional entries not shown) * SYRTMAMT TYPE=FINAL National Languages As shipped, the text table contains SYRTMAMT entries to supply message text in three languages: U.S. English, German, and French. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 8-5
  • 90. Understanding the AMD2 Message Table MainframeConnect for DB2/MVS-CICS version 11.1.1 Each SYRTMAMT entry contains a complete set of messages in the language specified by the LANG= property located in the first line of the entry. If the text table does not contain a LANG= property to match the language identification passed to AMD2, the default is the U. S. English message set. For information about how languages are defined, see the customization options appendix in the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS and the DirectConnect documentation. ® Note A default message (“Error 33231” on page A-70) returns whenever a problem with the AMD2 message table occurs. This message is always sent in U.S. English, regardless of the text coded in the text table. Message Variable Indicators The message the client application receives contains the words specified in the text table and, in some cases, the contents of one or more variable indicators: %s, %d, and %S. The words and the variables are specified in the text table. AMD2 supplies the content of the message variable indicators before a message is returned to the client. Regardless of the language of the message text, the content of the variables is always in U.S. English. AMD2 replaces the variable indicators with the variable values shown in the following table. Table 8-2: Message variable indicators and values Message Variable Replaced by Message Variable Value Indicator %s String message variable value indicating the DB2 function last executed, usually PREPARE. %d Numeric message variable value used for any integer values, such as an error number or the position of an error. %S Messages returned by DB2 routine DSNTIAR, including SQLCA message tokens and SQLCODEs. 8-6 Customizing MainframeConnect Messages
  • 91. MainframeConnect for DB2/MVS-CICS version 11.1.1 Changing the AMD2 Message Table Changing the AMD2 Message Table You can customize and update AMD2 messages by changing the AMD2 message table. For example, you can: • Add entries for new SQLCODEs • Add or change messages for a parse exit routine • Customize message text • Eliminate messages • Change message logging Adding Entries for New SQLCODEs DB2 versions later than 4.1 return SQLCODEs without corresponding entries in the translate table. In this circumstance, AMD2 assigns a generic error message (“Error 33231” on page A-70) and sends the associated text from the text table for that message number. To provide clients with more than the generic message, add new entries to the AMD2 message table for each new DB2 SQLCODE. There are two options for translating new SQLCODEs to client messages. New SQLCODEs can be: • Mapped to existing MainframeConnect messages (“Error 30000” on page A-48, “Error 30001” on page A-49, and “Error 30002” on page A-50) • Mapped to messages that correspond to SQL Server messages. These SQL Server messages may exist in the AMD2 message table, or you may need to create new entries for these messages. The changes to the AMD2 message table for the preceding two options are shown in the following table. Table 8-3: Adding entries for new SQLCODEs Message Number Translate Table Text Table For Coding the Option (MSGNO=) Changes Changes Changes, See Map to existing Assign number by Add an No change. “Adding a Mainframe- severity level: SYRTMAMX entry Translate Table Connect 30000–Error for each new Entry” on page messages. 30001–Warning message. 8-11. 30002–Confirmation. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 8-7
  • 92. Changing the AMD2 Message Table MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 8-3: Adding entries for new SQLCODEs (continued) Message Number Translate Table Text Table For Coding the Option (MSGNO=) Changes Changes Changes, See Map to SQL Use corresponding Add an • If message is “Adding a Server messages. SQL Server message SYRTMAMX entry already in text Translate Table number. for each new table, no change Entry” on page message. is needed. 8-11. • If message is not “Adding a in text table, add Message to the the message Text Table” on number and the page 8-13 text of SQL Server message to SYRTMAMT entry for each language in use. Adding or Changing Messages for a Parse Exit Routine If you customize MainframeConnect by adding a parse exit routine, you can add additional messages to the AMD2 message table to report on the processing of your routine. A sample parse exit routine ships with MainframeConnect with a corresponding message number 33400 (“Error 33400” on page A-86) in the AMD2 message table. You can modify the sample routine entries in the translate and text tables or you can create new entries. The changes to the AMD2 message table for these two options are shown in the following table. Table 8-4: Adding or changing messages for a parse exit routine Message Number Translate Table Text Table For Coding the Option (MSGNO=) Changes Changes Changes, See Modify the 33400. Change Replace message text “Modifying a sample parse SYRTMAMX as appropriate in the Translate Table exit routine properties as SYRTMAMT entry for Entry” on page message. appropriate. each language in use. 8-11. “Modifying a Message in the Text Table” on page 8-13. 8-8 Customizing MainframeConnect Messages
  • 93. MainframeConnect for DB2/MVS-CICS version 11.1.1 Changing the AMD2 Message Table Table 8-4: Adding or changing messages for a parse exit routine (continued) Message Number Translate Table Text Table For Coding the Option (MSGNO=) Changes Changes Changes, See Create new See “Selecting an Add an Add messages to the “Adding a messages. Error Message” on SYRTMAMX entry SYRTMAMT entry for Translate Table page 9-19 for for each new each language in use. Entry” on page available numbers. message. 8-11. “Adding a Message to the Text Table” on page 8-13. Customizing Message Text If the existing message text does not meet your needs, you can change the text of specific messages or translate all the messages into a different language. However, the following messages or parts of messages cannot be customized or translated: • “Error 33231” on page A-70 always returns with as-shipped U.S. English text, regardless of what is coded in the text table. • The message variable indicator strings, %s and %S, in the text table are always replaced with values that contain U. S. English text. Many of these values are DB2 commands or messages, which are always returned in U.S. English. The following table shows the changes to the AMD2 message table. Table 8-5: Customizing message text Message Number Translate Table Text Table For Coding the Option (MSGNO=) Changes Changes Changes, See Modify existing The message No change. Replace existing “Modifying a message text. number is not text with new Message in the changed. text in the Text Table” on SYRTMAMT entry page 8-13. for each language in use. Translate No new numbers are No change. Add an SYRTMAMT “Adding a messages. assigned, but text for entry with Language to the all numbers must be translated Text Table” on translated. message text. page 8-13. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 8-9
  • 94. Changing the AMD2 Message Table MainframeConnect for DB2/MVS-CICS version 11.1.1 Eliminating Messages MainframeConnect sends confirmation, warning, and error messages from DB2 to the client application. You can change the AMD2 message table to intercept those messages before they are sent, thus reducing message traffic by eliminating some of the messages. To prevent the sending of specific messages, you can make changes to the AMD2 message table as shown in the following table. Table 8-6: Eliminating messages Message Number Translate Table Text Table For Coding the Option (MSGNO=) Changes Changes Changes, See Prevent a Change the message Change the value No change. “Modifying a message from number to 0 of the MSGNO Translate Table being sent to a (MSGNO=0). property to 0 Entry” on page client (MSGNO=0). 8-11. application. Changing Message Logging As shipped, MainframeConnect writes messages to the AMD2LOG file based on the preassigned values of the translate table’s LOG= property. You can control which messages are written to the error log file AMD2LOG by changing the value of the LOG property in the translate table for each message involved. To change message logging, make changes to the AMD2 message table as shown in the following table. Table 8-7: Changing message logging Message Number Translate Table Text Table For Coding the Option (MSGNO=) Changes Changes Changes, See Write a message No change. Change the value No change. “Modifying a to the error log of the LOG Translate Table file. property to Y. Entry” on page 8-11. Prevent a No change. Change the value No change. “Modifying a message from of the LOG Translate Table being written to property to N. Entry” on page the error log file. 8-11 8-10 Customizing MainframeConnect Messages
  • 95. MainframeConnect for DB2/MVS-CICS version 11.1.1 Coding AMD2 Message Table Changes Coding AMD2 Message Table Changes To code changes to the AMD2 message table, determine whether you must change the translate table, the text table, or both, then proceed as shown in the following table. Table 8-8: Changing the AMD2 message table To modify Follow the Instructions in Translate table “Changing the Translate Table” on page 8-11 Text table “Changing the Text Table” on page 8-12 ® Note After making the changes, assemble and link the message table. Changing the Translate Table Changes to the translate table are made in the SOURCE library member AMD2CAMX. You can modify existing SYRTMAMX entries or you can add new ones; do not delete entries. Adding a Translate Table Entry To add a SYRTMAMX macro entry to the translate table, follow these steps: 1. Copy an existing SYRTMAMX macro entry. 2. Add the copied entry to the translate table. 3. Modify the property values as needed. For help in determining property values, see the explanation in “Translate Table Properties” on page 8-3. For additional information about assigning message numbers, see “Adding Entries for New SQLCODEs” on page 8-7 and “Adding or Changing Messages for a Parse Exit Routine” on page 8-8. Modifying a Translate Table Entry To modify an existing SYRTMAMX entry, follow these steps: MainframeConnect for DB2/MVS-CICS Install & Admin Guide 8-11
  • 96. Coding AMD2 Message Table Changes MainframeConnect for DB2/MVS-CICS version 11.1.1 1. Locate the target entry. 2. Change the property values as necessary. For example, if you do not want messages returned to the client application for certain DB2 SQLCODEs, set the message number property to 0 (MSGNO=0). ® Note Deleting a SYRTMAMX entry generates default messages or errors; it does not reduce the number of messages sent to the client application. To prevent the sending of certain messages, modify the property values (see “Eliminating Messages” on page 8-10) instead of removing the entry. Changing the Text Table Changes to the text table are made in the SOURCE library member AMD2CAMX. You can modify existing SYRTMAMT macro entries by adding messages or changing message text, but you should not delete messages, because then messages will not be returned for the error codes. You can also add SYRTMAMT entries to provide message text in additional languages. Rules for Text Table Entries The following rules apply to text table messages: • Message number—Do not change the message numbers of existing messages because those numbers correspond to MSGNO values in translate table entries. For new text table entries, be sure the message number added to the text table has a corresponding message added to the translate table. • Message text string—You can replace existing text or add new text. The text string, including message variable indicators, can be up to 255 characters in length. After AMD2 replaces the variable indicators with variable values, the message text returned to the client application never exceeds 512 characters. 8-12 Customizing MainframeConnect Messages
  • 97. MainframeConnect for DB2/MVS-CICS version 11.1.1 Coding AMD2 Message Table Changes Modifying a Message in the Text Table To modify the text of existing text table messages, type over the target message text with your new text, following the guidelines in “Rules for Text Table Entries” on page 8-12. Adding a Message to the Text Table To add a message to the text table, follow the format of other messages in the editable member AMD2CAMT and observe the guidelines in “Rules for Text Table Entries” on page 8-12. To avoid message processing errors, be sure to add any new messages to all the SYRTMAMT entries in use at your installation. For example, if both United States and German customers can use MainframeConnect, add all new messages to both the U.S. English and the German message sets. If a message number exists in a SYRTMAMX entry but not in the SYRTMAMT entry for the specified language, “Error 33231” on page A-70, in U.S. English, is sent to the client application. Adding a Language to the Text Table To translate message text into a different language, add an SYRTMAMT entry, containing an entire set of messages, to the SOURCE library member AMD2CAMX. To add the entry, copy and modify an existing SYRTMAMT entry (U.S. English, French, or German) as follows: 1. Place the copied SYRTMAMT entry in the text table just above the following line: SYRTMAMT TYPE=FINAL 2. Change the LANG= property to match the language identification passed to AMD2 for the target language. The first line of the new entry should look like this: SYRTMAMT TYPE=ENTRY,LANG={us_english|german|french}, 3. Replace the message text with a translation in the target language. - For information about the variable indicators, %s, %d and %S, see “Message Variable Indicators” on page 8-6. - Be sure the translated text follows the guidelines in “Rules for Text Table Entries” on page 8-12. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 8-13
  • 98. Coding AMD2 Message Table Changes MainframeConnect for DB2/MVS-CICS version 11.1.1 8-14 Customizing MainframeConnect Messages
  • 99. 9 User Exits 9. This chapter describes how to use MainframeConnect exits and provides examples of the kinds of programs you can write. ® Note Be sure you compile and link-edit MainframeConnect sample programs so that they run in 31-bit addressing mode. The samples are in the SOURCE library. This chapter contains the following sections: • User Exits in MainframeConnect 9-1 • Request/Result Validation Exits 9-1 • Parse Exit Routine 9-11 User Exits in MainframeConnect User exits enable you to set up your own rules with your own code. MainframeConnect provides user exits that allow you to write programs to: • Validate requests and results processed by MainframeConnect • Generate a list of group IDs for input to Catalog Stored Procedures (CSPs) • Customize SQL commands for a particular database or a specific purpose ® Note For information about providing security, see the Open ServerConnect Installation and Administration Guide for IBM CICS/MVS. Request/Result Validation Exits When MainframeConnect passes a request to DB2 for processing, a request/result validation exit can be called by AMD2CICS. It uses the standard EXEC CICS LINK with a common area described in the copy library book AMD2XCOB. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-1
  • 100. Request/Result Validation Exits MainframeConnect for DB2/MVS-CICS version 11.1.1 The request validation exit checks whether the request is valid by using values in the Exit Communication Area (described in “Understanding the Exit Communication Area” on page 9-5). After the request processes, a result exit can be called by AMD2CICS. It uses the standard EXEC CICS LINK with a common area described in the copy library book EXITAREA to validate the results and determine whether to give control back to MainframeConnect. It also uses values in the Exit Communication Area to determine whether to give control back to MainframeConnect. The MainframeConnect installation tape contains examples of validation exit programs. AMD2 calls the request and result validation exit programs when a request comes in and a result is returned. The request and result validation exits provide the CICS or DB2 system programmer with some additional control over the MainframeConnect request processing session. This section explains how to write a request or request validation exit. It contains the following information: • Understanding exit routines • Enabling request and result validation exits • Using the sample validation program • Understanding the exit communication area • Writing a request validation exit • Writing a result validation exit • Writing the Group ID Exit Name • Understanding Group ID Exit Name processing Understanding Exit Routines At appropriate points in the request processing sequence, MainframeConnect issues calls to your exit program. You can write an exit program to: • Enforce special installation security rules • Prohibit access during certain times of the day • Capture statistics and user information • Examine or modify the user’s SQL statement • Direct results to other destinations 9-2 User Exits
  • 101. MainframeConnect for DB2/MVS-CICS version 11.1.1 Request/Result Validation Exits The MainframeConnect INSTALL library includes a sample validation exit program, AMD2PXIT. You can modify this program or create an entirely new program. Enabling Request/Result Validation Exits You can use the MainframeConnect Configuration screen to enable or disable the request and result validation exits. For instructions on accessing the MainframeConnect Configuration screen, see “Changing the MainframeConnect Configuration” on page 7-1. ® Note If you run a remote stored procedure (RSP), the result validation exit is not called. If you run a USE REQUEST statement, the request validation exit is called once for the USE REQUEST statement and once for the SQL statement retrieved from the Host Request Library. Be sure to add an entry to the CICS PPT for each exit program. For details, see “Request exit name” and “Result exit name” on page 7-4. Using the Sample Validation Program The SOURCE library includes a sample validation program AMD2PXIT. It captures user information and puts it in a transient data queue called USERINFO. You can modify this program or create an entirely new program. TITLE 'EXITSAMP SAMPLE EXIT PROCESSING' PRINT NOGEN *–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––* * THIS SAMPLE EXIT PROGRAM IS CALLED FOR BOTH REQUEST AND RESULT * * EXITS. FOR THE REQUEST EXIT, THE REQUEST IS LOGGED TO A TEMPORARY * * STORAGE QUEUE CALLED 'USERINFO'. IN ADDITION, IF THE REQUEST NAME * * IS 'PAYROLL', THE REQUEST IS IGNORED. FOR THE RESULT EXIT, THE * * SIZE OF REPORT1 IS CHECKED. * *–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––* MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-3
  • 102. Request/Result Validation Exits MainframeConnect for DB2/MVS-CICS version 11.1.1 R0 EQU 0 R1 EQU 1 R2 EQU 2 R3 EQU 3 R4 EQU 4 R5 EQU 5 R6 EQU 6 R7 EQU 7 R8 EQU 8 R9 EQU 9 R10 EQU 10 R11 EQU 11 R12 EQU 12 R13 EQU 13 R14 EQU 14 R15 EQU 15 BLANK EQU X'40' EJECT *––––––––––––––––––* * INITIALIZATION * *––––––––––––––––––* EXITSAMP DFHEIENT CODEREG=(12),DATAREG=(13) USING EXITAREA,R8 ESTABLISH DSECT ADDRESSABILITY L R8,DFHEICAP GET ADDRESS OF EXITAREA *–––––––––––––––––––––––––––––––––––––* * HANDLE A CALL TO THE REQUEST EXIT * *–––––––––––––––––––––––––––––––––––––* REQUEST CLC XREASON,=CL8'REQUEST' CALL TO REQUEST EXIT ? BNE RESULT NO, BRANCH CLC XREQNAME,=CL8'PAYROLL' IS THIS A PAYROLL REQUEST ? BE IGNORE YES, IGNORE THE REQUEST MVC LOGREC,BLANKS CLEAR LOG RECORD MVC LOGREC+00(08),XDATE DATE MVC LOGREC+09(08),XTIME TIME MVC LOGREC+18(08),XUSERID USERID MVC LOGREC+27(08),XREQNAME REQUEST NAME MVC LOGREC+36(08),XREQFUNC REQUEST FUNCTION EXEC CICS WRITEQ TS QUEUE('USERINFO') + FROM(LOGREC) LENGTH(44) B RETURN RETURN 9-4 User Exits
  • 103. MainframeConnect for DB2/MVS-CICS version 11.1.1 Request/Result Validation Exits *––––––––––––––––––––––––––––––––––––* * HANDLE A CALL TO THE RESULT EXIT * *––––––––––––––––––––––––––––––––––––* RESULT CLC XRESNAME,=CL8'REPORT1' IS THIS REPORT1 ? BNE RETURN NO, BRANCH L R3,XRESROWS GET RESULT ROW COUNT ? C R3,=F'3000' IS REPORT TOO LARGE ? BNH RETURN NO, BRANCH MVC XERRMSG,=CL70'REPORT TOO LARGE. CHANGE WHERE CLAUSE' B IGNORE *–––––––––––––––––––––––––––––––––* * RETURN TO THE CALLING PROGRAM * *–––––––––––––––––––––––––––––––––* IGNORE MVC XACTION,=CL8'IGNORE' INDICATE IGNORE RETURN DS 0H EXEC CICS RETURN EJECT *–––––––––––––––––––––––––* * MISCELLANEOUS STORAGE * *–––––––––––––––––––––––––* BLANKS DC CL44' ' LTORG DFHEISTG LOGREC DS CL44 COPY EXITAREA END Understanding the Exit Communication Area When a call is made to the request or result validation exit, the exit communication area passes information to the exit program. The Exit Communication Area contains information that is passed to either a request or result validation exit program when a call is made to that program. The MACRO library includes a description of the exit communication area (EXITAREA), which follows: MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-5
  • 104. Request/Result Validation Exits MainframeConnect for DB2/MVS-CICS version 11.1.1 *********************************************************************** * COMMUNICATION AREA PASSED TO THE REQUEST/RESULT EXITS * *********************************************************************** EXITAREA DSECT XHEADER DS CL8 EYE CATCHER XREASON DS CL8 REASON FOR CALLING EXIT XUSERID DS CL8 USER IDENTIFICATION XTERMID DS CL4 TERMINAL IDENTIFICATION XDATE DS CL8 DATE IN MM/DD/YY FORMAT XTIME DS CL8 TIME IN HH:MM:SS FORMAT XSERVER DS CL8 NAME OF SERVER XDBSID DS CL30 DATABASE SYSTEM ID XDBUID DS CL30 DATABASE USER ID *––––––––––––––––––––––––––––* * REQUEST EXIT INFORMATION * *––––––––––––––––––––––––––––* XREQINFO DS 0CL28 REQUEST INFORMATION XREQNAME DS CL8 REQUEST NAME XREQADDR DS F ADDRESS OF REQUEST BUFFER XREQFUNC DS CL8 REQUEST FUNCTION XREQOPT DS CL8 REQUEST OPTION *––––––––––––––––––––––––––––* * RESULT EXIT INFORMATION * *––––––––––––––––––––––––––––* XRESINFO DS 0CL36 RESULT INFORMATION XRESNAME DS CL8 RESULT NAME XRESOPT DS CL8 RESULT OPTION XRESTYPE DS CL3 RESULT TYPE XRESFILL DS CL1 FILLER XRESCODE DS F DB2 RETURN CODE XRESROWS DS F NO. OF ROWS IN RESULT XRESSIZE DS F NO. OF BYTES IN RESULT XRESQNAM DS CL8 TEMPORARY STORAGE QUEUE NAME *–––––––––––––––––––––––––––––––––––––––––––––––––––* * VALUES THAT CAN BE MODIFIED BY THE EXIT PROGRAM * *–––––––––––––––––––––––––––––––––––––––––––––––––––* XACTION DS CL8 ACTION TO BE TAKEN XDDBNAME DS CL8 DEFAULT DATABASE NAME XDTSNAME DS CL8 DEFAULT TABLESPACE NAME XERRMSG DS CL70 ERROR MESSAGE XFILLER DS CL30 FILLER Common Fields When you call the exit program, certain fields are always passed from the Exit Communication Area to the exit program by 9-6 User Exits
  • 105. MainframeConnect for DB2/MVS-CICS version 11.1.1 Request/Result Validation Exits MainframeConnect, regardless of the validation exit that was called. These fields are as follows: Table 9-1: Common Exit Communication Area Fields Field Description XHEADER The eye-catcher containing the word EXITAREA. XREASON The reason for calling the exit. REQUEST indicates a call to the request validation exit; RESULT indicates a call to the result validation exit. XUSERID The user identification. XTERMID The terminal identification. XDATE The current date in the format MM/DD/YY. XTIME The current time of day in the format HH:MM:SS. XSERVER The database server name. XDBSID The database system ID, which is not applicable for DB2. XDBUID The database user ID, which is not applicable for DB2. The values for these fields are shown in the example in “Understanding the Exit Communication Area” on page 9-5, following the first comment area. Writing a Request Validation Exit MainframeConnect calls the request validation exit before a request is executed by MainframeConnect. The exit program examines the exit communication area that MainframeConnect passes to it. Based on the information in the XACTION field description, the exit program either passes, fails, or modifies the request. The request validation exit can be either a separate program or combined with the result validation program. You can check the XREASON field to determine the reason for the call. The communication area fields that pertain to the request validation exit are as follows: Table 9-2: Request Validation Communication Area Fields Field Description XREASON An eye-catcher containing the word REQUEST. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-7
  • 106. Request/Result Validation Exits MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 9-2: Request Validation Communication Area Fields Field Description XREQNAME The name of the request. XREQFUNC The request function. Valid values are SELECT, UPDATE, USE, and so on, which are taken from the SQL statement. The first word of the SQL statement is not used anymore. XREQOPT The request option. Valid values are PREVIEW and REPORT, which are taken from the SQL statement. XREQADDR The address of the request buffer. The request buffer is formatted as a half-word length field followed by the request. XACTION This field is blank when MainframeConnect sends it on to DB2. If you specify it, the exit program can place a value in this field to indicate what action MainframeConnect takes: • If you leave this field blank, MainframeConnect does nothing. Processing proceeds in the normal fashion. • If you specify IGNORE, MainframeConnect ignores the request, and processing continues with the next request in the request queue. This request is not treated as an error condition. • If you specify REJECT, MainframeConnect rejects the request. This request is treated as an error condition. If a request is ignored or rejected, MainframeConnect issues an appropriate error message when the results return to the client application. If you specify it, the exit program can supply an additional error message in the XERRMSG field. XERRMSG This field is blank. The values for the request validation exit fields are shown throughout the example in “Understanding the Exit Communication Area” on page 9-5. Writing a Result Validation Exit The result validation exit is called after each request runs. The exit program can examine the exit communication area that MainframeConnect passes to it. Based on the information in the communication area, the exit program can either pass or fail the result. 9-8 User Exits
  • 107. MainframeConnect for DB2/MVS-CICS version 11.1.1 Request/Result Validation Exits The communication area fields that pertain to the result validation exit are as follows: Table 9-3: Result Validation Communication Area Fields Field Description XREASON An eye-catcher containing the word RESULT. XRESNAME The name of the result. XRESOPT The result option. The valid value is PREVIEW. XRESTYPE The result type. The valid value is OUT. XRESCODE The DB2 return code. XRESROWS The size of the result in rows. XRESSIZE The size of the result in bytes. XRESQNAM The queue name of the result file. XACTION This field is blank when MainframeConnect sends it on. The exit program can place a value in this field to indicate which of the following actions MainframeConnect takes: • If you leave this field blank, MainframeConnect does nothing. Processing proceeds in the normal fashion. • If you specify IGNORE or REJECT, MainframeConnect bypasses this result, which means the result exit is called once per result, not once for each row. It does not return the result to the client application. The results might also be rejected if a row count is exceeded. XERRMSG The error message or blank. If you want an additional error message in the XERRMSG field, the exit program can supply it. ® Note If you use a result exit, set Temp storage queue type to AUX or MAIN at the MainframeConnect Configuration screen (see “Temp storage queue type” in Chapter 7, “Configuring MainframeConnect”). The result exit is not called when Temp storage queue type is set to NONE. The values for the result validation exit fields are shown throughout the example in “Understanding the Exit Communication Area” on page 9-5. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-9
  • 108. Request/Result Validation Exits MainframeConnect for DB2/MVS-CICS version 11.1.1 Using the Group ID Exit Name The Group ID Exit Name is a CICS program that builds a list of group IDs for CSPs to use. Depending on the configuration values of the catalog access parameters, this program can be called, before CSPs are generated. This program provides the appropriate list of group IDs used to determine table and column authorizations for CSP results. Generally, you write CSP exit programs when you are not using RACF, ACF2, or Top Secret; yet, you want the equivalent of Group-ID Support. However, if you use those security packages, you can also write an exit program to limit the result set returned from CSPs; for example, when user IDs belong to large numbers of groups. The Group ID Exit Name is a dynamic link. To use it, you must add an entry for a user CSP exit program to the CICS PPT. Also, the program must be in the CICS RPL. Understanding Group ID Exit Name Processing When the Group ID Exit Name is called, MainframeConnect passes the exit program a 4012-byte communication area into which the exit program can build a list of up to 500 eight-byte group IDs. The format of the communication area is as follows: COMMAREA DSECT COUNT DS F USERID DS CL8 ENTRIES DS 500CL8 The COUNT field contains the number of entries in the list including the original user ID; ENTRIES can contain a list of 500 eight-byte group IDs. The communication area comes with an entry for USERID already filled in. The COUNT field contains 1. The exit program can perform one of the following actions: • Do nothing. The user ID is used for CSPs. • Replace the user ID with a new ID. The new ID is used for CSPs. • Add additional IDs to the list. The additional IDs must follow the entry for user ID, and the COUNT field must change to reflect the total number of IDs in the list (including the user ID). All the IDs are used for the CSPs. 9-10 User Exits
  • 109. MainframeConnect for DB2/MVS-CICS version 11.1.1 Parse Exit Routine In the example that follows, two group IDs (GROUP1 and GROUP2) are added to the list: EXITPROG DFHEIENT USING COMMAREA,R2 L R2,DFHEICAP MVC COUNT,=F'3' MVC ENTRIES+08(08),=CL8'GROUP1' MVC ENTRIES+16(08),=CL8'GROUP2' EXEC CICS RETURN LTORG DFHEISTG COMMAREA DSECT COUNT DS F ENTRIES DS 501CL8 END Parse Exit Routine The parse exit routine is similar to a request exit. It allows a customer-written exit routine to alter SQL text received from MainframeConnect clients before the SQL statements are passed to DB2. By altering the SQL text, your routine can customize SQL commands for a particular database or a specific purpose. There are several potential uses for this option. For example, you can use a parse exit routine to limit the scope of client access by restricting client SQL statements to select statements only. You can also use the parse exit routine to modify the qualifiers for DB2 object names to provide additional security restraints on accessing mainframe data. This section explains how to write a parse exit routine. It is organized around the following tasks, which are performed by the programmer: 1. Understanding the parse exit routine 2. Preparing to code your routine 3. Coding your routine 4. Compiling and link-editing your routine 5. Enabling your routine A section containing the definitions for the fields that pass values to and from your routine is included in “CICS Common Area Fields” on page 9-15. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-11
  • 110. Parse Exit Routine MainframeConnect for DB2/MVS-CICS version 11.1.1 Understanding the Parse Exit Routine When the CICS transaction AMD2 receives SQL text from a DirectConnect client, it processes the statements and prepares to send the SQL text to DB2. If the parse exit is specified on the MainframeConnect Configuration screen, AMD2 calls the parse exit routine before passing the SQL text to DB2. For more information, see “Parse exit name” in Chapter 7, “Configuring MainframeConnect.” Calling the Parse Exit from AMD2 For CICS, AMD2 uses the EXEC CICS LINK command to call the parse exit routine. The call is executed only if the parse exit option is selected using the MainframeConnect Configuration screen. See “Changing the MainframeConnect Configuration” in Chapter 7, “Configuring MainframeConnect,” for instructions on using the MainframeConnect Configuration screen. This option can be selected during installation of the product (see step 3 in “Changing the MainframeConnect Configuration” on page 7-1), or when you enable your routine following the instructions in this section. Before calling the parse exit routine, AMD2 sets up the parse exit common area that a parse exit routine can access. Your routine should alter the values in the common area of the parse exit as shown in the following table. An explanation of the fields and information about changing their values is included in “CICS Common Area Fields” on page 9-15. Table 9-4: Altering values in common area fields Common Area Field When to Alter the Value USERID Never PASSWORD Never NETGWNAME Never STMT-PTR When the SQL text length changes RETCODE Always (every invocation of the routine) MSGCODE When the return code equals +2 9-12 User Exits
  • 111. MainframeConnect for DB2/MVS-CICS version 11.1.1 Parse Exit Routine Processing Batched SQL Statements AMD2 calls the parse exit routine once for each SQL statement. If the SQL statements are batched using the semicolon delimiter, AMD2 processes each statement separately, calling the parse exit routine and passing the returned SQL text to DB2. Processing continues until one of the following conditions occurs: • The batch is exhausted. • The parse exit routine requests that the batch be aborted. • A DB2 error occurs in processing any statement in the batch. Processing User-Defined Transactions A user-defined transaction is a unit of work explicitly defined by the client application with transaction control statements such as begin tran, commit, and rollback. A unit of work is the data that the users want to confirm was added to the back end database. The parse exit routine is called once for each SQL statement, including the transaction control statements that define the transaction. Your routine should not alter transaction control statements. x WARNING! A customer-defined transaction causes AMD2 to maintain database locks and the DirectConnect-to-mainframe connection until you end the transaction. If your parse exit routine alters the transaction control statements, especially those that explicitly end the transaction, your routine can impact DB2 and other mainframe resource usage. Returning to AMD2 After customizing the SQL text, the exit routine returns to AMD2, which passes the altered SQL statements to DB2 without further modification. The Parse Exit Common Area The parse exit common area passes information between AMD2 and the parse exit routine. It is acquired and initialized by AMD2. A MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-13
  • 112. Parse Exit Routine MainframeConnect for DB2/MVS-CICS version 11.1.1 COBOL II copy book, AMD2XCOB, defines the common area fields that are passed (through the linkage section) to a COBOL II parse exit routine. This copy book is distributed with MainframeConnect (see “COPY Library” in Chapter 5, “Installing the MainframeConnect Tape”). The layout of the common area follows, with descriptions of each field. Layout of the AMD2XCOB Copy Book The CICS common area has the following structure. (“DB2 Access Module” in the following copy book means “AMD2.”) ************************************************************** * AMD2XCOB Rel 10.1 * This copy book defines the LINKAGE SECTION for a COBOL II * Parse Exit Routine for DB2 Access Module. ************************************************************** 01 AMD2XCOB-COMMAREA REDEFINES DFHCOMMAREA. 05 AMD2XCOB-CA-EYECATCHERPIC X(8). 05 AMD2XCOB-CA-USERID PIC X(32). 05 AMD2XCOB-CA-PASSWORDPIC X(32). 05 AMD2XCOB-CA-NETGWNAMEPIC X(32). 05 AMD2XCOB-CA-CHARSETCLTPIC X(32). 05 AMD2XCOB-CA-CHARSETSRVPIC X(32). 05 AMD2XCOB-CA-NATLANGCLTPIC X(32). 05 AMD2XCOB-CA-DBCSPIC X(32). 05 AMD2XCOB-CA-STMT-PTRPOINTER. 05 AMD2XCOB-CA-RETCODEPIC S9(9) COMP. 05 AMD2XCOB-CA-MSGCODEPIC S9(9) COMP. 05 AMD2XCOB-CA-RESERVEDPIC X(80). *------------------------------------------------------------ * Define SQL text area pointed to by AMD2XCOB-CA-STMT-PTR *------------------------------------------------------------ 01 AMD2SQL-TEXT-LVL-01. 03 AMD2SQL-TEXT. 05 AMD2SQL-TEXT-LLPIC S9(4) COMP. 05 AMD2SQL-TEXT-CHARS OCCURS 0 TO 32704 TIMES 9-14 User Exits
  • 113. MainframeConnect for DB2/MVS-CICS version 11.1.1 Parse Exit Routine DEPENDING ON AMD2SQL-TEXT-LL PIC X. 03 AMD2SQL-TEXT-DUMMY-LVLPIC X. ***************************************************************** * END AMD2XCOB COPY BOOK ***************************************************************** CICS Common Area Fields The following AMD2XCOB-CA- fields are defined for COBOL/CICS. Table 9-5: CICS Common Area Fields Field Description EYECATCHER This value is set by AMD2. If it is altered by the parse exit routine, unpredictable results occur. USERID The user ID of the client sending the request. This field should not be altered by the parse exit routine. PASSWORD The password of the client sending the request. This field should not be altered by the parse exit routine. NETGWNAME The name of DirectConnect specified by the client. These fields should not be altered by the parse exit routine. CHARSETCLT Reserved for future use. CHARSETSRV Reserved for future use. ATLANGCLT Reserved for future use. DBCS Reserved for future use. STMT-PTR A pointer to a single SQL statement beginning with the 2- byte SQL length. The parse exit routine should alter the pointer to hold the new address of the SQL text area when this address is changed by the exit routine. It is only necessary to acquire a new SQL text area if the existing area is not large enough for the SQL text after it is altered by the user. AMD2 uses this pointer to determine whether the exit routine allocated storage that AMD2 must deallocate. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-15
  • 114. Parse Exit Routine MainframeConnect for DB2/MVS-CICS version 11.1.1 Table 9-5: CICS Common Area Fields Field Description RETCODE A full-word return code. The user-written parse exit routine should alter this field. Valid values are: 0—Passes the SQL text to DB2. +1—Does not pass the SQL text to DB2 and continues with the next statement in the batch, if there is one. +2—Aborts the batch and returns an error message using the message code in the next parse exit communication area field. MSGCODE A fullword message code. This field should be altered by the user-written parse exit routine if the return code was set to +2. AMD2 ignores it in all other cases. RESERVED Reserved for future use. Getting Ready to Code Your Routine This section describes your programming language options and the materials we provide, such as the sample routine and the COBOL copy book, that can help you write your routine. Programming Languages The parse exit feature is designed to work with Assembler, COBOL, and PL/I. We supply a sample parse exit routine in COBOL and a COBOL copy book that defines the linkage section for a COBOL II parse exit routine. This routine is in the SOURCE library. Sample Parse Exit Routine The sample parse exit routine, AMD2CCPX, is located in the SOURCE library. You can modify this program or use it as an example. The COBOL copy book is discussed in the “The Parse Exit Common Area” on page 9-13. Coding Your Routine This section contains information about the tasks that you should code your routine to perform. These tasks include: 9-16 User Exits
  • 115. MainframeConnect for DB2/MVS-CICS version 11.1.1 Parse Exit Routine • Altering the SQL text to suit your purposes • Acquiring additional storage, if necessary • Handling errors • Assigning a return code • Selecting an error message Altering the SQL Text The parse exit common area contains a pointer to the SQL text area. The text area consists of the SQL text preceded by a 2-byte SQL length field, which provides the number of bytes in the SQL text. (The SQL length field does not include the 2 bytes for the length field itself.) If your exit routine changes the length of the SQL text, it must also change the value in the 2-byte length field. • If the SQL text is shortened by the processing of your exit routine, you need only to correct the value in the length field. • If the SQL text is expanded by your exit routine, you must acquire additional storage to handle the overflow. ® Note As you code your exit routine to alter the SQL text, be aware that AMD2 does not modify the SQL text after your routine is executed; therefore, the SQL statements must be in the DB2 syntax before the parse exit routine returns to AMD2. Acquiring Additional Storage If your routine expands the SQL statements beyond the length specified in the 2-byte SQL length field, the parse exit routine must acquire additional storage before it alters the SQL text. x WARNING! A storage violation can occur if your routine expands the SQL text area beyond the specified length in the 2-byte SQL length field without first acquiring additional storage. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-17
  • 116. Parse Exit Routine MainframeConnect for DB2/MVS-CICS version 11.1.1 To acquire additional storage for a larger SQL text area, your routine must issue a GETMAIN command. Like the old SQL text area, the new one must allow 2 bytes for the length field in addition to the area needed for the expanded SQL statement. After altering the new SQL text, your routine must: • Load the length field with the new length of the SQL text after it is expanded • Change the pointer in the parse exit common area to the location of the new SQL text area This pointer should be altered by the parse exit routine to hold the new address of the SQL text area if this address is changed by the exit routine. It is only necessary to acquire a new SQL text area if the existing area is not large enough for the SQL text after it is altered by the user. Your exit routine does not need to deallocate the storage it acquires. After the routine returns, AMD2 checks the SQL text pointer. If the pointer changed during the exit routine execution, AMD2 deallocates the additional storage after DB2 processes the SQL statement. Handling Errors Errors associated with parse exit routine execution can occur before the routine is called, during the routine’s processing, and after the routine returns to AMD2. This section describes the types of errors and their consequences, so that you can provide appropriate error handling code in your routine. Before the Routine Is Called The parse exit routine is not invoked if an error occurs in AMD2 processing before the parse exit call. “Error 33233” on page A-72 is sent to the client if this occurs. During Parse Exit Routine Processing Errors that occur during the processing of your routine produce the following results: • If your routine abnormally ends (abends) and your code does not handle the abend, MainframeConnect abends and the appropriate messages may not be returned. 9-18 User Exits
  • 117. MainframeConnect for DB2/MVS-CICS version 11.1.1 Parse Exit Routine • If your routine abends and your code handles the abend, MainframeConnect may not be aware of the abend, depending upon how your abend handler is written. • If your routine contains an internal logic error, the results may be unpredictable. After Returning to AMD2 Errors that result from exit routine processing can occur after the routine returns to AMD2. • If your routine acquires additional storage and incorrectly alters the pointer to the SQL text, MainframeConnect abends when AMD2 issues a FREEMAIN command to deallocate the additional storage. • If the modifications of the SQL text are invalid, DB2 performs its usual error handling. Any DB2 error that occurs in batched SQL commands terminates the entire batch, unless the Stop_on_error property is set. For DirectConnect messages, see the DirectConnect Error Message Guide. Assigning a Return Code Your exit routine must pass a return code back to AMD2 in the parse exit common area field AMD2XCOB-CA-RETCODE. Valid values are: 0—Passes the SQL text on to DB2. +1—Does not pass the SQL text to DB2 and continues with the next statement, if there is one. +2—Aborts the batch and returns an error message using the message code in the AMD2XCOB-CA-MSCODE field. Selecting an Error Message If your exit routine sets the return code to +2, it should also change the parse exit common area message code field AMD2XCOB-CA-MSGCODE. After a parse exit routine returns to AMD2 with a return code of +2, AMD2 matches the message code against the message table AMD2CAMX. If the message code is in the table, AMD2 sends the text associated with that message number. If AMD2 cannot find the MainframeConnect for DB2/MVS-CICS Install & Admin Guide 9-19
  • 118. Parse Exit Routine MainframeConnect for DB2/MVS-CICS version 11.1.1 message code in the table, it sends the default error message: “Error 33231” on page A-70. Any message code between 33400 and 33999 is available for use as a user message code. AMD2CAMX is shipped with a sample error message (“Error 33400” on page A-86), which is coded for the parse exit routine. Altering the Message Table To add messages for your routine to the message table, add entries to the SOURCE library member AMD2CAMX. After making any changes, you must reassemble and relink the message table. The JCL for this job is in JCL Library members AMD2CAMX. For more information, see “Changing the AMD2 Message Table” in Chapter 8, “Customizing MainframeConnect Messages.” Compiling and Link-Editing Your Routine The JCL for compiling and link-editing a parse exit routine is in the JCL library member SYSAPARS. Change the property values to those for your routine before running the job. Enabling Your Routine You can enable your routine by specifying the parse exit name on the MainframeConnect Configuration screen, which shows you whether it is successfully enabled. 9-20 User Exits
  • 119. Troubleshooting
  • 120. 10 Troubleshooting 10. This chapter provides guidelines for what to do when a client application cannot access data on the mainframe. The guidelines include how to locate an error and cover the most frequent problems. This chapter also includes operational and process flow overviews for Enterprise Connect. The information applies to both CICS LU 6.2 and TCP/IP environments, except where differentiated. The sections in this chapter are: • Verifying Connectivity After Installing MainframeConnect 10-1 • Where to Start Troubleshooting 10-2 • Common Problems and Suggested Solutions 10-3 • Components 10-6 • Coordination 10-14 ® Note This chapter describes mainframe troubleshooting. For comparable DirectConnect information, see the DirectConnect Transaction Router Service User’s Guide and the DirectConnect for MVS Access Service User’s Guide. Verifying Connectivity After Installing MainframeConnect If you already ran Be sure the AMD2 transaction processor and the client and server snaping or cicsping, connections are configured correctly. You can use one of the successfully, skip to “Where to Start standalone utilities (snaping or cicsping) shipped with Open Troubleshooting” on ServerConnect to test the network connections between the page 10-2 workstation and mainframe. Use snaping for Open ServerConnect for LU 6.2 and cicsping for Open ServerConnect for TCP/IP. These utilities do not require DirectConnect to be active. For details on using them, see the DirectConnect for MVS Connectivity Guide. If these utilities fail to operate correctly, the failure is caused by a configuration error or line outage problem. Based on the error message returned, you can narrow your search. Resolution may require coordination with the DirectConnect administrator to make changes to the configuration. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-1
  • 121. Where to Start Troubleshooting MainframeConnect for DB2/MVS-CICS version 11.1.1 After snaping or cicsping runs successfully, be sure the DirectConnect administrator defined all the necessary remote procedure call (RPC) and connection information to DirectConnect. Be sure that DirectConnect is started. Use the guidelines in the following section for further problem determination. Where to Start Troubleshooting System administrators at the client, DirectConnect server, and mainframe must check components systematically to locate the source of the problem. Check for problems in this sequence: 1. Major outage, such as CICS crashed or your personal computer is unplugged 2. Client application 3. Client LAN 4. Client network setup 5. DirectConnect server 6. Connection from the client application to the DirectConnect server 7. Connection from the DirectConnect server to the mainframe 8. Configuration between the transaction processor and Open ServerConnect or MainframeConnect For any of these problems, the appropriate system administrator should: • Record specific information about the error message(s), including: - Error message number - Associated SNA sense codes, SNA Services error codes, or TCP/IP error codes - The time the error occurred - The client or user affected • See the appropriate documentation, as needed. For example, if you need information about MainframeConnect errors, see Appendix A, “Error Messages.” • Perform the recommended action. • Continue the process until the problem is resolved. 10-2 Troubleshooting
  • 122. MainframeConnect for DB2/MVS-CICS version 11.1.1 Common Problems and Suggested Solutions Common Problems and Suggested Solutions Problems often can be traced to configuration errors or network, line, modem, or adapter outages. Configuration Errors Configuration errors are most often the cause of communications failure. To resolve these errors, you need the following information, which is created when the network is installed and successfully implemented: • CICS table definitions for TCT, PCT, PPT, FCT, and RCT • VTAM/NCP definitions for the logical unit (LU) and associated Logmode table • SDLC or Token Ring connection charts to the mainframe • Named pipe and SPX charts to clients • TCP/IP connection charts to clients • For CICS LU 6.2, server SNA configuration • For CICS TCP/IP, server TCP/IP configuration • Sybase interface files for clients and DirectConnect servers • Sybase security definitions, including client logins, connection groups, and transaction groups Verify that this information is still the same as before the error occurred. If it is not the same, determine if a recent change is contributing to the problem. The following subsections explain the causes and actions for common configuration errors. Cannot Establish a Session Cause Any of the following: • Mismatched LU definitions between VTAM and server • Mismatched modenames • Incorrect VTAM MODETAB and APPLID macros • Incorrect CICS TCT definitions MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-3
  • 123. Common Problems and Suggested Solutions MainframeConnect for DB2/MVS-CICS version 11.1.1 Action Correct the spelling. Coordinate with the DirectConnect administrator to check connection and modename profiles using the snaping or cicsping utility shipped with the product. Session Established, but the Transaction Does Not Run Cause Any of the following: • CICS PCT or PPT entry error • host security error • Incorrect transaction ID in the DirectConnect RPC table Action Verify definitions. Coordinate with the DirectConnect administrator for correct security and transaction ID setups. SDLC Line or Token Ring is Not Up Cause Address incorrectly configured with NCP (assumes correct line or modem setup) Action Check both ends of the SDLC station or Token Ring address configuration. SDLC Link and PU are Active, but the LU Is Not Active Cause Any of the following: • VTAM and DirectConnect LU definition errors • SSCPID value in the local LU profile set incorrectly 10-4 Troubleshooting
  • 124. MainframeConnect for DB2/MVS-CICS version 11.1.1 Common Problems and Suggested Solutions Action Use the SDLC trace and error log facilities to find the error. Mainframe Network Operational Failure On the mainframe, there are two frequent causes of operational errors: • The CICS or VTAM operator varied the resource out of service. • VTAM placed the line, physical unit (PU), or LU into a non- operating (INOP) state because of a network outage. In these cases, either: • The DirectConnect administrator sees SNA software time-out and connection failure messages in trying to start up DirectConnect, or • The requesting client sees a SNA software message indicating that the system could not start the RPC. When you are contacted about such messages, reactivate the necessary mainframe resources. Network Session or Line Failures Line, adapter, or modem outages result in error messages at both the VTAM console and DirectConnect. DirectConnect records the message and, if possible, sends a similar error message to any affected clients. Preventative Measures Intermittent hardware errors and line degradation problems can disrupt processing, but can be difficult to find. You should check periodically for these types of problems. For example: • To check for hardware errors, use the associated VTAM error logs and report errors to IBM Service. • To check for line degradation, use VTAM to periodically report the SDLC line statistics. Examine the statistics for a significant number of re-transmissions or idle detect time-outs. Line degradation results in random SDLC line failures or very slow response to the client, even during a moderate processing load. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-5
  • 125. Components MainframeConnect for DB2/MVS-CICS version 11.1.1 Components Enterprise Connect support consists of several components on the IBM mainframe and the DirectConnect platform, as Figure 10-1 shows. These components provide tracing and logging, which you can use to locate errors. This section includes examples of tracing and logging for CICS. The following figure shows Enterprise Connect components in a CICS environment: 10-6 Troubleshooting
  • 126. MainframeConnect for DB2/MVS-CICS version 11.1.1 Components Figure 10-1: Open ServerConnect and DirectConnect support components DirectConnect Support DirectConnect performs the following functions: MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-7
  • 127. Components MainframeConnect for DB2/MVS-CICS version 11.1.1 • Receives requests from client applications • Converts the requests to the appropriate communications protocol call • Sends the requests to the mainframe Each TRS or access service includes a unique server name, which clients use to select a server for communication. Each TRS or access service has its own set of configuration information. As shown in Figure 10-1, DirectConnect uses four files: • nglog for logging TDS traffic between TRS and client workstations, and for recording errors • ngtds for tracing Sybase TDS traffic between TRS and mainframe SNA • servername.log for logging TDS traffic between the Access Service and client workstations, and for recording errors • tds.trc for tracing Sybase TDS traffic between the Access Service and mainframe SNA For more information, see the DirectConnect Transaction Router Service User’s Guide and the DirectConnect for MVS Access Service User’s Guide. DirectConnect Communications with MainframeConnect DirectConnect depends on the communications support, supplied by the platform vendor, to communicate with MainframeConnect. Depending on the server-based communications software installed, DirectConnect uses SNA LU 6.2 or TCP/IP Uplink support. SNA LU 6.2 SNA software uses the SNA trace file to record SDLC/SNA traffic between the server and mainframe. The vendor trace utility extracts this file. For Windows NT platforms, the error log file records errors that SNA Server for Windows NT detects. TCP/IP Uplink For CICS TCP/IP environments, third-party TCP/IP trace facilities provide a way of obtaining low-level TCP/IP level traces between 10-8 Troubleshooting
  • 128. MainframeConnect for DB2/MVS-CICS version 11.1.1 Components the mainframe and DirectConnect. For AIX platforms, the error log file records errors that SNA Server/6000 detects. The IBM error log report utility extracts this information. Microsoft SNA Server for Windows NT also has a trace process. Mainframe Communications with DirectConnect Mainframe-based communications support provides the “transport” level of function. Depending on the mainframe communications software installed, Gateway-Library uses VTAM/NCP or TCP/IP for MVS. VTAM/NCP For CICS LU 6.2 environments, you can use the VTAM General Trace Facility (GTF) files to trace SDLC/SNA traffic between Gateway- Library and the mainframe. The IBM TAP utility extracts this information. TCP/IP for MVS For CICS TCP/IP environments, you can use the Netstat facility to check the status of TCP/IP connections, as well as to deactivate them if problems occur. You can use the TCP/IP trace facility to trace traffic between DirectConnect and the mainframe. TCP/IP Sockets Interface The TCP/IP Sockets Interface provides the interface between CICS and the MVS/TCP support. The Sockets Interface enables CICS applications to use TCP/IP communications facilities. It uses the IBM-supplied TCP/IP Listener transaction to initiate transactions when operating with TCP/IP devices, such as DirectConnect. The TCP/IP Sockets Interface provides CICS user exit traces, denoting each TCP call issued and the associated return call. CICS For CICS, Gateway-Library tracing stores information on the TDS traffic between the mainframe and server in the VSAM ESDS file, MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-9
  • 129. Components MainframeConnect for DB2/MVS-CICS version 11.1.1 SYTDLOG1. This information includes any errors detected in the traffic. Some TD calls fill up internal TDS buffers before sending them out to the network. For example, a TDSNDROW or TDSNDMSG call does not cause execution of a corresponding CICS EXEC SEND call, unless the TDS buffer becomes full. x WARNING! To avoid losing records, periodically archive or delete the trace records on SYTDLOG1. Trace records append to this file until it is full. Then it rejects any further records. MainframeConnect for DB2/MVS-CICS MainframeConnect for DB2/MVS-CICS provides the AMD2 transaction, which automatically processes client SQL language requests using the DB2 dynamic SQL facilities. Using this product, client applications can communicate directly with DirectConnect or with another server that communicates with DirectConnect, such as SQL Server or OmniConnect (as shown in the following figure): 10-10 Troubleshooting
  • 130. MainframeConnect for DB2/MVS-CICS version 11.1.1 Components Figure 10-2: MainframeConnect and DirectConnect support components Tracing For MainframeConnect, you can use the standard DirectConnect tracing support. See Figure 10-1. Logging You can determine the errors logged. Enter changes in SOURCE library member AMD2MAMX, as detailed in MainframeConnect MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-11
  • 131. Components MainframeConnect for DB2/MVS-CICS version 11.1.1 installation instructions. For example, to indicate that you want a message logged, set LOG=Y. SYRTMAMX TYPE=ENTRY, MSGNR=32000, SQLCODE=0, LEVEL=11, STATEC=0, STATESC=0, LOG=Y, SQLFATAL=N x WARNING! If a connection fails, the error log is the only method of tracking an error. To prevent the log from running out of room, initialize the log file regularly. In a CICS environment, MainframeConnect provides the AMD2LOG and AMD2LOGO files. The AMD2 transaction writes errors to AMD2LOG, including task ID, term ID, timestamp, and the unique message code for each error. AMD2 also returns an error message to the client. Under CICS, if AMD2LOG is full or no longer accepts messages, AMD2 writes errors to the overflow file, AMD2LOGO. AMD2 then issues error message 33219: MainframeConnect error (Write to log file AMD2LOG failed, switching to overflow log AMD2LOGO). Under CICS, you can close, archive (if desired), and purge AMD2LOG when it becomes full. During the time AMD2LOG is closed, AMD2 writes messages to AMD2LOGO that you can close, archive, and purge once you reopen AMD2LOG. In this example, AMD2 writes an internal error 32000 to AMD2LOG (or AMD2LOGO, if AMD2LOG is full). For CICS environments, you must define the error log files to CICS in an FCT entry as follows: • AMD2LOG 10-12 Troubleshooting
  • 132. MainframeConnect for DB2/MVS-CICS version 11.1.1 Components DFHFCT TYPE=DATASET, ACCMETH=VSAM, DATASET=AMD2LOG, RECFORM=(FIXED,BLOCKED), DSNAME=your.syrtlog.dataset.name, DISP=SHR, SERVREQ=(ADD,BROWSE) • AMD2LOGO DFHFCT TYPE=DATASET, ACCMETH=VSAM, DATASET=AMD2LOGO, RECFORM=(FIXED,BLOCKED), DSNAME=your.syrtlogo.dataset.name, DISP=SHR, SERVREQ=(ADD,BROWSE) MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-13
  • 133. Coordination MainframeConnect for DB2/MVS-CICS version 11.1.1 Coordination System administrators at the mainframe, DirectConnect, and client need to coordinate troubleshooting efforts. To aid in your analysis, this section describes the processing flow from the client through DirectConnect to the mainframe. Processing Flow and Enterprise Connect Requirements Enterprise Connect processing can involve CT-Library, DB-Library, and ODBC. The following figure shows Enterprise Connect processing with DB-Library (for more information, see the DirectConnect for MVS Access Service User’s Guide): Figure 10-3: Processing flow: client-to-DirectConnect-to-mainframe The following points describe the sequence shown in Figure 10-3 and highlight Enterprise Connect requirements: 10-14 Troubleshooting
  • 134. MainframeConnect for DB2/MVS-CICS version 11.1.1 Coordination ® Note The following points describe both RPC and dynamic SQL processing flows. 1. Assuming DirectConnect is started, the client opens a LAN connection to a designated DirectConnect Service and logs in. If the message Server name not found in interface file occurs, make sure: - The client interfaces file is correctly set up. - The client Sybase path variable is correctly defined. - The DirectConnect server is specified in the DSQUERY variable. 2. On receiving the client login information, DirectConnect checks security as follows (for TRS only): - If security is turned on, DirectConnect ensures the client is authorized. If the client is not authorized, this error occurs: Security Violation: Login denied (no login entry). - If the client is authorized or security is turned off, DirectConnect acknowledges the login. 3. When the client application needs to invoke an RPC or language request on the mainframe, the client sends a request to DirectConnect over the LAN connection. 4. DirectConnect receives the request and performs a table lookup to find the mainframe session and Open ServerConnect transaction ID to use. The RPC and connection must be in the table. If security is turned on, the client must be authorized to use the RPC and connection to the mainframe. Provided that the table lookup and security check are successful, the line is up, and the session is active, DirectConnect allocates a conversation with the named transaction. If a failure occurs during this process, one of the following error messages is written to both the DirectConnect log and client: - Security Violation: Access to RPC ‘xxxx’ denied. The client is not authorized or is not listed correctly. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-15
  • 135. Coordination MainframeConnect for DB2/MVS-CICS version 11.1.1 - Request Rejected: No host connections are available. Connections to the mainframe are unavailable. - Request Rejected: Remote procedure ‘xxxx’ not found. The RPC name was entered incorrectly or the name is not in the lookup table. 5. DirectConnect sends the client’s External Data Representation (XDR) information and RPC parameters to the mainframe, and then waits for a reply from the transaction. 6. On the mainframe, the transaction processor initiates the named transaction, and the transaction issues Open ServerConnect Gateway-Library calls. These calls read the client’s XDR information and RPC parameters. The transaction also performs associated processing, such as issuing static SQL DB2 requests or reading VSAM or other database data. 7. The transaction issues Gateway-Library calls to send results back to the client. These calls perform any data conversions, generate the TDS reply datastream, and send out reply data. 8. DirectConnect receives each TDS reply packet and forwards it to the client, which continues until the Open ServerConnect transaction issues a TDSNDDON call. If a failure occurs during this process, an error message is written to the DirectConnect log. An “Unexpected EOF from SQL Server” message is written to the client. (The mainframe is acting as a SQL Server.) Gateway-Library tracing functions, if in use, also record errors in this process. See ‘‘Tracing’’ on page 10-11. 9. When completed with the request, the transaction exits; then the conversation terminates. For a long-running transaction (also called a user-defined transaction), the transaction can remain active through multiple requests before the conversation terminates. If a long-running transaction ends before it finishes processing, determine whether appropriate client support is set up. For example: - The client can be set up to disconnect after invoking the transaction and before the transaction ends. - SQL Server logs out after sending a client request and, therefore, does not support long-running transactions. 10-16 Troubleshooting
  • 136. MainframeConnect for DB2/MVS-CICS version 11.1.1 Coordination ® Note AMD2 supports user-defined transactions, which are comparable to long- running transactions based on Gateway-Library support. Process Flow During Attention Sequences Any of the following actions results in an attention sequence: • Database-Library issues a dbcancel( ) command. • A SQL user cancels processing while the server is sending results. • An APT program or form issues a closesql command. When an attention sequence is issued, the process flow is as follows: 1. Open Client issues an attention packet to DirectConnect, then discards anything else received until it receives a TDSDONE packet with the attention Ack bit on. 2. DirectConnect converts the attention packet into a SNA SIGNAL command, issuing an LU 6.2 request-to-send verb. DirectConnect then discards any results received from the mainframe until receiving a TDS DONE packet with the attention Ack bit on. 3. At the mainframe, CICS receives the SIGNAL command and informs Open ServerConnect. 4. Gateway-Library passes back a return code, indicating TDS_CANCEL_RECEIVED, on all subsequent TDSNDROW, TDSNDMSG, and TDSETPRM calls from an application. Any data associated with TDSNDROW or TDSNDMSG calls is discarded until the application issues a TDSNDDON call. For details on these calls, see the Open ServerConnect Programmer’s Reference. COBOL and PL/1 versions of this guide are available. 5. When the application issues a TDSNDDON call, Open ServerConnect support sends a TDS DONE packet with the attention Ack bit on. This ends the attention sequence. MainframeConnect for DB2/MVS-CICS Install & Admin Guide 10-17
  • 137. Coordination MainframeConnect for DB2/MVS-CICS version 11.1.1 10-18 Troubleshooting
  • 138. Appendixes
  • 139. A Error Messages A. This appendix describes provides general information about the messages that MainframeConnect returns. It also lists and describes each message, providing a probable cause and suggested course of action. Understanding the Messages This section provides the following information: • Message sources • How errors are logged • Interpreting the messages • Understanding TDSNDMSG properties Message Sources Two sources for MainframeConnect messages are: • MainframeConnect • Messages mapped to SQL Server MainframeConnect Messages The SQL transaction processing component of MainframeConnect returns messages identified by “MainframeConnect error.” These messages have a 5-digit message number and consist of two types: • DB2 messages forwarded from DB2 to the client • Internal messages generated by the SQL transaction processor AMD2 The AMD2 message table handles both types of messages. This message processing table, which consists of a translation table and a text table, is created during installation of MainframeConnect. It is an editable table that can be customized to suit customer requirements. For more information about the AMD2 message table and customizing MainframeConnect messages, see Chapter 8, “Customizing MainframeConnect Messages.” MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-1
  • 140. Understanding the Messages MainframeConnect for DB2/MVS-CICS version 11.1.1 DB2 Messages DB2 errors generate messages that are returned to AMD2. The AMD2 message table processes the DB2 SQLCODEs and forwards the DB2 message and any additional information, such as SQL codes, to the client. Internal Messages The AMD2 message table processes MainframeConnect internal messages and sends them to the client. Messages Mapped to SQL Server Messages MainframeConnect maps its messages to SQL Server messages where appropriate. The AMD2 message table, described in the previous section, performs this mapping. These messages are identified by 3- or 4-digit message numbers, compared to the 5-digit numbers used for the other messages. How Errors are Logged The AMD2 message table determines the logging of errors for MainframeConnect. If the translation table LOG property is Y for a given message, that message writes to the AMD2LOG error log. Like other parts of the message table, the value of the LOG property can be changed to meet a customer’s error logging requirements. AMD2LOG and AMD2LOGO are VSAM ESDS files installed as part of the product. Logged errors originally write to the AMD2LOG file. When AMD2LOG becomes full or does not accept messages for any reason, errors write to the overflow file, AMD2LOGO. When this occurs, you should close, archive (if desired), and purge the AMD2LOG file. While AMD2LOG is closed, errors write to AMD2LOGO. When AMD2LOG is reopened, the system programmer can close, archive, and purge AMD2LOGO. When AMD2LOGO is closed, errors automatically redirect to AMD2LOG. Defining Log Files to CICS The CICS system programmer must define the error log files to CICS in an FCT entry. This section shows sample FCT entries for AMD2LOG and AMD2LOGO. A-2 Error Messages
  • 141. MainframeConnect for DB2/MVS-CICS version 11.1.1 Understanding the Messages AMD2LOG: DFHFCT TYPE=DATASET, ACCMETH=VSAM, DATASET=AMD2LOG, RECFORM=(FIXED,BLOCKED), DSNAME=your.AMD2log.dataset.name, DISP=SHR, SERVREQ=(ADD,BROWSE) AMD2LOGO: DFHFCT TYPE=DATASET, ACCMETH=VSAM, DATASET=AMD2LOGO, RECFORM=(FIXED,BLOCKED), DSNAME=your.AMD2logo.dataset.name, DISP=SHR, SERVREQ=(ADD,BROWSE) Interpreting the Messages To help you understand what to do in response to a message, the messages are presented as follows: Error xxxxx Message text Explanation Why the error occurred Action The action we recommend to correct the problem If the action recommended does not correct the problem, you should do one of the following: - Run the error report facility for additional information about the error. - Rerun the failing situation with SDLC or Token-Ring trace activated. Message Source The source of the message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-3
  • 142. Understanding the Messages MainframeConnect for DB2/MVS-CICS version 11.1.1 In some cases, the message text uses different terms to refer to the products, as shown in the following table: Table A-1: Abbreviations for message text This abbreviation Stands for... DB2 Access Module MainframeConnect for DB2/MVS-CICS MainframeConnect MainframeConnect for DB2/MVS-CICS GWLib Gateway-Library MSG Transaction Router Service Library (formerly Mainframe Server Gateway) AMD2 The name of the MainframeConnect transaction AMD2LOG and The names of the MainframeConnect primary AMD2LOGO and backup error log files A-4 Error Messages
  • 143. MainframeConnect for DB2/MVS-CICS version 11.1.1 MainframeConnect Error Messages MainframeConnect Error Messages The MainframeConnect error messages are listed in numerical order on the following pages. MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-5
  • 144. Error 102 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 102 Incorrect syntax (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-6 Error Messages
  • 145. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 103 Error 103 String is too long (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-7
  • 146. Error 105 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 105 Unclosed quote (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-8 Error Messages
  • 147. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 106 Error 106 Too many table names (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-9
  • 148. Error 108 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 108 Order-by position is out of range of number of items in the select-list (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-10 Error Messages
  • 149. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 109 Error 109 There are more columns in the INSERT statement than values specified in the VALUES clause. The number of values in the VALUES clause must match the number of columns specified in the INSERT statement (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-11
  • 150. Error 131 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 131 Size exceeds maximum (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-12 Error Messages
  • 151. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 147 Error 147 Aggregate function may not appear in WHERE clause unless in subquery in HAVING clause (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-13
  • 152. Error 164 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 164 GROUP BY expressions must refer to column names that appear in the SELECT list (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-14 Error Messages
  • 153. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 183 Error 183 Scale out of range (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-15
  • 154. Error 189 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 189 Function has incorrect number of arguments (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-16 Error Messages
  • 155. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 191 Error 191 SQL statement nested too deeply, too long or too complex (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-17
  • 156. Error 193 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 193 Object or column name is too long (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-18 Error Messages
  • 157. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 206 Error 206 Operand type clash (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-19
  • 158. Error 207 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 207 Invalid column name (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-20 Error Messages
  • 159. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 209 Error 209 Ambiguous column name (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-21
  • 160. Error 220 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 220 Arithmetic overflow (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-22 Error Messages
  • 161. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 229 Error 229 Permission denied (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-23
  • 162. Error 233 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 233 Column may not be null (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-24 Error Messages
  • 163. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 241 Error 241 Syntax error converting DATETIME from character string (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-25
  • 164. Error 242 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 242 Conversion to DATETIME resulted in a DATETIME value out of range (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-26 Error Messages
  • 165. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 254 Error 254 Maximum number of columns exceeded (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-27
  • 166. Error 255 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 255 Maximum row size exceeded (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-28 Error Messages
  • 167. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 257 Error 257 Datatype conversion not allowed (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-29
  • 168. Error 264 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 264 Column name appears more than once (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-30 Error Messages
  • 169. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 267 Error 267 Object cannot be found (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-31
  • 170. Error 512 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 512 Subquery returned more than 1 value (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-32 Error Messages
  • 171. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 536 Error 536 Invalid length parameter passed to the substring function (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-33
  • 172. Error 546 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 546 Foreign key constraint violation occurred (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-34 Error Messages
  • 173. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 547 Error 547 Dependent foreign key constraint violation in a referential integrity constraint (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-35
  • 174. Error 550 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 550 The insert or update is not allowed because a resulting row does not satisfy the view definition. (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-36 Error Messages
  • 175. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 557 Error 557 Cursor cannot be found (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-37
  • 176. Error 558 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 558 Attempt to open a cursor which is already open (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-38 Error Messages
  • 177. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 559 Error 559 Attempt to issue a cursor which is not open (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-39
  • 178. Error 560 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 560 Cursor in Update or Delete is not positioned on a row (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-40 Error Messages
  • 179. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 593 Error 593 The UPDATE WHERE CURRENT OF to a cursor failed because the column being updated was not specified in the FOR UPDATE OF list (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-41
  • 180. Error 1903 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 1903 Index too large (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-42 Error Messages
  • 181. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 1904 Error 1904 Too many columns for index (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-43
  • 182. Error 2714 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 2714 Object already exists (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-44 Error Messages
  • 183. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 4403 Error 4403 View is not updatable (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-45
  • 184. Error 4409 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 4409 Columns in the query definition and the view definition do not match (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message A-46 Error Messages
  • 185. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 4607 Error 4607 Privilege may not be GRANTed or REVOKEd (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source AMD2 (module AMD2CAMX) call to DB2 that is mapped to a SQL Server message MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-47
  • 186. Error 30000 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 30000 DB2 Access Module DBMS error (DB2 %s failed: %S) Explanation Request failed. The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action See your DB2 documentation. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-48 Error Messages
  • 187. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 30001 Error 30001 DB2 Access Module DBMS warning (DB2 %s warning: %S) Explanation The cause is indicated by the DB2 message text and SQLCODE returned in the %S variable. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action No action required. This is only a warning. For more information, look up the message and SQLCODE in your DB2 documentation. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-49
  • 188. Error 30002 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 30002 DB2 Access Module DBMS confirm (DB2 %s completed successfully: %S) Explanation The DB2 request completed without errors. • %s is replaced by a string message variable value. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. Action No action required. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-50 Error Messages
  • 189. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 30003 Error 30003 DB2 Access Module DBMS info (DB2 completed SQLCODE = %d, SQLSTATE = %s) Explanation Informational message providing the SQLCODE and statement. • %d is the return code number. • %s is replaced by a string message variable value. Action No action. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-51
  • 190. Error 32000 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 32000 DB2 Access Module GWLib error (%s returned %d) Explanation An internal MainframeConnect error occurred. • %s is replaced by a string message variable value. • %d is the return code number. Action Record the return code, and contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) ® Note More than one type of error can generate this number. See “Error 32000” on page A-53 for more information. A-52 Error Messages
  • 191. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 32000 Error 32000 tds_ms error (tdinflog, etc) Explanation An internal MainframeConnect error occurred. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) ® Note More than one type of error can generate this number. See “Error 32000” on page A-52 for more information. MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-53
  • 192. Error 33214 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33214 DB2 Access Module error (Get storage failed) Explanation The AMD2 transaction was unable to get requested storage. CICS is running short on storage. Action Ask the CICS system programmer to increase the size of the DSA or EDSA storage pools in the CICS start-up procedure. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-54 Error Messages
  • 193. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33215 Error 33215 DB2 Access Module error (Illogical request in I/O routine. Request not honored because host cannot continue.) Explanation A MainframeConnect error. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-55
  • 194. Error 33216 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33216 DB2 Access Module error (Invalid request in I/O routine. Internal error.) Explanation A MainframeConnect error. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-56 Error Messages
  • 195. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33218 Error 33218 DB2 Access Module error (Rollback error) Explanation MainframeConnect received an error while attempting to roll back a transaction. Action Check the CICS and DB2 error logs to determine the reason for the rollback error. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-57
  • 196. Error 33219 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33219 DB2 Access Module error (Write to log file AMD2LOG failed, switching to overflow log AMD2LOGO) Explanation MainframeConnect is now writing messages to the secondary error log, AMD2LOGO. MainframeConnect is unable to write to the primary error log, AMD2LOG, possibly because it is full. Action No immediate action is required. Before AMD2LOGO fills up, you need to determine why the write to AMD2LOG failed and correct the condition. If AMD2LOG is full, follow your site's procedures for storing error log information; then delete the messages from AMD2LOG and reopen it. After you reopen AMD2LOG, MainframeConnect directs messages there. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-58 Error Messages
  • 197. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33220 Error 33220 DB2 Access Module error (Write to overflow log file AMD2LOGO failed. Error not logged.) Explanation MainframeConnect is unable to write to the overflow error log, AMD2LOGO, possibly because it is full. Action Determine why the write to AMD2LOGO failed and correct the condition. If AMD2LOGO is full: 1. Follow your site's procedures for storing message log information in AMD2LOGO and AMD2LOG. 2. Delete the archive or purge messages from AMD2LOGO and AMD2LOG. 3. Reopen AMD2LOG so that MainframeConnect redirects messages to AMD2LOG. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-59
  • 198. Error 33221 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33221 DB2 Access Module error (Datatype %d not supported) Explanation The specified datatype is not supported by MainframeConnect for DB2. %d is replaced by a numeric message variable value. Action The client must use a supported datatype in the request. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-60 Error Messages
  • 199. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33222 Error 33222 DB2 Access Module error (Illogical request in DB2 routine. Request not honored because DB2 cannot continue.) Explanation An error in the MainframeConnect code. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-61
  • 200. Error 33223 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33223 DB2 Access Module error (Invalid request in DB2 routine. Internal error.) Explanation An internal error. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-62 Error Messages
  • 201. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33224 Error 33224 DB2 Access Module error (No SQLDA. Internal error.) Explanation An internal error. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-63
  • 202. Error 33225 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33225 DB2 Access Module error (DB2 SQL statement too long.) Explanation The SQL statement received from the client exceeds the maximum number of characters allowed by MainframeConnect and DirectConnect. Action Requests sent by the client must be limited to fewer than 32,705 characters. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-64 Error Messages
  • 203. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33226 Error 33226 DB2 Access Module error (DB2 Invalid character in SQL statement at position %d) Explanation The request failed because it included an invalid character. %d is replaced by a numeric message variable value. Action Identify the invalid character and remove it; then resubmit the request. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-65
  • 204. Error 33227 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33227 DB2 Access Module error (No SQL statement.) Explanation MainframeConnect did not receive any SQL from the client. Action • If the client is an application, the client should resubmit the request. • If the client is SQL Server, the system administrator should check the stored procedure for errors. • If the client is an application other than SQL Server, check the application. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-66 Error Messages
  • 205. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33228 Error 33228 DB2 Access Module error (Long varchar column data truncated when truncation not allowed.) Explanation MainframeConnect retrieved a LongVarChar column with data greater than 255 bytes when TRS was set to prevent truncation of LongVarChar columns. Action Reset the truncate option when you start MSG or avoid fetching columns that exceed 255 bytes. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-67
  • 206. Error 33229 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33229 DB2 Access Module error (Stack overflow. Internal error.) Explanation MainframeConnect internal stack overflowed. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-68 Error Messages
  • 207. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33230 Error 33230 DB2 Access Module error (Abend, code = %s) Explanation If the abend code is AE49, the attachment facility did not start. %s is replaced by a string message variable value. Action For other abend codes, contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-69
  • 208. Error 33231 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33231 DB2 Access Module error (Message table not loaded or code not matched. Message code = %d, sql error = %S) Explanation MainframeConnect message table (module AMD2CAMX) could not be loaded, or the message code generated within MainframeConnect could not be matched in AMD2CAMX. This message always returns in U.S. English. • %S is replaced by the DB2 DSNTIAR message information, including the SQLCA message tokens and the SQLCODE. • %d is replaced by a numeric message variable value. Action Be sure AMD2CAMX is correctly defined to CICS. If AMD2CAMX was customized at your site, be sure no message codes are removed; otherwise, contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-70 Error Messages
  • 209. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33232 Error 33232 DB2 Access Module error (Default options will be used; failure in %s, error = %d) Explanation An internal error in a call prevented MainframeConnect from setting the options in the TDCUSTOM CSECT (control section, the Assembler verb starting the program) through the customization macro SYGWMCST. The default options are used. MainframeConnect issues this message each time it is invoked until the error is resolved, but it still processes incoming SQL. • %s is replaced by a string message variable value. • %d is replaced by a numeric message variable value. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-71
  • 210. Error 33233 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33233 DB2 Access Module error (Parsexit will not be invoked; failure in %s, error = %d) Explanation An internal error in a Gateway-Library call specifically for the parse exit routine failed. The parse exit routine is not invoked for this instance of the AMD2 transaction. MainframeConnect issues this message each time it is invoked until the error is resolved, but it still processes incoming SQL. • %s is replaced by a string message variable value. • %d is replaced by a numeric message variable value. Action Contact Sybase Technical Support. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-72 Error Messages
  • 211. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33234 Error 33234 DB2 Access Module error (Transactions cannot be labeled.) Explanation A transaction statement included a label. AMD2 does not support labels such as begin tran mytran, where mytran is a label for the transaction. Action If a transaction is in progress when AMD2 receives the invalid statement, MainframeConnect ignores it and the transaction continues. If a transaction is not in progress, then AMD2 issues a rollback and a transaction does not begin. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-73
  • 212. Error 33235 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33235 DB2 Access Module error (Transaction must be ended before another transaction is begun.) Explanation A begin tran statement was sent to AMD2 before the current transaction was terminated by commit, end tran or rollback. Action This error message is returned to the client, but the transaction remains active, waiting for the next SQL text to be sent. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-74 Error Messages
  • 213. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33236 Error 33236 DB2 Access Module error (BEGIN or END must be followed by TRAN or TRANSACTION.) Explanation A begin or end statement was sent to AMD2 without tran or transaction. Action MainframeConnect returns this error message to the client. If a transaction is in progress, it continues. If a transaction is not in progress, then another transaction does not begin. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-75
  • 214. Error 33242 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33242 DB2 Access Module error (Request or RSP not found.) Explanation MainframeConnect did not find the remote stored procedure (RSP) or host resident request specified in the use statement. Action Refer to the RSP. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-76 Error Messages
  • 215. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33300 Error 33300 DB2 Access Module error (No dynamic entries available.) Explanation MainframeConnect supports 1–50 dynamic requests. This limit was exceeded. Action Reduce the number of dynamic requests to 50 or less. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-77
  • 216. Error 33301 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33301 DB2 Access Module error (Selects not allowed for dynamic events.) Explanation The SQL entered for a dynamic event was a select statement, which is not allowed. Action To process a select statement, either execute it as a language request or open a cursor. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-78 Error Messages
  • 217. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33302 Error 33302 DB2 Access Module error (Invalid cursor event, %d, received.) Explanation An invalid cursor event was received from DirectConnect. The event number appears. This is an internal error. Action Report this information to your DirectConnect administrator. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-79
  • 218. Error 33303 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33303 DB2 Access Module error (Unable to declare cursor; all cursor ids are in use.) Explanation The maximum number of dynamic events are currently in a prepared state. Action Free at least one dynamic event name to prepare another dynamic event. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-80 Error Messages
  • 219. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33304 Error 33304 DB2 Access Module error (Declare cursor was not a select statement.) Explanation The SQL statement supplied when declaring a cursor must be a valid SQL select statement. Action Provide a valid select statement for the cursor request. For information, see your DB2 documentation. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-81
  • 220. Error 33305 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33305 DB2 Access Module error (Invalid cursor ID of %d supplied.) Explanation The cursor ID that the cursor request supplied does not match a cursor ID that was prepared by MainframeConnect. Action Make sure that a cursor with this ID is prepared before attempting to use the ID. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-82 Error Messages
  • 221. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33306 Error 33306 DB2 Access Module error (Unknown Open Server datatype %d supplied.) Explanation An attempt to send data of a type that is not recognized by MainframeConnect occurred. Action Change the client application to supply the correct datatype. See your DirectConnect documentation for more information. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-83
  • 222. Error 33307 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33307 DB2 Access Module error (Cursor name of %s does not match what was given in the update sql statement.) Explanation A cursor was prepared using one cursor name and the client tried to update the cursor using a different cursor name. Action Change the client application to specify the correct cursor names. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-84 Error Messages
  • 223. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33308 Error 33308 DB2 Access Module error (bad parms in bulk load.) Explanation MainframeConnect received bad parameters in a bulk load request. Action Try the transfer again. Message Source DB2 Access Module - AMD2 (module AMD2CAMX) MainframeConnect for DB2/MVS-CICS Install & Admin Guide A-85
  • 224. Error 33400 MainframeConnect for DB2/MVS-CICS version 11.1.1 Error 33400 Sample Parsexit message for sample parse exit: SQL Command was not a Select; batch aborted. Explanation The sample parse exit routine issues this message. The sample program rejects all incoming SQL except SELECT statements. Action For information about disabling the parse exit routine, see “Parse Exit Routine” in Chapter 9, “User Exits.” For information about changing the AMD2 message table, see “Changing the AMD2 Message Table” in Chapter 8, “Customizing MainframeConnect Messages.” Message Source DB2 Access Module - AMD2 (module AMD2CAMX) A-86 Error Messages
  • 225. B DB2 Database Administrator Information for TRS B. This section is intended for the DB2 database administrator. It describes Sybase-defined tables that store requested Catalog Stored Procedure (CSP) information that is not available in the DB2 catalog. This information is for application programs on personal computers and workstations. ® Note For comparable Access Service information, see the DirectConnect for MVS Access Service User’s Guide. This appendix contains the following sections: • Stored Procedures and DBMS B-1 • Keeping Server and Stored Procedure Information Current B-1 Stored Procedures and DBMS Several CSPs access tables that the DB2 database administrator maintains, including the tables shown in the following table. Table B-1: DB2 Database administrator-maintained tables Member Description sp_server_info The server, including capabilities and limitations sp_sproc_columns Stored procedures that an application can execute sp_stored_procedures Stored procedures executable from DirectConnect During installation of the CSPs, the tables that these CSPs query are created and populated. For details on the CSPs, see the DirectConnect for MVS Access Service User’s Guide. Keeping Server and Stored Procedure Information Current This section specifies changes to consider to keep server and stored procedure information current at your site. MainframeConnect for DB2/MVS-CICS Install & Admin Guide B-1
  • 226. Keeping Server and Stored Procedure Information Current MainframeConnect for DB2/MVS-CICS version 11.1.1 New Stored Procedures The CSPs, sp_capabilities and sp_thread_props, are included for OmniConnect support. • sp_capabilities returns information about the capabilities of the TRS so that OmniConnect knows how to format its DB2 statements correctly. • sp_thread_props returns minimal information at this time. Stored Procedure Names on DirectCONNECT sp_stored_procedures stores the names of procedures executable from DirectConnect. B-2 DB2 Database Administrator Information for TRS
  • 227. Glossary abend The abnormal ending of a task. access To obtain the use of a computer resource. access code A number or binary code assigned to programs, documents, or folders that allows authorized users to access them. Access Service Library (ACSLIB) A component of DirectConnect, a service library that provides access to non- Sybase data contained in a database management system or other type of repository. Each such repository is called a “target.” Each access service library interacts with exactly one target and is named accordingly. See also service library. ACF See Advanced Communications Function. ACSLIB See Access Service Library. Advanced Communications Function (ACF) A group of IBM licensed programs, principally VTAM programs, TCAM, NCP, and SSP, that use the concepts of Systems Network Architecture (SNA), including distribution of function and resource sharing. Advanced Peer-to-Peer Networking (APPN) An extension to SNA featuring (a) greater distributed network control that avoids critical hierarchical dependencies, thereby isolating the effects of single points of failure; (b) dynamic exchange of network topology information to foster ease of connection, reconfiguration, and adaptive route selection; (c) dynamic definition of network resources; and (d) automated resource registration and directory lookup. APPN extends the LU 6.2 peer orientation for end-user services to network control and supports multiple LU types, including LU 2, LU 3, and LU 6.2. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-1
  • 228. MainframeConnect for DB2/MVS-CICS version 11.1.1 advanced program-to-program communication (APPC) Hardware and software that characterize the LU 6.2 architecture and its various implementations in products. See also logical unit 6.2. algorithm An ordered set of well-defined rules for the solution of a problem in a finite number of steps. American Standard Code for Information Interchange See ASCII. APAR See authorized program analysis report. API See application program interface. APPC See advanced program-to-program communication. APPC communications link Hardware and software configured to enable a remote transaction program to establish an APPC conversation with a partner transaction program in an SNA network. See also Systems Network Architecture. APPN See Advanced Peer-to-Peer Networking. application The use to which an information processing system is put; for example, a payroll application, an airline reservation application, a network application. application plan The control structure produced during the bind process and used by the DB2 program to process SQL statements during application execution. application program A program that is specific to the solution of an application problem. Glossary-2
  • 229. MainframeConnect for DB2/MVS-CICS version 11.1.1 application program interface (API) A functional interface, supplied by an operating system or other licensed program, that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program. application programmer A programmer who designs programming systems and other applications for a user that applies to the user’s work. APT See automatically programmed tools. argument A value supplied to a function or procedure that is required to evaluate the function. ASCII (American Standard Code for Information Interchange) A 7-bit standard code that permits transmittal of text, numbers, and some special characters among systems. Characters are represented by the numbers between 32 and 127, inclusive. The set includes uppercase and lowercase letters, numbers, and frequently-used special characters (such as $ & ; : # . ,). assemble To translate an assembly language program into an object program. assembler language A source language that includes symbolic machine language statements in which there is a one-to-one correspondence with the instruction formats and data formats of the computer. attach To connect a device logically to a ring network. authority The right to access objects, resources, or functions. authorized program analysis report (APAR) A report of a problem caused by a suspected defect in a current unaltered release of a program. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-3
  • 230. MainframeConnect for DB2/MVS-CICS version 11.1.1 automatically programmed tools (APT) A programming language for numerically-controlled machine tools. auxiliary storage All addressable storage, other than main storage, that can be accessed by means of an input/output channel; for example, storage on magnetic tape or direct access devices. batch A group of records or data processing jobs brought together for processing or transmission. base tape See Open ServerConnect for CICS/MVS base tape. bind SQL statements from a compiled mainframe program where the access to DB2 was optimized and saved as static SQL in an application plan. block In programming languages, a compound statement that coincides with the scope of at least one of the declarations contained within it. A block can also specify storage allocation or segment programs for other purposes. block size The number of data elements in a block. bridge In the connection of local loops, channels, or rings, the equipment and techniques used to match circuits and to facilitate accurate data transmission. A bridge connects networks or systems of the same or similar architectures, whereas a gateway connects networks or systems of different architectures. Contrast with gateway, router. call The action of bringing a computer program, a routine, or a subroutine into effect, usually by specifying the entry conditions and jumping to an entry point. catalog A system table that contains information about objects in a database, such as tables, views, columns, and authorizations. Glossary-4
  • 231. MainframeConnect for DB2/MVS-CICS version 11.1.1 Catalog Stored Procedure (CSP) A procedure that provides information about tables, columns, and authorizations. It is used in SQL generation and application development. chain A group of logically-linked user data records processed by LU 6.2. channel-attached Devices attached to a controlling unit by cables, rather than by telecommunication lines. character data Data in the form of letters and special characters, such as punctuation marks. character set A set of specific (usually standardized) characters with an encoding scheme that uniquely defines each character. ASCII is a common character set. character string A sequence of consecutive characters that are used as a value. CICS See Customer Information Control System. CICS region The CICS area of the computer system in which an application is running. client In client/server systems, the part of the system that sends requests to servers and processes the results of those requests. See also client/server. Contrast with server. client application Software that is responsible for the user interface, including menus, data entry screens, and report formats or an application that sends requests to another application that acts as a server. See also client, client/server, server. client/server An architecture in which the client is an application that handles the user interface and local data manipulation functions, while the server provides data processing access and management for multiple clients. See also client application. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-5
  • 232. MainframeConnect for DB2/MVS-CICS version 11.1.1 Client Services Application (CSA) A customer-written CICS program initiated on the host that uses the Sybase API to invoke MainframeConnect for DB2 as a client to MainframeConnect or to SQL Server. See also application program interface. cluster A station that consists of a control unit (a cluster controller) and the terminals attached to it. cluster controller A device that can control the input/output operations of more than one device connected to it. A cluster controller can be controlled by a program stored and executed in the unit, or it can be entirely controlled by hardware. COBOL (common business-oriented language) A high-level programming language, based on English, that is used primarily for business applications. code page An assignment of graphic characters and control function meanings to all code point. command An order for an action to take place. command level An operation performed for a particular command in a program. commit An instruction to a database to make permanent all changes made to one or more database files since the last commit or rollback operation, and to make the changed records available to other users. Contrast with rollback. common area A control section used to reserve a main storage area that can be referred to by other modules. common business-oriented language See COBOL. Glossary-6
  • 233. MainframeConnect for DB2/MVS-CICS version 11.1.1 compatibility The capability of a hardware or software component to conform with the interface requirements of a given data processing system without adversely affecting its functions. compile To translate all or part of a program that is expressed in a high-level language into a computer program that is expressed in an intermediate language, an assembly language, or a machine language. concatenation To append one term to another to make a combined term. For example, aaaabbb is a concatenation of aaaa and bbb. configure To define to a system the devices, optional features, and programs installed on the system. connectivity The capability to attach a variety of functional units without modifying them. control section (CSECT) The part of a program specified by the programmer to be a relocatable unit, all elements of which are to be loaded into adjoining main storage locations. control statement In programming languages, a statement that is used to alter the continuous sequential execution of statements; a control statement may be a conditional statement, or an imperative statement. conversation a) A dialog between a user and an interactive data processing system. b) Within the context of APPC, an exchange of information or a sequence of messages sent between two transaction programs. Conversations take place between two LUs over an established session. Also, a sequence of messages sent between two applications (for instance, client application and SQL Server). CSECT See control section. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-7
  • 234. MainframeConnect for DB2/MVS-CICS version 11.1.1 CSP See Catalog Stored Procedure. cursor In SQL, a named control structure used by an application program to point to a row of data. The position of the row is within a table or view, and the cursor is used interactively to select rows from the columns. Customer Information Control System (CICS) An IBM licensed program that enables transactions entered at remote terminals to be processed concurrently by user-written application programs. It includes facilities for building, using, and maintaining databases. DASD See direct access storage device. data area A storage area used by a program or device to hold information. database A set of related data tables and other database objects that are organized and presented to serve a specific purpose. database management system (DBMS) A computer-based system for defining, creating, manipulating, controlling, managing, and using databases. The software for using a database can be part of the database management system, or it can be a stand-alone database system. Database 2 (DB2) An IBM relational database management system. data definition statement (DD statement) A job control statement describing a data set associated with a specific job step. See job control language. data object In a program, an element of data structure, such as a file, array, or operand, that is needed for the execution of a program and that is named or otherwise specified by the allowable character set of the language in which the program is coded. Glossary-8
  • 235. MainframeConnect for DB2/MVS-CICS version 11.1.1 data queue An object that communicates and stores data used by several programs in a job or between jobs. data record A collection of items of information from the standpoint of its use in an application, as the user supplies it. The data record is stored physically separate from its associated control information in a control interval. dataset The major unit of data storage and retrieval, consisting of a collection of data in one of several prescribed arrangements and described by control information to which the system has access. dataset name The term or phrase used to identify a dataset. data source A collection of data, such as a database. datatype In programming languages, a set of values together with a set of permitted operations. DBCS See double-byte character set. DB-Library A Sybase and Microsoft API that allows client applications to interact with ODS applications. See also application program interface. DBMS See database management system. DB2 See Database 2. DD statement See data definition statement. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-9
  • 236. MainframeConnect for DB2/MVS-CICS version 11.1.1 debug To detect, locate, and eliminate errors in computer programs. decode To convert data by reversing the effect of some previous encoding. delimiter A character that groups or separates words or values in a line of input. direct access storage device (DASD) A device in which access time is effectively independent of the location of the data. DirectConnect A Sybase Open Server application that provides access management for non- Sybase databases, copy management (transfer), and remote systems management. Each DirectConnect consists of a server and one or more service libraries to provide access to a specific data source. DirectConnect replaces the products “MDI Database Gateway” and “Net-Gateway.” DirectConnect Configuration Tool A Sybase Windows application that provides remote management capabilities for DirectConnect products. These capabilities include starting, stopping, creating, and copying services. DirectConnect for MVS A Sybase LAN-based solution that communicates with mainframe host components. It incorporates the functionality of the MDI Database Gateway and the Sybase Net-Gateway and includes LU 6.2 and TCP/IP support. directory A type of file containing the names and controlling information for other files or other directories. disk volume A disk pack or part of a disk storage module. distributed database A database that is physically decentralized and handled by a database management system in a way that provides a logically centralized view of the database to the user. Glossary-10
  • 237. MainframeConnect for DB2/MVS-CICS version 11.1.1 double-byte character set (DBCS) A set of characters in which each character is represented by 2 bytes. Languages such as Japanese, Chinese, and Korean, which contain more symbols than can be represented by 256 code points, require double-byte character sets. Because each character requires 2 bytes, the typing, display, and printing of DBCS characters requires hardware and programs that support DBCS. Contrast with single-byte character set. driver A system or device that enables a functional unit to operate. dump To record, at a particular moment, the contents of all or part of one storage device in another storage device. Dumping is usually for the purpose of debugging. dynamic SQL Pertaining to the preparation and processing of SQL source statements within a program while the program runs. The SQL source statements are contained in host-language variables rather than being coded directly into the application program. The SQL statement can change several times while the program runs. Contrast with static SQL. EBCDIC (Extended Binary-Coded Decimal Interchange Code) A coded character set of 256 8-bit characters. echo In data communication, a reflected signal on a communications channel. On a communications terminal, each signal is displayed twice, once when entered at the local terminal and again when returned over the communications link. This allows the signals to be checked for accuracy. embedded SQL (ESQL) SQL statements that are embedded within a program and are prepared in the program preparation process before the program runs. After it is prepared, the statement itself does not change, although values of host variables specified within the statement might change. enable In interactive communications, to load and start a subsystem, or to design a product in such a way as to facilitate the inclusion of national language functions. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-11
  • 238. MainframeConnect for DB2/MVS-CICS version 11.1.1 end-of-file A coded character recorded on a data medium to indicate the end of the medium or end of data. Enterprise Connect The encompassing architecture upon which Sybase implements heterogeneous data integration. Compare with DirectConnect. environment variable A variable that describes how an operating system runs and the devices it recognizes. error log A dataset or file in a product or system where error information is stored for later access. error message A message that a program issues, usually to the client application, when it detects an error condition. ESQL See embedded SQL. execute To carry out an instruction. exit routine A user-written routine that receives control at predefined user exit points. expression In programming languages, a language construct for computing a value from one or more operands; for example, literals, identifiers, array references, and function calls. Extended Binary-Coded Decimal Interchange Code See EBCDIC. FCT See forms control table. Glossary-12
  • 239. MainframeConnect for DB2/MVS-CICS version 11.1.1 field The smallest identifiable part of a record. file A collection of related data that is stored and retrieved by an assigned name. fixed-length record A record having the same length as all other records with which it is logically or physically associated. Contrast with variable-length record. FMH See function management header. format In programming languages, a language construct that specifies the representation, in character form, of data objects in a file. forms control table (FCT) An object that contains the special processing requirements for output data streams received from a host system by a remote session. fullword A word suitable for processing by a given computer, usually treated as a unit. function management header (FMH) One or more headers, optionally present in the leading request units (RUs) of an RU chain, that allow one LU to (a) select a transaction program or device at the session partner and control the way in which the end-user data it sends is handled at the destination, (b) change the destination or the characteristics of the data during the session, and (c) transmit between session partners status or user information about the destination (for example, a program or device). Function management headers can be used with LU type 1, 4, and 6.2 protocols. gateway Connectivity software that allows two or more computer systems with different network architectures to communicate. Contrast with bridge, router. globalization The combination of internationalization and localization. See also internationalization, localization. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-13
  • 240. MainframeConnect for DB2/MVS-CICS version 11.1.1 global variable A variable defined in one portion of a computer program and used in at least one other portion of the computer program. Contrast with local variable. graphical user interface (GUI) A type of computer interface consisting of a visual metaphor of a real-world scene, often of a desktop. Within that scene are icons, representing actual objects, that the user can access and manipulate with a pointing device. group ID A combination of alphanumeric characters that corresponds to a specific group name. The group ID can often be substituted in commands that take a group name as a value. GUI See graphical user interface. halfword A contiguous sequence of bits or characters that constitutes half a computer word and can be addressed as a unit. handler A routine that controls a program’s reaction to specific external events; for example, an interrupt handler. hexadecimal A system of numbers to the base 16; hexadecimal digits range from 0 through 9 and A through F, where A represents 10 and F represents 16. host The mainframe or other machine on which a database, an application, or a program resides. IMS See Information Management System. index A list of the contents of a file or of a document, together with keys or references for locating the contents. Glossary-14
  • 241. MainframeConnect for DB2/MVS-CICS version 11.1.1 Information Management System (IMS) A database/data communication (DB/DC) system that can manage complex databases and networks. interface Hardware, software, or both, that links systems, programs, or devices. internationalization The process of extracting locale-specific components from the source code and moving them into one or more separate modules, making the code culturally neutral so it may be localized for a specific culture. See also globalization. Contrast with localization. International Organization for Standardization (ISO) An organization of national standards bodies from various countries established to facilitate international exchange of goods and services, and develop cooperation in intellectual, scientific, technological, and economic activity. invoke To start a command, procedure, or program. ISO See International Organization for Standardization. Japanese Conversion Module A component of MainframeConnect that enables Open ServerConnect applications and the DB2 Access Module AMD2 transaction to convert data that passes between the mainframe and client using kanji and hankaku-katakana. JCL See job control language. job A collection of related programs, identified by appropriate job control statements. job control language (JCL) In MVS, a control language used to identify a job to an operating system and to describe the job’s requirements. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-15
  • 242. MainframeConnect for DB2/MVS-CICS version 11.1.1 kanji A graphic character set consisting of symbols used in Japanese idiographic alphabets. Each character is represented by 2 bytes. keyword In programming languages, a lexical unit that, in certain contexts, characterizes some language construct; a keyword normally has the form of an identifier. LAN See local area network. length The number of characters in a character string. library a) A named area on disk that can contain programs and related information (not files). A library consists of different sections, called library members. b) A partitioned dataset containing file members for the mainframe. library member A named collection of records or statements in a library. line feed The movement of the print or display position to the corresponding position on the next line. linkage In computer security, combining data or information from one information system with data or information from another system with the intention to derive additional information; for example, the combination of computer files from two or more sources. linkage editor A computer program for creating load modules from one or more object modules or creating load modules by resolving cross references among the modules and, if necessary, adjusting addresses. link-edit To create a loadable computer program by means of a linkage editor. See also linkage editor. Glossary-16
  • 243. MainframeConnect for DB2/MVS-CICS version 11.1.1 load module All or part of a computer program in a form suitable for loading into main storage for execution. A load module is usually the output of a linkage editor. local area network (LAN) A computer network located on the user’s premises and covering a limited geographical area. Communication within a local area network is not subject to external regulations; however, communication across the LAN boundary can be subject to some form of regulation. localization The process of preparing an extracted module for a target environment. The following items are addressed: messages are displayed and logged in the user’s language; numbers, money, dates, and time are represented using the user’s cultural convention; and documents are displayed in the user’s language. See also globalization. Contrast with internationalization. local variable A variable that is defined and used only in one specified portion of a computer program. Contrast with global variable. log file The log file maintained by the MainframeConnect Server. The server log file contains entries of events for each service managed by the MainframeConnect Server. logical unit (LU) A type of network-accessible unit that enables end users to gain access to network resources and communicate with each other. logical unit 6.2 (LU 6.2) A type of logical unit that supports general communication between programs in a distributed processing environment. See also advanced program-to-program communication. login The act of gaining access to a computer system by entering identification and authentication information at the workstation. LU See logical unit. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-17
  • 244. MainframeConnect for DB2/MVS-CICS version 11.1.1 LU 6.2 See logical unit 6.2. macro An instruction in a source language that is to be replaced by a defined sequence of instructions in the same source language and that can also specify values for parameters in the replaced instructions. mainframe A large computer, in particular one to which other computers can be connected so that they can share facilities the mainframe provides; for example, a System/370 computing system to which personal computers are attached so that they can upload and download programs and data. Mainframe Access Products Sybase products that enable client applications to communicate with mainframes in a client/server environment. See client/server. MainframeConnect for DB2/MVS-CICS A Sybase mainframe solution that provides dynamic access to DB2 data. It replaces the OmniSQL Access Module for DB2 and the functionality in the MDI Access Server. See also Customer Information Control System, Database 2, Multiple Virtual Storage. main storage Program-addressable storage from which instructions and other data can be loaded directly into registers for subsequent execution or processing. map A set of values that have defined correspondence with the quantities or values of another set. member A partition of a partitioned dataset. message number The number that uniquely identifies an error message. migration Installation of a new version or release of a program to replace an earlier version or release. Glossary-18
  • 245. MainframeConnect for DB2/MVS-CICS version 11.1.1 module A program unit that is discrete and identifiable with respect to compiling, combining with other units, and loading; for example, the input to or output from an assembler, compiler, linkage editor, or executive routine. Multiple Virtual Storage (MVS) An IBM operating system that runs on most System/370 and System/390 mainframes. It supports 24-bit addressing up to 16 megabytes. Multiple Virtual Storage/Enterprise Systems Architecture (MVS/ESA) An IBM operating system that extends virtual memory to 16 terabytes. It allows larger applications, such as DB2, to run more efficiently. Multiple Virtual Storage/Extended Architecture (MVS/XA) A version of MVS that supports 31-bit addressing of up to 2 gigabytes. MVS See Multiple Virtual Storage. MVS/ESA See Multiple Virtual Storage/Enterprise Systems Architecture. MVS/XA See Multiple Virtual Storage/Extended Architecture. NCP See Network Control Program. Net-Gateway A Sybase product that provides communication between a mainframe and a LAN server. Net-Gateway is the “ancestor” of the DirectConnect Transaction Router Service. nest To incorporate one or more structures of one kind into a structure of the same kind; for example, to nest one loop (the nested or inner loop) within another loop (the nesting or outer loop); to nest one subroutine within another subroutine. network A configuration of data processing devices and software connected for information exchange. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-19
  • 246. MainframeConnect for DB2/MVS-CICS version 11.1.1 Network Control Program (NCP) An IBM licensed program that provides communication controller support for single domain, multiple-domain, and interConnected network capability. null A pointer that does not point to a data object. OAM See Omni Access Module. object A passive entity that contains or receives information but cannot change the information it contains. In MainframeConnect, objects include rows, tables, databases, stored procedures, triggers, defaults, and views. object code Output from a compiler or assembler that is also executable machine code or is suitable for processing to produce executable machine code. Contrast with source code. ODBC See Open Database Connectivity. Omni Access Module (OAM) Provides built-in access to ISAM, RMS, and SQL Server. Open Client A Sybase product that provides customer applications, third-party products, and other Sybase products with the interfaces required to communicate with Open Client and Open Server applications. Open Client application An application written using Open Client libraries. Open ClientConnect A Sybase product that provides capability for the mainframe to act as a client to LAN-based resources. See client. Glossary-20
  • 247. MainframeConnect for DB2/MVS-CICS version 11.1.1 Open Database Connectivity (ODBC) A Microsoft API that allows access to both relational and non-relational databases. ODBC allows client application developers to produce vendor-neutral Windows applications that can access data sources without including code for a specific database. See also application program interface. Open Server A Sybase product that provides the tools and interfaces required to create a custom server. For example, clients can route requests to DirectConnect, which is an Open Server application that they configured to meet specific needs, such as the preprocessing of SQL statements or decision making about routing RPCs to Transaction Router Service for DB2 or to other servers. See the Open Server documentation for information about this product. Open ServerConnect A Sybase product that provides capability for programmatic access to mainframe data. Open ServerConnect for CICS/MVS base tape An installation tape that installs the portion of Open ServerConnect that is required by MainframeConnect to operate correctly. overwrite To write into an area of storage, thereby destroying the data previously stored in the same area. parameter A variable that is given a constant value for a specified application and that can denote the application. Contrast with property. parse In systems with time sharing, to analyze the operands entered with a command and create a parameter list for the command processor from the information. pipe To direct data so that the output from one process becomes the input to another process. The standard output of one command can be connected to the standard input of another with the pipe operator (|). Two commands connected in this way constitute a pipeline. platform The operating system environment in which a program runs. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-21
  • 248. MainframeConnect for DB2/MVS-CICS version 11.1.1 PL/I See Programming Language/I. pointer A data element that indicates the location of another data element. poll To determine whether any remote device on a telecommunication line is ready to transmit data. precompile To process programs containing SQL statements before they are compiled. SQL statements are replaced with statements that will be recognized by the host language compiler. The output from this precompile includes source code that can be submitted to the compiler and used in the bind process. program A sequence of instructions that a computer can interpret and execute. programming language An artificial language for expressing computer programs. Programming Language/I (PL/I) A programming language designed for use in a wide range of commercial and scientific computer applications. property A setting for a server or service that defines the characteristics of the service, such as how events are logged or how datatypes are converted. Contrast with parameter. protocol A set of rules that governs the behavior of computers communicating on a network. pseudocode A set of instructions that is logically structured but does not follow the syntax of any particular programming language. RDBMS See relational database management system. Glossary-22
  • 249. MainframeConnect for DB2/MVS-CICS version 11.1.1 record A set of one or more related data items grouped for processing. relational database A database in which data is viewed as being stored in tables consisting of columns (data items) and rows (units of information). Data from different tables can be combined to form new data relationships. relational database management system (RDBMS) An application that controls relational databases. See also relational database. Contrast with database management system. remote procedure call (RPC) A stored procedure executed on a different MainframeConnect server from the one onto which a user is logged. remote stored procedure (RSP) A customer-written CICS program that resides on the mainframe and communicates with MainframeConnect for DB2/MVS. See also Customer Information Control System. Contrast with Client Services Application. request One or more database operations the application sends as a unit to the database. During a request, the application gives up control to the DBMS and waits for its response. Depending upon the response, the application commits or rolls back the request. One or more requests can be grouped into a single unit of work. See also commit, rollback. resource table A main storage table that associates each resource identifier with an external logical unit (LU) or application program. return code A value returned to a program to indicate the results of an operation requested by that program. rollback An instruction to a database to back out of the changes requested in a unit of work. Contrast with commit. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-23
  • 250. MainframeConnect for DB2/MVS-CICS version 11.1.1 router An attaching device that connects two LAN segments, which use similar or different architectures, at the OSI reference model network layer. Contrast with bridge, gateway. routine A program, or part of a program, that can have general or frequent use. RPC See remote procedure call. RSP See remote stored procedure. SBCS See single-byte character set. server A functional unit that provides shared services to workstations over a network. Contrast with client. See client/server. service A functionality available to DirectConnect applications. It is the pairing of a service library and a set of specific configuration properties. service library A set of configuration properties that determine service functionality. Examples of service libraries include access service libraries, transfer service libraries, administrative service libraries, and transaction router service libraries. See also Access Service Library. shell A command interpreter that acts as an interface between the user and the operating system. A shell can contain another shell nested inside it; the outer shell is the parent shell and the inner shell is the child. single-byte character set (SBCS) A character set in which each character is represented by a 1-byte code. Contrast with double-byte character set. Glossary-24
  • 251. MainframeConnect for DB2/MVS-CICS version 11.1.1 SNA See Systems Network Architecture. socket A unique host identifier created by the concatenation of a port identifier with a TCP/IP address. source code The input to a compiler or assembler, written in a source language. Contrast with object code. source language A language from which statements are translated. SPAREA (Stored Procedure Communication Area) An area in which a CSA exchanges information with Open ClientConnect. SQL See structured query language. SQLDA (SQL descriptor area) A set of variables used in the processing of certain SQL statements. The SQLDA is intended for dynamic SQL programs. SQL descriptor area See SQLDA. SQL Server The server in the Sybase Client-Server architecture. It manages multiple databases and multiple users, tracks the actual location of data on disks, maintains mapping of logical data description to physical data storage, and maintains data and procedure caches in memory. staging The movement of data from an off-line or low-priority device back to an online or higher-priority device, usually on demand of the system or on request of a user. stand-alone An operation that is independent of any other device, program, or system. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-25
  • 252. MainframeConnect for DB2/MVS-CICS version 11.1.1 standard input (STD input) The primary source of data entered into a command. Standard input comes from the keyboard unless redirection or piping is used, in which case standard input can be from a file or the output from another command. statement A basic unit of SQL, which is a single SQL operation, such as select, update, or delete. static SQL SQL statements that are embedded within a program and are prepared during the program preparation process before the program runs. After being prepared, the statement itself does not change, although values of host variables specified by the statement can change. Contrast with dynamic SQL. STD input See standard input. Stored Procedure Communication Area See SPAREA. string In programming languages, the form of data used for storing and manipulating text. For example, in PL/I, a string is a sequence of characters or bits that is treated as a single data item; and in SQL, a string is a character string. structured field A mechanism that permits variable-length data or non-3270 data to be encoded for transmission in the 3270 data stream. structured query language (SQL) An IBM industry-standard language for processing data in a relational database. stub A program module that transfers remote procedure calls and responses between a client and a server. See client, server. syntax The rules for how to construct a statement. Glossary-26
  • 253. MainframeConnect for DB2/MVS-CICS version 11.1.1 Systems Administrator A user authorized to handle MainframeConnect system administration, including creating user accounts, assigning permissions, and creating new databases. Systems Network Architecture (SNA) An IBM proprietary plan for the logical structure, formats, protocols, and operational sequences for transmitting information units through networks and controlling network configuration and operation. See also advanced program-to- program communication. Systems Programmer A programmer who plans, generates, maintains, extends, and controls the use of an operating system with the aim of improving overall productivity of an installation. table An array of data or a named data object that contains a specific number of unordered rows. Each item in a row can be unambiguously identified by means of one or more arguments. TCP/IP See Transmission Control Protocol/Internet Protocol. temporary storage In computer programming, storage locations reserved for intermediate results. Time Sharing Option (TSO) An operating system option for the System/370 system; the option provides interactive time sharing from remote terminals. See also Customer Information Control System. transaction An exchange between a program on a local system and a program on a remote system that accomplishes a particular action or result. transfer A DirectConnect feature that allows users to move data or copies of data from one database to another. transient A program or subroutine that does not reside in main storage or in a temporary storage area for such a program. MainframeConnect for DB2/MVS-CICS Install & Admin Guide Glossary-27
  • 254. MainframeConnect for DB2/MVS-CICS version 11.1.1 Transmission Control Protocol/Internet Protocol (TCP/IP)) A set of communication protocols that supports peer-to-peer connectivity functions for both local and wide area networks. troubleshoot To detect, locate, and eliminate errors in computer programs or faults in hardware. TSO See Time Sharing Option. uppercase Pertaining to the capital letters, as distinguished from the small letters; for example, A, B, G, rather than a, b, g. variable An entity that is assigned a value. DirectConnect has two kinds of variables, called local variables and global variables. variable-length record A record having a length independent of the length of other records with which it is logically or physically associated. Contrast with fixed-length record. Virtual Storage Access Method (VSAM) An IBM licensed program that controls communication and the flow of data in an SNA network. It provides single-domain, multiple-domain, and interconnected network capability. Virtual Telecommunications Access Method (VTAM) A set of programs that maintain control of the communication between terminals and application programs running under DOS/VS, OS/VS1, OS/VS2, and MVS operating systems. VSAM See Virtual Storage Access Method. VTAM See Virtual Telecommunications Access Method. workstation A terminal, microcomputer, or personal computer usually one that is connected to a mainframe or to a network, at which a user can perform tasks. Glossary-28
  • 255. Index Symbols AMD2PXIT member 5-7 AMD2PXIT sample validation program 9-3 %d message variable indicator 8-6 AMD2RACF member 5-8, 7-5 %S message variable indicator 8-6 AMD2RDO3 member 5-6 %s message variable indicator 8-6 AMD2RDO member 5-6 AMD2TOP member 5-8 Numerics AMD2 transaction processor 2-4 AMD2TS member 7-5 33231 error message 8-6, 9-20 AMD2XCOB-CA- fields 9-15 AMD2XCOB copy book 9-1, 9-14 AMD2XCOB member 5-6 A Application plan, authorizing users 5-4 ACF2 APT Workbench 2-5 AMD2ACF2 group ID exit name 7-5 Assembler, coding parse exit AMD2ACF2 member 5-8 routine 9-16 mainframe product 2-5 Assigning return codes 9-19 Altering SQL text 9-17 Attention sequence 10-17 AMCF command 7-1 Authorize users AMD2 for application plan 5-4 returning after user exit 9-13 for DB2 packages 5-4 AMD2ACE member 5-7 for system tables 5-5 AMD2ACF2 member 5-8, 7-5 AMD2CAMX member 5-8, 5-9 AMD2CAMX module 4-3, 8-2 B AMD2CCPX member 5-9 begin tran statement 9-13 AMD2CCPX sample parse exit routine 9-16 BINDPKG member 5-7 AMD2CFG member 5-7, 5-8 BINDPLAN member 5-7 AMD2CHAB member 5-8 Book, COBOL copy 9-13 AMD2CICS member 5-8 AMD2CM member 5-8 AMD2 command 5-5 C AMD2DB2 member 5-7 Changes AMD2DSN member 5-8 to DirectConnect stored procedure AMD2HRCT member 5-6 name B-2 AMD2LOG error log 10-12 to MainframeConnect from prior AMD2LOG member 5-7 products 4-1 AMD2LOGO error overflow file 10-12 Character sets AMD2MAMT macro 8-2 customization on AMD2MAMX macro 8-2 MainframeCnnect 2-2 AMD2 messages. See Messages CHARSETCLT field 9-15 AMD2MSG member 5-7 CHARSETSRV field 9-15 MainframeConnect for DB2/MVS-CICS Install & Admin Guide Index-1
  • 256. MainframeConnect for DB2/MVS-CICS version 11.1.1 Checklists, preinstallation 3-2 PASSWORD 9-12, 9-15 CICS RESERVED 9-16 configuration 3-7 RETCODE 9-12, 9-16, 9-19 defining SYRT error logs to CICS A-2 STMT-PTR 9-12, 9-15 MainframeConnect default USERID 9-12, 9-15 transaction name 2-4 Common area of the parse exit mainframe product 2-5 routine 9-13 sample FCT entries for SYRT error Common problems 10-3 logs A-3 Communicating with other products troubleshooting 10-9 client applications 2-5 CICS common area fields. See Common DirectConnect 2-5 area fields other servers 2-5 CICS PPT entry 9-3 Communication area CICS system programmer CSP exit program 9-10 MainframeConnect tape tasks 5-1, 5-3 in request validation exit 9-5 TRS CSP tasks 6-1, 6-2 in result validation exit 9-5 ClearConnect Communication path capabilities 1-8 DB2 Access Module 2-5 description 1-9 MainframeConnect 2-5 use with DRDA 1-8 Communications Client applications, communicating See DirectConnect communications with other products 2-5 See Mainframe communications COBOL, coding parse exit routine 9-16 with other products 2-4 COBOL copy book 9-13, 9-14 Compatibility 3-6 Coding Compiling parse exit routines 9-20 changes to messages 8-11 Components of DB2 Access Module 2-3 parse exit routines 9-16 CompuServe Columns, non-truncated 2-3 Sybase online information xxiii Commands Configuring CICS 3-7 AMCF 7-1 Configuring MainframeConnect AMD2 5-5 changing settings 7-1 EXEC CICS LINK 9-1, 9-2, 9-12 understanding parameters 7-3 FREEMAIN 9-19 Connectivity GETMAIN 9-18 in MainframeConnect 2-1 commit statement 9-13 preinstallation checklist 3-6 Common area fields verifying 10-1 altering values 9-12 Considerations for DBA-maintained CHARSETCLT 9-15 tables B-1 CHARSETSRV 9-15 Contacting Sybase technical support xix DBCS 9-15 Coordination of troubleshooting 10-14 EYECATCHER 9-15 Copy books MSGCODE 9-12, 9-16, 9-19 AMD2XCOB 9-1, 9-14 NATLANGCLT 9-15 COBOL 9-13 NETGWNAME 9-12, 9-15 COPY library 5-6 Index-2
  • 257. MainframeConnect for DB2/MVS-CICS version 11.1.1 COUNT field 9-10 DB2 data access 2-2 CREATPKG member 5-6 DB2 database administrator CSAs, migrating 4-1 considerations for maintained CSDLOAD member 5-7 tables B-1 CSP access table MainframeConnect tape tasks 5-3 sp_server_info table B-1 personnel requirements 3-3 sp_sproc_columns table B-1 tables to maintain 6-1, B-1 sp_stored_procedures table B-1 tasks 6-2 CSP exit 9-10 TRS CSP tasks 6-2 CSP exit programs 9-10 DB2 messages CSPs how handled by SYRT A-2 exit processing 9-10 how returned to client A-2 exit program 9-10 DB2 packages, authorizing users 5-4 exit program group ID 9-10 DBCS field 9-15 sp_capabilities B-2 DBMS B-1 sp_stored_procedures B-2 DBRM library 5-7 sp_thread_props B-2 Defaults, transaction name 4-1 CTRL library Definitions MainframeConnect tape 5-6 verifying NCP 3-7 Customization VTAM, verifying 3-7 character set 2-2 DFHCSDUB utility 5-2, 6-1 messages on AMD2CAMX 4-3 DirectConnect message text 8-9 communicating with other products 2-5 stored procedure name changes B-2 D stored procedure names B-2 DASD requirements 3-6 support 10-7 Data accessed by ClearConnect 1-8 DirectConnect communications Datatypes, user 2-3 SNA LU6.2 10-8 Data Workbench 2-5 TCP/IP uplink 10-8 DB2 DRDA mainframe product 2-4 use with ClearConnect 1-8 DB2 Access Module Dynamic SQL DB2 data access 2-2 components 2-3 defining error logs to CICS A-2 error logging A-2 to A-3 E full error logs A-2 Electronic mail handling messages A-2 for documentation xxiv how DB2 messages are returned to for technical support xx client A-2 Eliminating messages 8-10 how error logs work A-2 Enabling parse exit routine 9-20 messages A-1 to A-3 Enterprise CONNECT See also SYRT processing environment 1-10 SQL Server messages mapped to A-2 ENTRIES field 9-10 MainframeConnect for DB2/MVS-CICS Install & Admin Guide Index-3
  • 258. MainframeConnect for DB2/MVS-CICS version 11.1.1 Error handling in parse exit how to contact xxiv routines 9-18 Features of MainframeConnect 2-3 Error log, AMD2LOG 10-12 Fields Error logging AMD2XCOB-CA. See Common area DB2 Access Module A-2 to A-3 fields DB2 Access Module log files A-2 COUNT 9-10 Error messages ENTRIES 9-10 33231 8-6, 9-20 Group ID exit name 9-10 Errors See Common area fields AMD2LOGO error overflow 10-12 USERID 9-10 common problems 10-3 XACTION 9-8, 9-9 fatal indicator 8-4 XDATE 9-7 preventative measures 10-5 XDBSID 9-7 Estimating temporary storage 7-6 XDBUID 9-7 Examples XERRMSG 9-8, 9-9 source code for translate table 8-2 XHEADER 9-7 EXEC CICS LINK command 9-1, 9-2, 9-12 XREASON 9-7, 9-9 EXITAREA 9-5 XREQADDR 9-8 Exit processing, CSPs 9-10 XREQFUNC 9-8 Exit programs XREQNAME 9-8 and Temporary Storage Type 9-9 XREQOPT 9-8 CSP 9-10 XRESCODE 9-9 parse exit routine 9-11 XRESNAME 9-9 request validation 9-2 XRESOPT 9-9 result validation 9-2 XRESQNAM 9-9 Exit routines XRESROWS 9-9 coding 9-16 XRESSIZE 9-9 in MainframeConnect 2-3 XRESTYPE 9-9 returning to AMD2 9-13 XSERVER 9-7 See Exit programs 9-11 XTERMID 9-7 understanding 9-2 XTIME 9-7 Exits XUSERID 9-7 request validation 9-1 Flow, process 10-14 result validation 9-1 FREEMAIN command 9-19 EXITSAMP 9-3 Functionality EYECATCHER field 9-15 in MainframeConnect 2-1 F G Failure GETMAIN command 9-18 mainframe network 10-5 Group ID exit, setting the name 7-4 network session or line 10-5 Group ID exit name field 9-10 Fatal error indicator 8-4 Group ID exit name property 7-4 Fax-on-Demand Group ID in CSP exit program 9-10 Index-4
  • 259. MainframeConnect for DB2/MVS-CICS version 11.1.1 H TRSDBRM 6-4 TRSLOAD 6-5 Handling errors in parse exit Library names 4-3 routines 9-18 Line failure 10-5 Host Request Library DB2 table 2-4 Link-editing the parse exit routine 9-20 Host request library ID property 7-5 LOADLIB library MainframeConnect tape 5-7 I Logging messages 8-10 Indicators troubleshooting 10-11 fatal error 8-4 LOG property 8-4, A-2 for message variables 8-6 Logs, nglog traffic log 10-8 Installation steps Long-running transactions 2-1 MainframeConnect tape 5-1 LU6.2 Installation task summary 3-1 troubleshooting 10-8 Internationalization LU is inactive 10-4 in MainframeConnect 2-2 M J MACLIB library 5-8 JCL library Macros MainframeConnect tape 5-7 AMD2MAMT 8-2 JCL to retrieve JCL AMD2MAMX 8-2 MainframeConnect tape 5-1 Mainframe network failure 10-5 Mainframe communications L TCP/IP for MVS 10-9 Languages TCP/IP Sockets Interface 10-9 programming 9-16 VTAM/NCP 10-9 Level, severity 8-4 MainframeConnect Level property 8-4 accessing relational and Libraries non-relational data 2-2 COPY 5-6 AMD2 transaction processor 2-4 CTRL 5-6 changes from prior products 4-1 DBRM 5-7 changing settings 7-1 host request 7-5 character set customization 2-2 JCL 5-7 communication path 2-5 LOADLIB 5-7 communication with other MACLIB 5-8 products 2-4 MainframeConnect contents 5-6 dynamic SQL DB2 data access 2-2 MainframeConnect TRS contents 6-3 exit routines 2-3 SOURCE 5-9 functionality 2-1 TRLSJCL 6-5 Host Request Library DB2 table 2-4 TRSCTRL 6-3 internationalization 2-2 MainframeConnect for DB2/MVS-CICS Install & Admin Guide Index-5
  • 260. MainframeConnect for DB2/MVS-CICS version 11.1.1 library contents 5-6 AMD2ACF2 5-8 long-running transactions 2-1 AMD2CAMX 5-8, 5-9 migrating 4-2 AMD2CCPX 5-9 multiple connectivity 2-1 AMD2CFG 5-7, 5-8 non-truncated columns 2-3 AMD2CHAB 5-8 other features 2-3 AMD2CICS 5-8 protocols 2-1 AMD2DB2 5-7 tape installation steps 5-1 AMD2DSN 5-8 tapes 3-1 AMD2HRCT 5-6 troubleshooting 10-10 AMD2LOG 5-7 TRS library contents 6-3 AMD2MSG 5-7 understanding properties 7-3 AMD2PXIT 5-7 user datatypes 2-3 AMD2RACF 5-8 verifying connectivity 10-1 AMD2RDO 5-6 MainframeConnect Configuration Tran AMD2RDO3 5-6 ID Selection window 7-1 AMD2TOP 5-8 MainframeConnect Configuration AMD2XCOB 5-6 window 7-2 BINDPKG 5-7 MainframeConnect tape BINDPLAN 5-7 installation steps 5-1 CREATEPKG 5-6 JCL to retrieve JCL 5-1 CSDLOAD 5-7 library contents 5-6 SYBACO00 6-4 TRS library contents 6-3 SYBACO01 6-4 mainframe network operational SYBACP00 6-4 failure 10-5 SYBADB00 6-4 Mainframe products SYBADT00 6-4 ACF2 2-5 SYBAFK00 6-4 CICS 2-5 SYBAGNAM 6-4 DB2 2-4 SYBAPK00 6-4 MVS 2-5 SYBASC00 6-4 NCP 2-5 SYBASI00 6-4 RACF 2-5 SYBASL00 6-4 Resource Access Control Facility 2-5 SYBASP00 6-4 Systems Network Architecture 2-5 SYBAST00 6-4 TCP/IP 2-5 SYBATB00 6-4 Top Secret 2-5 SYBATB01 6-4 Main memory, temporary storage 7-6 SYBATB02 6-4 Maintain DB2 database administrator SYBATP00 6-4 tables B-1 SYBCAPAB 6-5 MDI transaction processor 2-3 SYBTHRED 6-5 Measures for preventing problems 10-5 SYCACERR 6-5 Members SYCACPGM 6-5 ADM2CM 5-8 SYRTMAMT 5-8 AMD2ACE 5-7 SYRTMAMX 5-8 Index-6
  • 261. MainframeConnect for DB2/MVS-CICS version 11.1.1 SYSAPARS 9-20 Group ID exit name property 7-4 TRSBIND 6-5 library 4-3 TRSCREA2 6-3 Parse exit name property 7-4 TRSCREAT 6-3 Request exit name property 7-4 TRSCSD 6-3, 6-5 Result exit name property 7-4 TRSDROP 6-3 stored procedure on TRSGRANT 6-3 DirectConnect B-2 TRSRCT 6-3 transaction 4-1 Messages NATLANGCLT field 9-15 adding SQLCODEs 8-7 NCP changing 8-1 to 8-11 mainframe product 2-5 changing message table 8-7 troubleshooting 10-9 changing text 8-1 verifying definition 3-7 coding changes 8-11 Net-Gateway 1-4 customized on AMD2CAMX 4-3 NETGWNAME field 9-12, 9-15 customizing 8-9 Network failure eliminating 8-10 mainframe 10-5 list of A-1 to A-86 session or line 10-5 logging 8-10 network operational failure 10-5 Text table 8-1, 8-4 Network session failures 10-5 translate table 8-1, 8-2 nglog traffic log 10-8 variables 8-6 ngtds trace file 10-8 Message table, SYRT A-1 Non-relational data, accessing 2-2 Migrating Non-truncated columns 2-3 assigning library names 4-3 CSAs 4-1 MainframeConnect changes 4-1 O preserving customized messages 4-3 ODBC 2-5 remove a prior product 4-2 OmniSQL Access Module for DB2 1-3 RSPs 4-1 Open Database Connectivity 2-5 to MainframeConnect 4-2 overflow error file, AMD2LOGO 10-12 Modules Overviews, result validation exit 9-1 AMD2CAMX 8-2 MSGCODE field 9-12, 9-16, 9-19 MSGNO property 8-3 P Multiple connectivity in Packages, DB2 5-4 MainframeConnect 2-1 Parse exit name property 7-4 MVS mainframe product 2-5 Parse exit routine 9-11 acquiring additional storage 9-17 N assigning return code 9-19 calling 9-12 Names COBOL copy book 9-13 DirectConnect stored procedure coding 9-16 changes B-2 common area 9-13 MainframeConnect for DB2/MVS-CICS Install & Admin Guide Index-7
  • 262. MainframeConnect for DB2/MVS-CICS version 11.1.1 compiling 9-20 DirectConnect stored names B-2 enabling 9-20 stored B-1 handling errors 9-18 Process flow 10-14 link-editing 9-20 Processing environment 1-10 programming languages 9-16 Processing SQL statements 9-13 sample 9-16 Processing user-defined setting the name 7-4 transactions 9-13 understanding 9-12 Product names 4-2 PASSWORD field 9-12, 9-15 Professional Services Performance upgrades 3-5 how to contact xxi Personnel requirements 3-3 Programming languages and parse exit PL/I coding parse exit routine 9-16 routine 9-16 Plan, application 5-4 Programs Planning See Exit programs 9-9 installation task summary 3-1 See Sample programs 9-3 MainframeConnect tapes 3-1 Properties preinstallation checklist 3-2 DateTime results type 7-7 Post-installation tasks Group ID exit name 7-4 authorizing users for application Host request library 7-5 plan 5-4 Level 8-4 authorizing users for DB2 LOG 8-4, A-2 packages 5-4 MSGNO 8-3 authorizing users for system Parse exit name 7-4 tables 5-5 Request exit name 7-4 Preinstallation checklist Result exit name 7-4 CICS configuration 3-7 SQLCODE 8-3, 8-7 Components 3-6 SQLFATAL 8-4 connectivity 3-6 STATEC 8-4 NCP definition 3-7 Temp storage queue type 7-5, 9-9 performance upgrades 3-5 Transaction ID 7-3 personnel requirements 3-3 understanding MainframeConnect space requirements 3-6 configuration 7-3 special system requirements 3-4 Protocols summary 3-2 MainframeConnect 2-1 system requirements 3-3 Tabular Data Stream 2-5 VTAM definition 3-7 Preventative measures 10-5 Prior products, removing groups 4-2 R Problems RACF common 10-3 AMD2RACF group ID exit name 7-5 preventative measures 10-5 AMD2RACF member 5-8 Procedures mainframe product 2-5 DirectConnect stored name Related software products changes B-2 related IBM products 1-12 Index-8
  • 263. MainframeConnect for DB2/MVS-CICS version 11.1.1 related Sybase products 1-11 CSP exit 9-10 Relational data, accessing 2-2 request validation exit 9-3 Release numbers 4-2 result validation exit 9-3 Request exit name property 7-4 SDLC Request validation exit line is not up 10-4 communication area 9-5 planning considerations 3-5 description 9-7 Security Administrator 3-3 enabling 9-3 select statement 9-11 fields 9-7 Sequence, attention 10-17 overview 9-1 Servers, communicating with other sample program 9-3 products 2-5 setting the name 7-4 Session failure 10-5 Requirements 10-14 Settings, changing DASD 3-6 MainframeConnect 7-1 performance upgrades 3-5 Severity level 8-4 personnel 3-3 Sizes, RU 3-5 space 3-6 SNA LU6.2 10-8 special system 3-4 Source code for translate table 8-2 system 3-3 SOURCE library RESERVED field 9-16 MainframeConnect tape 5-9 Resource Access Control Facility sp_capabilities procedure B-2 AMD2RACF group ID exit name 7-5 sp_server_info table B-1 AMD2RACF member 5-8 sp_sproc_columns table B-1 mainframe product 2-5 sp_stored_procedures CSP B-1, B-2 Result exit name property 7-4 sp_thread_props procedure B-2 Result validation exit Space requirements 3-6 communication area 9-5 SQLCA description 9-8 in DB2 Access Module messages A-7, enabling 9-3 A-8, A-9, A-10, A-11, A-12, A-13, fields 9-8 A-14, A-15, A-16, A-17, A-18, overview 9-1 A-19, A-20, A-21, A-22, A-23, sample program 9-3 A-24, A-25, A-26, A-27, A-28, setting the name 7-4 A-29, A-30, A-31, A-32, A-33, RETCODE field 9-12, 9-16, 9-19 A-34, A-35, A-36, A-37, A-38, Return codes, assigning 9-19 A-39, A-40, A-41, A-42, A-43, rollback statement 9-13 A-44, A-45, A-46, A-47, A-48, Routines, exit 9-2 A-49, A-50, A-70 RSPs, migrating 4-1 in MainframeConnect for RU size 3-5 DB2/MVS-CICS messages A-6 SQLCODE in DB2 Access Module messages A-6, S A-7, A-8, A-9, A-10, A-11, A-12, Sample parse exit routine 9-16 A-13, A-14, A-15, A-16, A-17, Sample programs A-18, A-19, A-20, A-21, A-22, MainframeConnect for DB2/MVS-CICS Install & Admin Guide Index-9
  • 264. MainframeConnect for DB2/MVS-CICS version 11.1.1 A-23, A-24, A-25, A-26, A-27, Summary A-28, A-29, A-30, A-31, A-32, of installation tasks 3-1 A-33, A-34, A-35, A-36, A-37, Support A-38, A-39, A-40, A-41, A-42, DirectConnect 10-7 A-43, A-44, A-45, A-46, A-47, SYBACO00 member 6-4 A-48, A-49, A-50, A-70 SYBACO01 member 6-4 SQLCODE property SYBACP00 member 6-4 adding 8-7 SYBADB00 member 6-4 definition 8-3 SYBADT00 member 6-4 SQL DB2 data access 2-2 SYBAFK00 member 6-4 SQLFATAL property 8-4 SYBAGNAM member 6-4 SQL Server SYBASC00 member 6-4 messages mapped to SYRT Sybase online information messages A-2 how to access xxiii other servers 2-5 SYBASI00 member 6-4 SQL statements, processing 9-13 SYBASL00 member 6-4 SQL text, altering 9-17 SYBASP00 member 6-4 STATEC property 8-4 SYBAST00 member 6-4 Statements SYBATB00 member 6-4 begin tran 9-13 SYBATB01 member 6-4 commit 9-13 SYBATB02 member 6-4 processing SQL 9-13 SYBATP00 member 6-4 rollback 9-13 SYBCAPAB member 6-5 select 9-11 SYBPKO00 member 6-4 USE REQUEST 9-3 SYBTHRED member 6-5 STATESC subclass 8-4 SYCACERR member 6-5 Steps, installation SYCACPGM member 6-5 CSPs for Transaction Router SYRT Service 6-1 how DB2 messages are handled A-2 MainframeConnect tape 5-1 how internal messages are STMT-PTR field 9-12, 9-15 handled A-2 Storage message table processes DB2 acquiring additional for parse exit SQLCODEs A-2 routine 9-17 See also DB2 Access Module DateTime results type property 7-7 SYRTLOG estimating temporary 7-6 definition A-2 See Temporary Storage Type sample FCT entry A-3 temporary storage 7-6 SYRTLOGO Temp queue type property 7-5 definition A-2 Stored procedures, DB2 database sample FCT entry A-3 administrator information B-1 SYRTMAMT member 5-8 Subclasses, STATESC 8-4 SYRTMAMX member 5-8 Suggested solutions for SYRT transaction processor 2-3 troubleshooting 10-3 SYSAPARS member 9-20 Index-10
  • 265. MainframeConnect for DB2/MVS-CICS version 11.1.1 System requirements Temp storage queue type property 7-5, 7-7, operating system 3-3 9-9 performance upgrades 3-5 Text platform 3-3 altering SQL 9-17 special 3-4 changing message 8-1 Systems Network Architecture 2-5 message table 8-1, 8-4 System tables, authorizing users 5-5 Token Ring line is not up 10-4 upgrade considerations 3-5 T Top Secret Tables AMD2TOP member 5-8 considerations for DB2 database AMD2TS group ID exit name 7-5 administrator-maintained mainframe product 2-5 tables B-1 Trace files, ngtds 10-8 DB2 database administrator B-1 Tracing 10-11 DB2 database Transaction ID property 7-3 administrator-maintained 6-1 Transaction name 4-1 Host Request Library DB2 2-4 Transaction processor message text 8-1, 8-4 AMD2 2-4 message translate 8-1, 8-2 MDI 2-3 system 5-5 SYRT 2-3 Tabular Data Stream protocol 2-5 Transactions Tapes, MainframeConnect 3-1 long-running 2-1 Tasks processing user-defined 9-13 CICS system programmer 5-1, 5-3, Translate table 6-1, 6-2 messages 8-1, 8-2 DB2 database administrator 5-3, 6-2 source code 8-2 installation summary 3-1 Troubleshooting post-installation 5-4, 5-5 attention sequences 10-17 TCP/IP cannot establish a session 10-3 for MVS 10-9 CICS 10-9 mainframe product 2-5 common problems 10-3 Sockets Interface 10-9 components 10-6 troubleshooting 10-8 configuration errors 10-3 uplink 10-8 coordination 10-14 TDS 2-5 DirectConnect support 10-7 Technical support flow process 10-14 how to contact xix line failure 10-5 Temporary storage logging 10-11 estimating 7-6 LU is inactive 10-4 in main memory 7-6 mainframe communications with Temporary Storage Type and exit MainframeConnect 10-9 programs 9-9 MainframeConnect 10-10 MainframeConnect for DB2/MVS-CICS Install & Admin Guide Index-11
  • 266. MainframeConnect for DB2/MVS-CICS version 11.1.1 mainframe network operational understanding 9-2 failure 10-5 USERID field 9-10, 9-12, 9-15 NCP 10-9 Utility, DFHCSDUB 5-2, 6-1 network session failure 10-5 preventative measures 10-5 SDLC line not up 10-4 V SNA LU6.2 10-8 Validation exits suggested solutions 10-3 request 9-1 TCP/IP for MVS 10-9 result 9-1, 9-2 TCP/IP Sockets Interface 10-9 Validation programs. See Sample TCP/IP uplink 10-8 programs Token Ring is not up 10-4 Variables, messages 8-6 tracing 10-11 VTAM transaction does not run 10-4 knowledgeable person 3-3 verifying connectivity 10-1 verifying definition 3-7 VTAM 10-9 where to start 10-2 TRSBIND member 6-5 W TRSCREA2 member 6-3 Where to start troubleshooting 10-2 TRSCREAT member 6-3 Windows TRSCSD member 6-3, 6-5 MainframeConnect TRSCTRL library 6-3 Configuration 7-2 TRSDBRM library 6-4 MainframeConnect Configuration TRSDROP member 6-3 Trans ID Selection 7-1 TRSGRANT member 6-3 TRSJCL library 6-5 TRSLOAD library 6-5 X TRSRCT member 6-3 XACTION field 9-8, 9-9 XDATE field 9-7 U XDBSID field 9-7 Unit of work 9-13 XDBUID field 9-7 Upgrade considerations XERRMSG field 9-8, 9-9 performance 3-5 XHEADER field 9-7 RU size 3-5 XREASON field 9-7, 9-9 using a Token Ring 3-5 XREQADDR field 9-8 using SDLC 3-5 XREQFUNC field 9-8 User datatypes 2-3 XREQNAME field 9-8 User-defined transactions 9-13 XREQOPT field 9-8 USE REQUEST statement 9-3 XRESCODE field 9-9 User exits XRESNAME field 9-9 coding 9-16 XRESOPT field 9-9 enabling 9-3 XRESQNAM field 9-9 returning to AMD2 9-13 XRESROWS field 9-9 XRESSIZE field 9-9 Index-12
  • 267. MainframeConnect for DB2/MVS-CICS version 11.1.1 XRESTYPE field 9-9 XSERVER field 9-7 XTERMID field 9-7 XTIME field 9-7 XUSERID field 9-7 MainframeConnect for DB2/MVS-CICS Install & Admin Guide Index-13
  • 268. MainframeConnect for DB2/MVS-CICS version 11.1.1 Index-14