uniaccess for os 2200 client guide · release 10r3: october 31, 2005 contents vii part iv:...

UniAccess for OS 2200 Client Guide

Release 10R3Document Version: 1.00Last Revised: October 31, 2005Copyright 2005. All rights reserved.

UniAccess 10R3 Product SuiteTitle

Principal Authorship

AIS Technical Publications Department

Document Version

This publication pertains to Release 10R3, version 1.00 of the Applied Information Sciences OS 2200 connectivity 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 may be used or copied only in accordance with the terms of the agreement.

Document Feedback

The Applied Information Sciences Technical Publications Department welcomes corrections and comments on its documents. Please send corrections and comments to UniAccess Technical Support at the address below.

Applied Information Sciences, Inc.1850 Centennial Park DriveReston, VA 20191USA

Phone (703) 860-7808FAX (703) 860-7820E-mail [email protected]

Document Orders and Upgrades

UniAccess documentation is provided on the UniAccess 10R3 PC Client CD for online viewing with Adobe Acrobat Reader. To order this CD, contact AIS at the above number or retrieve the documents from the Internet at http://www.uniaccess.com. Customers may make copies of the UniAccess 10R3 PC Client CD for their in-house use. Additionally, customers may print copies of the UniAccess documentation from the CD for their in-house use.

Customers may purchase printed copies of any document or the right to make photocopies of printed documentation for their in-house use. To order printed documents or photocopy rights, contact AIS at the address given above.

Upgrades are provided only at regularly scheduled software release dates.

http://www.uniaccess.com

Copyright 1989 to 2005 Applied Information Sciences, 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 prior written permission of Applied Information Sciences, Inc.

Restricted Rights Legend

Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in FAR subparagraphs 52.227-19(a)-(d) for civilian agency contracts and DFARS 252.227-7013(c)(1)(ii) for Department of Defense contracts.

Applied Information Sciences, Inc. reserves all unpublished rights under the copyright laws of the United States.

Applied Information Sciences Trademarks

UniAccessTM is a trademark of Applied Information Sciences, Inc.

Sybase Trademarks

Sybase®, SYBASE® (logo), SQL Server®, Transact-SQL®, PowerBuilder®, and Adaptive Server® Enterprise are registered trademarks of Sybase, Inc.

Client-LibraryTM, CT-LibraryTM, DB-LibraryTM, Embedded SQLTM, Enterprise Client/ServerTM, Net-LibraryTM, Open ClientTM, Open ServerTM, and Tabular Data StreamTM are trademarks of Sybase, Inc.

Other Trademarks

Microsoft® is a registered trademark of Microsoft Corporation. Unisys® is a registered trademark of Unisys Corporation. All other company and product names used herein may be the trademarks or registered trademarks of their respective companies.

Release 10R3: October 31, 2005

Contents

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Contents

Table of ContentsPreface

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiUniAccess System Product Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiRelated Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Conventions Used in this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvFonts and Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvTerminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

How This Manual Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Part I: Basics

1 Introduction to UniAccess System for OS 2200 1-1Client/Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Client/Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Types of Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Types of Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

ODBC Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5The ODBC Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6ODBC Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

UniAccess System for OS 2200 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8UniAccess ODBC Server for RDMS 2200. . . . . . . . . . . . . . . . . . . . . . . 1-9UniAccess ODBC Server for DMS 2200 . . . . . . . . . . . . . . . . . . . . . . . 1-11UniAccess Transaction Server for OS 2200 . . . . . . . . . . . . . . . . . . . . . 1-11UniAccess Transaction Client for OS 2200 . . . . . . . . . . . . . . . . . . . . . 1-12Communication with the UniAccess System . . . . . . . . . . . . . . . . . . . . 1-12

What’s Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14

iv UniAccess for OS 2200 Client Guide


2 Application Development Overview 2-1Types of Computing Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Services Model of Application Composition . . . . . . . . . . . . . . . . . . . . . 2-2Physical Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Types of Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Language Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Remote Procedure Calls (RPCs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Comparing Language Requests and RPCs . . . . . . . . . . . . . . . . . . . . . . . 2-8

Client Applications with the UniAccess System . . . . . . . . . . . . . . . . . . . . . 2-9Sending Language Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Sending Procedure Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

What’s Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

Part II: Getting Started

3 Installing Client Software 3-1System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2UniAccess 0S 2200 Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

UniAccess ODBC Driver Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Standard PC Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Network Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5Microsoft Systems Management Server (SMS) Installation . . . . . . . . . 3-6Customized Data Source Configuration and Translator Installation . . . 3-7

4 Using the UniAccess System 4-1General Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Levels of TDS Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Establishing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Changing Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4Connection Timeout Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4Architecture Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4User Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

What’s Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Pointers for ODBC Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Pointers for Open Client Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9


Contents v

5 Using the UniAccess ODBC Driver 5-1The UniAccess ODBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

ODBC Implementation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Datatypes Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Isolation and Lock Levels Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9Number of Connections and Statements Supported . . . . . . . . . . . . . . . 5-10ODBC Translation Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10High Speed Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Configuring Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11Configuring a New or Existing Data Source . . . . . . . . . . . . . . . . . . . . 5-11General UADriver Setup Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12Advanced UADriver Setup Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15Translation UADriver Setup Options . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20UARS Setup Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22UAHS Setup Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29

Connecting to a Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32Verifying Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32Using a Login Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33Using a Connection String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33

Application Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40Andyne GQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40Centura SQL Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40

Part III: Accessing RDMS 2200 with UARS

6 Using UniAccess Relational Service for RDMS 2200 6-1UARS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

UARS Operational Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3ODBC and Open Client API Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

RDMS 2200 Statement Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4RDMS 2200 Statements Supported by UARS . . . . . . . . . . . . . . . . . . . . 6-4Statement Considerations for ODBC Clients . . . . . . . . . . . . . . . . . . . . . 6-6Statement Considerations for Open Clients . . . . . . . . . . . . . . . . . . . . . 6-10

RDMS 2200 Datatype Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20Client and RDMS 2200 Datatype Correspondence . . . . . . . . . . . . . . . 6-20RDMS 2200 Datatype Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22Datatype Considerations for Open Clients . . . . . . . . . . . . . . . . . . . . . . 6-26

RDMS 2200 Stored Procedure Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28Routing Procedure Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28Error Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29Datatype Correspondence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29

vi UniAccess for OS 2200 Client Guide


RDMS Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34ODBC Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35RDMS Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39

7 UARS Commands 7-1UARS Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

BEGIN TRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5SET ACCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6SET BLOBSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8SET DISTTRAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9SET INTTOCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11SET LONGCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12SET RECOVERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13SET ROWLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15SET SPACETRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16SET STRIPCTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17SET TRANSACTIVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18SET TRANSOPTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19SET UNICODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-22SET USERTRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-23SET WORKSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-24UARSINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-26

8 RDMS Catalog RPCs 8-1Overview of RDMS Catalog RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2Using Catalog RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

Coding Instructions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7

RDMS Catalog RPC Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8sp_column_privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10sp_columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14sp_databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18sp_datatype_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19sp_fkeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24sp_pkeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28sp_server_info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-30sp_special_columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-35sp_sproc_columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-38sp_statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-43sp_stored_procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-47sp_table_privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-51sp_tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-55


Contents vii

Part IV: Accessing DMS 2200 with UAHS

9 Using UniAccess Hierarchical Service for DMS 2200 9-1UAHS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

UAHS Operational Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3ODBC and Open Client API Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4The UAHS Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4

UAHS SQL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7UAHS SELECT Statement Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7UAHS SELECT Statement Extensions . . . . . . . . . . . . . . . . . . . . . . . . 9-10UAHS SELECT Statement Limitations . . . . . . . . . . . . . . . . . . . . . . . . 9-11

Relational Mapping Implications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12Repository Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13DMS Set Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13Record Retrieval Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17Sorting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17UAHS Debug Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18

DMS 2200 Datatype Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19Client and DMS 2200 Datatype Correspondence. . . . . . . . . . . . . . . . . 9-19Supported DMS 2200 Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-21Attributes of Supported DMS Items . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22

10 UAHS Commands 10-1UAHS Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2

SET AREASEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4SET DEBUG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5SET DISTTRAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6SET ROWLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7SET SPACETRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8SET STRIPCTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9SET TRANSACTIVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10SET TRANSOPTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11UAHSINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12

11 UAHS Catalog RPCs 11-1Overview of UAHS Catalog RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2Using Catalog RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2

Coding Instructions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4

UAHS Catalog RPC Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5sp_columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6

viii UniAccess for OS 2200 Client Guide


sp_databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10sp_datatype_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11sp_special_columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15sp_statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18sp_tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22

Part V: Advanced Data Access through UniAccess

12 Using UniAccess Transaction Server for OS 2200 12-1Transaction Server Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2

Server-Library Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2ODBC Catalog RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3UAINFO Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4User Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7

RPC Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7Naming RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8Routing RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9

Language Request Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9Default Language Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9

13 Using UniAccess Distributed Transaction Coordinator 13-1Distributed Transaction Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2

Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2Distributed Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3Distributed Transaction Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5UniAccess / Microsoft Implementation . . . . . . . . . . . . . . . . . . . . . . . . 13-6

UADTC Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9Network Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11Transaction Coordinator Connectivity Test . . . . . . . . . . . . . . . . . . . . 13-11

UADTC Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12Starting and Stopping UADTC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12Configuring UADTC Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-13

Distributed Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-15Monitoring Distributed Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 13-17Distributed Transaction States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20Resolving Distributed Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 13-22


Contents ix

Appendixes

A Client Examples A-1Interactive SQL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Microsoft Transact-SQL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

From SQL Query Analyzer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2From a Stored Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Visual Basic Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

B Server Program Messages B-1UniAccess System Server Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2UAHS Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21

C UAMM Error Messages C-1UAMM General Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1UAMM Detailed Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2

D Troubleshooting D-1UADriver Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1

Test Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1Tracing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-7

UADTC Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-10Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-12

UADriver Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-12UADTC Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-16

Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-18E-mail Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-18WWW Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-18

E References E-1AIS References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1Microsoft References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2Sybase References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2Unisys References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2

Glossary

Index

x UniAccess for OS 2200 Client Guide


List of FiguresFigure 1-1: Client/Server Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Figure 1-2: ODBC Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7Figure 1-3: UniAccess ODBC Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10Figure 1-4: UniAccess PC Client Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14Figure 2-1: UniAccess Implementation of Logical Two-Tier Model . . . . . . . . . . . . . . 2-3Figure 2-2: UniAccess Implementation of Logical Two-and-a Half-Tier Model . . . . . 2-4Figure 2-3: UniAccess Implementation of Logical Three-Tier Model . . . . . . . . . . . . . 2-6Figure 2-4: Two-Tier and Multi-Tier Language Requests . . . . . . . . . . . . . . . . . . . . . 2-11Figure 2-5: Two-Tier and Multi-Tier Procedure Calls

in the UniAccess Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12Figure 5-1: UADriver Setup Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13Figure 5-2: Advanced UADriver Setup Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15Figure 5-3: Translation Options Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21Figure 5-4: UARS Setup Options Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23Figure 5-5: UAHS Setup Options Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29Figure 8-1: How RDMS Catalog RPCs are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3Figure 9-1: Catalog RPC and SELECT Statement Processing . . . . . . . . . . . . . . . . . . . 9-6Figure 9-2: Superior Record Root Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14Figure 9-3: Subordinate Record Root Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15Figure 9-4: Subordinate Record Root Selection of Manual Sets . . . . . . . . . . . . . . . . 9-16Figure 13-1: Distributed Transaction Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4Figure 13-2: UniAccess / Microsoft Implementation of

Distributed Transaction Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8Figure 13-3: UADTC Network Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10Figure 13-4: UADTC Configuration Options Dialog . . . . . . . . . . . . . . . . . . . . . . . . 13-15Figure 13-5: UADTC Snap-in Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-16Figure 13-6: Communications Break Resulting in an In Doubt State . . . . . . . . . . . 13-23Figure 13-7: Communications Break Resulting in a Cannot Notify State . . . . . . . . 13-25Figure D-1: UADriver Test Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2Figure D-2: UADriver Tracing Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-8Figure D-3: UADTC Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-11


Contents xi

List of TablesTable 1: Client Guide Organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiTable 3-1: UniAccess PC Client Software Requirements . . . . . . . . . . . . . . . . . . . . . . . 3-2Table 3-2: LANGTYPE Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8Table 4-1: Summary of 8-bit-byte Architecture and OS 2200 Ranges . . . . . . . . . . . . . 4-5Table 4-2: User Datatypes Returned by UARS, UAHS, and UAINFO . . . . . . . . . . . . 4-7Table 4-3: Important Chapters for ODBC Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Table 4-4: Important Chapters for Open Client Users. . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Table 5-1: Supported ODBC Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Table 5-2: RDMS 2200 and ODBC Datatype Correspondences. . . . . . . . . . . . . . . . . . 5-6Table 5-3: DMS 2200 and ODBC Datatype Correspondences . . . . . . . . . . . . . . . . . . . 5-7Table 5-4: ODBC to UASL Datatype Correspondence. . . . . . . . . . . . . . . . . . . . . . . . . 5-8Table 5-5: UASL to ODBC SQL Datatype Correspondence . . . . . . . . . . . . . . . . . . . . 5-9Table 5-6: UniAccess ODBC Driver Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34Table 6-1: Supported RDMS 2200 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4Table 6-2: Restrictions on User-Defined Transactions . . . . . . . . . . . . . . . . . . . . . . . . 6-18Table 6-3: Supported RDMS 2200 Datatypes and Client Correspondences . . . . . . . . 6-20Table 6-4: Precision, Scale, and Length of RDMS 2200 Datatypes . . . . . . . . . . . . . . 6-25Table 6-5: ODBC SQL to RDMS 2200 Datatype Correspondence . . . . . . . . . . . . . . 6-30Table 6-6: Client-Library to RDMS 2200 Datatype Correspondence . . . . . . . . . . . . 6-31Table 6-7: ODBC Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35Table 6-8: Supported RDMS Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39Table 7-1: UARS Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2Table 7-2: UARS Command Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3Table 7-3: Information Returned by UARSINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-26Table 7-4: Result Set for UARSINFO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-29Table 8-1: UniAccess Catalog RPCs and Corresponding RDMS 2200 Entities . . . . . . 8-4Table 8-2: Wild Card Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7Table 8-3: Quick Reference for Catalog RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8Table 8-4: Result Set for sp_column_privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12Table 8-5: Result Set for sp_columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16Table 8-6: Result Set for sp_databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18Table 8-7: Result Set for sp_datatype_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21Table 8-8: Result Set for sp_fkeys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26Table 8-9: Result Set for sp_pkeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29Table 8-10: Information Retrievable by sp_server_info . . . . . . . . . . . . . . . . . . . . . . . 8-31Table 8-11: Result Set for sp_server_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34

xii UniAccess for OS 2200 Client Guide


Table 8-12: Result Set for sp_special_columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-37Table 8-13: Result Set for sp_sproc_columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-41Table 8-14: Result Set for sp_statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-45Table 8-15: Result Set for sp_stored_procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-50Table 8-16: Result Set for sp_table_privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-53Table 8-17: Result Set for sp_tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-57Table 9-1: UAHS SELECT Statement Syntax Components . . . . . . . . . . . . . . . . . . . . 9-8Table 9-2: Supported DMS 2200 Datatypes and Client Correspondences . . . . . . . . . 9-20Table 9-3: Precision, Scale, and Length of DMS 2200 Datatypes . . . . . . . . . . . . . . . 9-24Table 10-1: UAHS Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2Table 10-2: UAHS Command Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3Table 10-3: Information Returned by UAHSINFO. . . . . . . . . . . . . . . . . . . . . . . . . . 10-12Table 10-4: Result Set for UAHSINFO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14Table 11-1: Wild Card Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4Table 11-2: Quick Reference for Catalog RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5Table 11-3: Result Set for sp_columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8Table 11-4: Result Set for sp_databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10Table 11-5: Result Set for sp_datatype_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12Table 11-6: Result Set for sp_special_columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17Table 11-7: Result Set for sp_statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20Table 11-8: Result Set for sp_tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-24Table 12-1: Datatypes Supported by UASL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2Table 12-2: Information Returned by UAINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5Table 12-3: Result Set for UAINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6Table 13-1: Distributed Transaction States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-20


Preface

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preface

About This BookThis manual accompanies the UniAccess System for OS 2200 product suite. It explains how a client programmer can write applications that communicate with an OS 2200 host through the UniAccess System. In general, writing UniAccess System client applications is just like writing applications that communicate with a SQL Server; the UniAccess System is largely transparent to the client user.

The manual introduces you to the UniAccess System and gives you an overview of how it works. It describes how to prepare your UniAccess System environment and explains how to direct requests from various ODBC and Open Client environments to an OS 2200 host.

Audience

The UniAccess for OS 2200 Client Guide is written for UniAccess customers who are developing or using client applications that will communicate with the OS 2200 services of the UniAccess ODBC and/or Transaction Servers. The reader should be familiar with ODBC or Open Client programming techniques already.

UniAccess System Product Suite

This manual discusses communications among components of the entire UniAccess product suite. The discussion of some system components, therefore, may not apply to your particular site. The manual will specify what information is applicable to what product packages.

xiv UniAccess for OS 2200 Client Guide


Applied Information Sciences (AIS) provides the following product packages:

UniAccess ODBC Server for RDMS 2200, which includes:UARS (UniAccess Relational Service)UADriver (UniAccess ODBC Driver)UADTC (UniAccess Distributed Transaction Coordinator)UniAccess core components

UniAccess ODBC Server for DMS 2200, which includes:UAHS (UniAccess Hierarchical Service)UADriver (UniAccess ODBC Driver)Schemadef utilityTabledef utilityUniAccess core components

UniAccess Transaction Server for OS 2200, which includes:UASL (UniAccess Server-Library)UADriver (UniAccess ODBC Driver)UADTC (UniAccess Distributed Transaction Coordinator) UniAccess core components

UniAccess Transaction Client for OS 2200, which includes:UACL (UniAccess Client-Library)ISQL for OS 2200 (Interactive SQL Parser)UniAccess core components

The UniAccess core components, included in all product packages, are the UniAccess Communication Server (UACS), the UniAccess Configuration Utility (UACF), the UniAccess Data Manager (UADT), and the UniAccess Message Manager (UAMM). Their configuration and management are discussed in the UniAccess for OS 2200 System Administration Guide.

Related Documentation

In addition to this manual, the following documents are included in the UniAccess System for OS 2200 product suite:


Preface xv

UniAccess for OS 2200 System Administration GuideThis manual describes all installation and administrative aspects of the UniAccess for OS 2200 system. It describes the components of the UniAccess System and how to configure them to interface with Unisys 2200 components.

UniAccess for OS 2200 Server-Library Programming ReferenceThis manual describes UniAccess Server-Library functions and contains instructions for using them to write OS 2200 applications that accept and process client requests. It documents the UCS COBOL, ASCII COBOL, and UCS C interfaces to UASL.

UniAccess for OS 2200 Client-Library Programming ReferenceThis manual references UniAccess Client-Library functions and explains how to use these functions to write OS 2200 client applications. It documents the UCS COBOL and UCS C interfaces to UACL.

Conventions Used in this ManualAs you read this manual, you should understand how certain fonts, formats, and terminology are used.

Fonts and Format

The following general conventions are adhered to in this manual:

• Product names are capitalized: UniAccess Relational Service for RDMS 2200; SQL Server.

• Publication names and chapter names within publications are italicized: UniAccess for OS 2200 Client Guide; see Chapter 2, Application Development Overview.

• Bold type and italics are used for emphasis in the text.

In addition, certain fonts and conventions represent specific object types:

• In examples, information displayed on a computer screen is shown in Courier font: TRACE LEVEL CHANGED TO LOW.

xvi UniAccess for OS 2200 Client Guide


• PC-based file names are italicized: sql.ini.

• The following terms are in regular typeface, all capital letters:

— Constants within configuration statements and console commands: COMSRV APPNUM; STATUS PID.

— Host-based objects and values such as datatypes, symbolic values, and file names: DATETIME; TDS-OK; SYS$LIB$*UAUTIL.

• The following terms are in Arial bold:

— Catalog Remote Procedure Call names: sp_server_info

— Server-Library function names: CTBINIT; TDINIT

— Other commands in the text: a SELECT statement; the COMMIT command.

Terminology

Some familiar terms have a particular meaning when used with the UniAccess System for OS 2200. The following list explains how they are used in this manual. (For a more comprehensive list of terms, please see the Glossary.)

UniAccess System for OS 2200. Refers to the entire suite of AIS products that implements Microsoft client/server architecture on the Unisys OS 2200 system. The UniAccess System provides components that function as either clients or servers, although some components, such as UACS, are shared by both client and server systems. To facilitate the discussion of client and server applications, the following terms will be used:

UniAccess Transaction Client refers to UACL and core components when they function as an Open Client. It also includes an interactive SQL command line utility (ISQL).

UniAccess Transaction Server refers to UASL and core components when they function as a server. It also includes the client component UADriver and, optionally, UADTC.


Preface xvii

UniAccess ODBC Server for RDMS 2200 refers to UARS and core components when they function as a server. It also includes the client component UADriver and, optionally, UADTC.

UniAccess ODBC Server for DMS 2200 refers to UAHS and core components when they function as a server. It also includes the client component UADriver.

Host. Refers to the hardware system on which a software application runs. In this manual, the term host generally refers to the Unisys OS 2200 mainframe where the UniAccess System for OS 2200 software is running.

Client. Anything functioning as a client in the Microsoft client/server architecture. A client can be an ODBC compliant application, an Open Client program, a UniAccess Client-Library program, or a stored procedure on a SQL Server. This document uses the term Open Client to refer to all non-ODBC clients.

Server. Anything functioning as a server in the Microsoft client/server architecture. A server may be a UniAccess System server on the OS 2200 (UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, or UniAccess ODBC Server for DMS 2200), a SQL Server, or a SYBASE Open Server application.

SQL Server. A database server in the Microsoft client/server architecture that accepts RPCs or language requests written in Transact-SQL. There are two implementations of SQL Server: Microsoft SQL Server and Sybase SQL Server (a.k.a. Adaptive Server Enterprise—ASE), which provide many similar features. When this manual refers to SQL Server, it is referring to features common to both SQL Servers. Features specific to an implementation will be identified as either Microsoft SQL Server or Sybase SQL Server.

Local / Remote. The term local refers to whatever system is the topic under discussion. The local system must be accessed directly without using a network access. Remote refers to an area or system on the network but outside the local host. Thus, in the UniAccess System manuals, local may refer to the OS 2200 host when indicated by the context of the passage.

Application. A program or programs that, when executed, accomplish a particular action.

xviii UniAccess for OS 2200 Client Guide


Transaction. A program that runs in a TIP environment on the OS 2200 host and is initiated by a single request. In the UniAccess System, TIP transactions may act as either clients or as servers. Client transactions are created with UACL (Client-Library) functions; server transactions may be created with UASL (Server-Library) functions. The UARS and UAHS transactions are specific UASL-built transactions that processes SQL language requests for RDMS 2200 and DMS 2200 respectively.

Distributed Transaction. A transaction involving updates to transaction-protected resources across two or more systems. In this sense, a transaction is a module of execution (not specific to OS 2200), that is atomic, consistent, isolated, and durable. In the UniAccess environment, TIP transactions may participate in distributed transactions with the assistance of the UniAccess Distributed Transaction Coordinator.

RPC (remote procedure call). A request issued by an Open Client or ODBC application that is processed by a stored procedure on a SQL Server or by a Server-Library transaction.

How This Manual Is OrganizedThis manual is designed to be used as a reference. You do not have to read it from front to back. However, it is a good idea to begin with the two introductory chapters to understand the UniAccess System in general before you begin to work with the product.

This manual is divided into the following sections, chapters, and appendices.

Table 1: Client Guide Organization

Manual Organization Page

Section I: Basics 1 Introduction to UniAccess System for OS 2200

Provides an overview of Microsoft client/server architecture, ODBC architecture, and the UniAccess System for OS 2200.

2 Application Development OverviewDescribes common computing configurations and types of requests available in Microsoft client/server architecture. Discusses the basics of processing ODBC and Open Client applications in the UniAccess System.

1-1

2-1


Preface xix

Section II: Getting Started 3 Installing Client Software

Describes UniAccess PC Client installation procedures for both ODBC clients and Open Clients.

4 Using the UniAccess SystemPresents specific information about the UniAccess System relevant to users operating in all environments. Directs users of specific environments to subsequent chapters in the manual.

5 Using the UniAccess ODBC DriverDescribes the UniAccess ODBC Driver in detail including levels of compliance and datatypes supported. Provides instructions on configuring data sources and connecting with UADriver.

3-1

4-1

5-1

Section III: Accessing RDMS 2200 with UARS Accessing RDMS 2200 with UARS 6 Using UniAccess Relational Service for RDMS 2200

Provides information and guidelines to help you write client applications that use UniAccess Relational Service (UARS) to access RDMS 2200. The information is relevant to both ODBC clients and Open Clients using the UniAccess ODBC Server for RDMS 2200.

7 UARS CommandsDescribes the non-RDMS 2200 commands available through the UniAccess Relational Service.

8 RDMS Catalog RPCsExplains the function and use of RDMS Catalog RPCs. A reference section describes each supported Catalog RPC.

6-1

7-1

8-1

Section IV: Accessing DMS 2200 with UAHS Accessing DMS 2200 with UAHS 9 Using UniAccess Hierarchical Service for DMS 2200

Provides information and guidelines to help you write client applications that use the UniAccess Hierarchical Service (UAHS) to access DMS 2200. The information contained here is relevant to both ODBC clients and Open Clients using the UniAccess ODBC Server for DMS 2200.

10 UAHS CommandsDescribes the non-DMS 2200 commands available through the UniAccess Hierarchical Service.

11 UAHS Catalog RPCsExplains the function and use of the UAHS Catalog RPCs. A reference section describes each supported Catalog RCP.

9-1

10-1

11-1


xx UniAccess for OS 2200 Client Guide


Section V: Advanced Data Access through UniAccess Advanced Data Access through UniAccess 12 Using UniAccess Transaction Server for OS 2200

Provides information that allows client applications to communicate successfully with user-written transactions, that is, transactions created with the UniAccess Transaction Server.

13 Using UniAccess Distributed Transaction CoordinatorProvides background and procedural information for the UniAccess Distributed Transaction Coordinator (UADTC).

12-1

13-1

Section VI: Appendixes A Client Examples

Provides examples designed to work with the sample system that is included with UniAccess.

B Server Program MessagesLists messages generated by UniAccess Transaction Server components, UniAccess ODBC Server components, or by Server-Library transactions and returned to client applications.

C UAMM Error MessagesLists error messages returned by the UniAccess Message Manager.

D TroubleshootingProvides troubleshooting assistance for problems that might arise in using Sybase System 10 Open Client and the UniAccess ODBC Driver in the PC environment.

E ReferencesLists technical references pertaining to the UniAccess System for OS 2200.

A-1

B-1

C-1

D-1

E-1


I Basics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part I

Basics

Chapter 1: Introduction to UniAccess System for OS 2200

Chapter 2: Application Development Overview


1 Introduction to UniAccess

1 Introduction to UniAccess System for OS 2200

This chapter provides an overview of Microsoft client/server architecture, ODBC architecture, and the UniAccess System for OS 2200. The information is relevant to all users of the UniAccess System.

Topics Page

Client/Server Architecture 1-2

Client/Server Overview 1-2

Types of Servers 1-4

Types of Clients 1-5

ODBC Architecture 1-5

The ODBC Interface 1-6

ODBC Components 1-6

UniAccess System for OS 2200 1-8

UniAccess ODBC Server for RDMS 2200 1-9

UniAccess ODBC Server for DMS 2200 1-11

UniAccess Transaction Server for OS 2200 1-11

UniAccess Transaction Client for OS 2200 1-12

Communication with the UniAccess System 1-12

What’s Next 1-14

1-2 UniAccess for OS 2200 Client Guide


Client/Server ArchitectureThe Microsoft® client/server architecture provides common interfaces across the client and server operating systems. This consistency allows software developers and integrators to use common tools and methodologies for the client and the server portions of an application and to move components between the client and the server as the need arises. Microsoft’s unified client/server architecture also delivers the broadest possible range of hardware and software support, bringing users a multitude of industry-leading development tools, end-user query tools, and off-the-shelf packages without restriction or modification. It provides the foundation for using the best of the present hardware and ensures a smooth migration to new hardware and software technologies as they become available.

Client/Server Overview

Client/server architecture divides the work of computing between clients and servers and defines an interface between them.

• Clients make requests of servers and process the results of those requests. For example, a client application might request data from a database server. Another client application might send a request to an environmental control server to lower the temperature in a room. (See Figure 1-1.)

• Servers respond to requests by returning data or other information to clients, or by taking some action. For example, a database server returns tabular data and information about that data to clients, and an electronic mail server directs incoming mail toward its final destination.

• An interface connects client and server software through clearly defined, message-based protocols. Interface components are often incorporated within client and server systems and may be transparent to the user.

Figure 1-1 illustrates the relationship between clients and servers.

NoteFor a discussion of types of client/server configurations, see Chapter 2.


Introduction to UniAccess System for OS 2200 1-3

Figure 1-1: Client/Server Model

Client/server architecture has several advantages over traditional program architectures:

• Application size and complexity can be significantly reduced, because common services are handled in a single location, a server. This simplifies client applications, reduces duplicate code, and makes application maintenance easier.

• Application logic can be split among several different servers and/or clients to achieve flexibility and performance. Organizations can leverage all of their available computing power across a variety of clients and servers.

action

server

serverclient

client

results

request for data

request to take an action

request for data

results

request for data

results



• Client/server architecture facilitates communication between varied applications. Client applications that use dissimilar communication protocols cannot communicate directly to each other, but can communicate through a server that speaks both protocols.

• Client/server architecture allows applications to be developed with distinct components, which can be modified or replaced without affecting other parts of the application.

• A robust client/server architecture enables enterprise environments to handle multiple, simultaneous events without degradation of performance. It provides the capacity to handle a growing number of transactions.

Types of Servers

The UniAccess System allows access to several types of servers, among them:

• UniAccess Servers (see page 1-8)

— UniAccess Transaction Server (UASL transactions)

— UniAccess ODBC Server for RDMS 2200 (UARS transaction)

— UniAccess ODBC Server for DMS 2200 (UAHS transaction).

• Non-UniAccess Servers (see Chapter 2)

— SQL Servers, including stored procedures on a SQL server

— SYBASE Open Server programs.

— RDMS 2200 stored procedures (supported by UniAccess ODBC Server for RDMS 2200).



Types of Clients

Basically, a client is any application that makes requests of a server. Valid clients within the UniAccess System include:

• ODBC-based applications using the UniAccess ODBC Driver, such as:

— End-user query and decision-support tools, such as Microsoft Query

— Vertical applications written with ODBC-compliant application development tools, such as Microsoft Visual Basic

— Administrative and development utilities such as Microsoft ODBC Test.

• Open Client applications, including the following:

— Applications written using SYBASE Open Client programming interfaces

— Applications written using UniAccess Transaction Client (UACL) programming interfaces, including ISQL for OS 2200

— Stand-alone utilities provided with SQL Servers, such as Interactive SQL.

ODBC ArchitectureMicrosoft® Open Database Connectivity (ODBC) is a comprehensive standard for accessing data in an environment of relational and non-relational database management systems (DBMSs). It defines a method for application programs to access databases from multiple DBMS vendors through a single programming interface. The core ODBC application programming interface (API) provides functions to connect to and disconnect from data sources, prepare and execute statements, describe and fetch result sets, retrieve error and informational messages, and process transactions.



ODBC is built upon the client/server computing model. An ODBC-enabled client application communicates with a DBMS through calls to the API. For every DBMS the application wants to connect to, there is a module called a driver. The driver translates the ODBC API calls to a format that the DBMS understands. The DBMS processes the call and sends the results back to the driver. The driver sends the results to the application. In addition to the application and the driver, a module called the Driver Manager provides the application with the list of available drivers and loads or unloads them as required.

The ODBC Interface

The ODBC interface defines the following:

• A library of function calls that allow an application to connect to a DBMS, execute SQL statements, and retrieve results (this is the ODBC API)

• SQL Syntax based on the X/Open and SQL Access Group (SAG) SQL CAE specification (1992)

• A standard set of error codes

• A standard way to connect and to logon to a DBMS

• A standard representation for datatypes.

ODBC Components

The ODBC architecture has four components, discussed below and illustrated in Figure 1-2.

• Application. A program that processes data and runs on a client workstation. The application calls ODBC functions to connect to a data source, submit SQL statements, retrieve results, and disconnect.

• Driver Manager. A dynamic link library (DLL) that provides information about available drivers and data sources to applications; it loads drivers on behalf of applications. All ODBC applications communicate with the driver manager and not directly with the driver.



• Driver. Sits between the Driver Manager and the network. The driver processes ODBC function calls, submits SQL requests to a specific data source, and returns results to the application. If necessary, the driver modifies an application’s request so that the request conforms to syntax supported by the associated DBMS.

• Data Source. Consists of the data the user wants to access and the associated operating system, DBMS, and network platform (if any) used to access the DBMS. An application can be connected to more than one data source at a time. These data sources can use the same DBMS or a variety of different DBMSs.

Figure 1-2: ODBC Components

ODBCInterface

Application

ODBC Driver Manager

Driver Driver Driver

DataSource

DataSource

DataSource



The ODBC API and the Driver Manager are provided by Microsoft. ODBC drivers, on the other hand, are written by a variety of vendors for a variety of DBMSs. For example, the UniAccess ODBC Driver has been written by AIS for use with UniAccess System for OS 2200 products. Since drivers are written to comply with specific ODBC standards, all ODBC components appear to the application as one unit that processes ODBC function calls.

UniAccess System for OS 2200The UniAccess System for OS 2200 implements Microsoft client/server architecture for the Unisys OS 2200 system. It provides seamless integration among DBMSs, applications, and hardware systems within a TCP/IP-based network environment. Any application development tool, end-user tool, database server, Internet server, or transaction processing system compatible with the Microsoft architecture may interoperate through UniAccess with any data source or program on an OS 2200 system. Thus, UniAccess transforms OS 2200 systems into Microsoft enterprise servers and enables the modernization of existing applications and databases to client/server, intranet, or internet applications.

UniAccess client, server, and interface components interact transparently with both local and remote services, allowing the client application to retrieve and manipulate data easily from an OS 2200 host. The OS 2200-based servers are UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200. They process requests from PC-based ODBC clients and Open Clients as well as from UniAccess Transaction Client. The UniAccess Transaction Client allows OS 2200 applications to make requests of various servers, including SQL Servers and OS 2200 transactions. To the client, the processes of the three UniAccess servers appear the same as those of a SQL Server. The processes of the Transaction Client, on the other hand, appear the same as other Open Client applications.

The UniAccess System gives users the flexibility to access and update a variety of data sources. Clients using UniAccess ODBC Server for RDMS 2200 have Structured Query Language (SQL) access to Unisys Relational Database Management System 2200 databases. Clients using UniAccess ODBC Server for DMS 2200 have SQL query access to Unisys Database Management System 2200 databases. In addition, programmers using UniAccess Transaction Server for OS 2200 can write transactions that can access any type of data on the OS 2200 system (e.g. RDMS, DMS, MAPPER, PCIOS, TIP-FCSS, etc.).



UniAccess ODBC Server for RDMS 2200

UniAccess ODBC Server for RDMS 2200 provides SQL 89 access to Unisys RDMS databases for both ODBC-compliant and Open Client applications. It includes the host-based UARS transaction, the communications server (UACS)—which translates and routes requests between clients and servers, and other core (interface) components that define, manage, and relay system information. It also includes the client-based UniAccess ODBC Driver and the UniAccess Distributed Transaction Coordinator. This product is intended for Unisys RDMS users to begin building client/server applications without mainframe-based programming.

UniAccess Relational Service

UARS (UniAccess Relational Service for RDMS 2200) is an OS 2200 transaction that accepts SQL language requests from clients, processes the requests using the RDMS 2200 interpretive SQL interface, and returns results to clients. It provides essential preprocessing and postprocessing services, including some datatype and architecture conversions. In addition, UARS supports RDMS stored procedures and may be configured to process RDMS procedure requests. It also provides ODBC-type catalog information in response to client requests. UARS is an AIS-written TIP transaction, built with UniAccess Server-Library functions. UARS is explained in more detail in Chapter 6.

UniAccess ODBC Driver

The primary UniAccess ODBC component is the PC-based UniAccess ODBC Driver (UADriver). The driver allows Microsoft ODBC-compatible client applications and tools to have ODBC access to OS 2200. The driver processes ODBC function calls from a wide variety of client tools, submits SQL requests and procedure calls to OS 2200 databases, and returns results to the application. It works in conjunction with the Microsoft supplied Driver Manager, appearing to the application as one processing unit.

In the UniAccess System, UADriver allows access to RDMS 2200 through the UARS transaction, to DMS 2200 through the UAHS transaction, and to other OS 2200 databases from user-written, UASL-based transactions. The UAINFO transaction is provided to allow UADriver to operate in a non-UARS, non-UAHS environment. UADriver is discussed in more detail in Chapter 5. Figure 1-3 illustrates how ODBC architecture has been implemented in the UniAccess System.



Figure 1-3: UniAccess ODBC Architecture

UniAccess Distributed Transaction Coordinator

UniAccess distributed transaction support extends Microsoft Windows distributed transaction capabilities to the Unisys OS 2200 environment. With the UniAccess Distributed Transaction Coordinator (UADTC) serving as a gateway between the Microsoft Distributed Transaction Coordinator (MS DTC) and the UniAccess System, OS 2200 distributed-transaction-enabled resources can be updated as part of an MS DTC-controlled transaction. UniAccess’ distributed transaction support uses proven transaction processing technology: it is robust despite system failures, process failures, and communication failures; and it exploits loosely coupled systems to provide scalable performance. (See Chapter 13 for and overview of distributed transaction processing and its implementation in the UniAccess System.)

ODBCInterface

Data

Source

Client

Server

Application

ODBC Driver Manager

UniAccess ODBC Driver

Open-Client Library

Network Library

Network Software

UniAccess Transaction Server /UniAccess ODBC Servers for RDMS and DMS

RDMS 2200 / DMS 2200 / Other OS 2200 Data



UniAccess ODBC Server for DMS 2200

UniAccess ODBC Server for DMS 2200 provides access to Unisys DMS databases for ODBC-compliant and Open Client applications. It includes the host-based UAHS transaction and the client-based UADriver discussed above. It also includes UACS—the communication server—and other core components. This product allows DMS users to begin to build client/server applications without mainframe-based programming.

UniAccess Hierarchical Service

UAHS (UniAccess Hierarchical Service for DMS 2200) is an OS 2200 transaction that provides multi-user SQL query capability to DMS 2200 databases. This service creates a meta database containing DMS schema information and a relational mapping of the schema. UAHS uses this relational view of a DMS database to process retrieve-only SQL language requests; ODBC catalog functions access the meta database to obtain DMS catalog information. UAHS is an AIS-written TIP transaction, built with UniAccess Server-Library functions. UAHS is explained in more detail in Chapter 9.

UniAccess Transaction Server for OS 2200

UniAccess Transaction Server allows ODBC-compliant and Open Client applications to invoke new and existing Unisys TIP transactions on the OS 2200 system. Using Transaction Server tools, OS 2200 programmers can create transactions to access a variety of OS 2200 data. The UniAccess Transaction Server includes the host-based UniAccess Server-Library, the communications server (UACS)—which translates and routes requests between clients and servers, and other core components that define, manage, and relay system information. It also includes the client-based UniAccess ODBC Driver and the UniAccess Distributed Transaction Coordinator.

UniAccess Server-Library

UASL (UniAccess Server-Library) provides a library of functions that allow programmers to create individual transactions that run on the OS 2200 system. Programmers can assemble transactions from pre-built software parts rather than write each transaction from scratch. They use these functions primarily to create RPC-processing transactions, although they may create general-purpose language transactions as well.



Transactions written with Server-Library functions appear and act like stored procedures on SQL Servers—they follow similar routines to connect and communicate with specific environments. (UASL functions are documented in the UniAccess for OS 2200 Server-Library Programming Reference.)

UniAccess Transaction Client for OS 2200

UniAccess Transaction Client is the group of UniAccess System products that provide client capabilities on the OS 2200 system. It includes the UniAccess Client-Library, a library of functions that allow programmers to write OS 2200 client applications. It also includes UACS—the communication server—and other core components. UniAccess Client-Library applications may make requests of SQL Servers and Open Servers, in addition to the UniAccess for OS 2200 servers.

Since this manual is concerned with client applications that are remote to the OS 2200 host, the UniAccess Transaction Client will not be discussed here. UACL functions are documented in the UniAccess for OS 2200 Client-Library Programming Reference.

Communication with the UniAccess System

For the ODBC client or the Open Client, sending a request to an OS 2200 host is no different than sending a request to a SQL Server. The actions taken by the UniAccess Communication Server to schedule a TIP transaction and retrieve transaction results are transparent to the client. The client receives the results in TDS (Tabular Data Stream) format, just as if they had come from a SQL Server.

UniAccess Communication Server

UACS (UniAccess Communication Server) on the OS 2200 system provides the central communication link between client and server applications. UACS accepts client requests and routes them to their corresponding server transactions. When the transaction finishes processing the request, UACS returns the results to the client. The operations of UACS are transparent to the client and require no additional programming or knowledge of its communications protocols. UACS can handle large numbers of users, and multiple UACSs may run on a single host.



The OS 2200 Environment

The UniAccess System provides access to host resources by facilitating communication between a client and a TIP transaction. TIP is an on-line transaction-processing system that runs on the Unisys OS 2200 system. It provides an environment that allows the user-written TIP transactions to retrieve or modify host resources.

To communicate with UACS and the client application, TIP transactions in the UniAccess System use the special set of functions (linkable subroutines) provided by AIS. These functions use TDS to return the results to the client, just as a SQL Server would. TDS is the application layer protocol used by the Microsoft architecture for client-to-server and server-to-server interoperability. The data is row-oriented and self-describing. The information in the TDS reply includes the names, datatypes, and formats of columns. Since the TIP transaction uses TDS to communicate with UACS, results are forwarded quickly and efficiently. TIP enables clients in large and small networks to execute individual transactions with host databases in short response times.

ODBC and Open Client programmers working with the UniAccess System write applications that will be processed by TIP transactions on the OS 2200 host. Language requests can be processed by the AIS-supplied UARS or UAHS transactions, which provide access to RDMS 2200 or DMS 2200 respectively. They can also be handled by a user-written language-processing UASL transaction, written to access any OS 2200 data source. RPCs are processed by user-written UASL transactions. A UASL transaction must exist for each RPC. UASL transactions are the responsibility of the OS 2200 application programmer and are discussed in the UniAccess for OS 2200 Server-Library Programming Reference.

To initiate a TIP transaction, a UniAccess System client can run a client program from a workstation or make a request through a Microsoft SQL Server. The UACS component accepts language requests and RPCs and passes them on to the appropriate TIP transaction. (These different types of client requests are explained in detail in Chapter 2).

Figure 1-4 illustrates how the UniAccess System might be implemented for PC clients on a LAN network.



Figure 1-4: UniAccess PC Client Environment

What’s NextIn Chapter 2, readers learn about the different types of client requests available in Microsoft client/server architecture and how ODBC client and Open Client programmers employ these requests within the UniAccess System.

Part 2 of the manual helps you get started using the UniAccess System, beginning with Chapter 3 that describes the installation procedures for both UniAccess ODBC and non-ODBC installations.

UniAccess ODBC Client

OS 2200 host

other host dataRDMS 2200

communication management systems

MicrosoftSQL Server

UniAccess services, including UACS

user-written UASL transactions

UARStransaction

UAHStransaction

DMS 2200

Open Client

UniAccess ODBC Client UADTC MS DTC


2 Application Development

2 Application Development Overview

Client-server architecture separates applications into two functional categories—client and server. Client applications provide user interface and presentation logic; they make requests of server applications. Server applications provide the logic to accept client requests, process them using host resources, and return the results to the client.

Client/server architecture defines the methods by which client applications pass their requests to server applications, and how servers, in turn, reply to client requests. This chapter gives an overview of client requests and then explains how ODBC client and Open Client programmers employ these requests within the UniAccess system to invoke TIP transactions on the OS 2200 host.

Topics Page

Types of Computing Configurations 2-2

Services Model of Application Composition 2-2

Physical Implementation 2-2

Types of Requests 2-7

Language Requests 2-7

Remote Procedure Calls (RPCs) 2-7

Comparing Language Requests and RPCs 2-8

Client Applications with the UniAccess System 2-9

Sending Language Requests 2-10

Sending Procedure Calls 2-12

What’s Next 2-13



Types of Computing Configurations The UniAccess System implements Microsoft client/server architecture to allow greater flexibility of communication among the various server systems of an organization. This allows organizations to leverage all of their available power across a variety of clients and servers. The following section reviews the basics of two- and three-tier models and overviews how they are implemented in the UniAccess System.

Services Model of Application Composition

What constitutes the parts of an application depends on the specific nature of the application. There are, however, three common categories of services in typical business applications that almost always occur:

• Presentation Services — interaction with the user: presentation of information and functionality, navigation, protection of user interface consistency and integrity

• Business Services — generation of business information from data, determination of application flow, governance of shared business policies, protection of business integrity

• Data Services — definition of data, storage and retrieval of persistent data, protection of data integrity.

The services model describes the conceptual or logical architecture of an application. The model suggests that any service may physically reside anywhere, and depending on specific functional requirements, any service may invoke any other service. Thus, an application becomes a collection of user, business, and data services that meets the needs of the business process or processes it supports. Because services are designed for general use and follow published interface guidelines, they can be reused and shared among multiple applications, providing a high degree of flexibility and reusability.

Physical Implementation

In deploying an application, there are many possible arrangements of the three logical layers of services on physical machines. The following sections describe how UniAccess is generally implemented—a deployment that follows standard Microsoft implementation.


Application Development Overview 2-3

Implementation of Two-Tier Model

In a two-tier configuration for an enterprise server, the client and a single server communicate directly with one another. That is, an individual at a client workstation submits requests to an enterprise server that responds to that request. In the UniAccess implementation of this model, the user services are allocated to the client tier and the data services allocated to the server tier, while the business services are split among both tiers (see Figure 2-1).

Figure 2-1: UniAccess Implementation of Logical Two-Tier Model

Unlike other systems that may require a gateway between the client and enterprise server, the UniAccess System allows this direct communication by means of the UniAccess Communication Server, located on the OS 2200. Both ODBC clients and Open Clients can communicate directly with OS 2200 TIP transactions (servers). Communication between client and server in the UniAccess system is fast and efficient, allowing multiple simultaneous events and procedures on the OS 2200 while appearing to the client as a familiar SQL Server.

Workstation

Presentation ServicesBusiness Services

Open Client

Client Tier

Data ServicesBusiness Services

Enterprise Server

Server Tier

ODBC Client

TDS

ODBC / TDS

UniAccess on OS 2200



Implementation of Two-and-a-Half-Tier Model

A two-and-a-half tier model—which has sometimes been termed a three-tiered model—employs stored procedures as a mid-tier component. Stored procedures provide a way for clients to execute groups of SQL statements remotely on the database server or a mid-tier server instead of on the client itself. Stored procedures reduce network traffic by minimizing the data that must be exchanged back and forth with the client, improve security by limiting use to authorized clients, and improve application reuse by enabling multiple presentation components to call the same stored procedure centrally. Stored procedures also improve scalability.

In the UniAccess System, Microsoft SQL Servers offer stored procedure support for clients accessing UniAccess servers on the OS 2200. Stored procedures can be used to reference other stored procedures or to issue language requests, which means they can function simultaneously as both clients and servers within a larger client/server framework. In the UniAccess environment, stored procedures may also exist on RDMS 2200.

Figure 2-2: UniAccess Implementation of Logical Two-and-a Half-Tier Model

Data Source TierClient TierEnterprise ServerWorkstation

Data Services


Presentation Services

TDS

Business Services

MicrosoftSQL Server (storedprocedures)

Middle Tier

Local Network Server

ODBC / TDS

ADO/OLE DB/

ODBC Client

ADO/OLE DB/

ODBC Client



Implementation of Three-Tier Model

In a three-tier configuration for an enterprise server, the presentation, business, and data service components are separated into distinct units. While there is no requirement that each unit run on a different physical machine, to deliver maximum benefit, three-tiered systems must run with presentation components on desktop clients or browsers, application logic on middle-tiered servers, and data on dedicated database servers (see Figure 2-3). Clients can call as many server-based components as they need to complete a request, and components can call other components to improve reuse.

Middle tier support may come from transaction processing environments such as Microsoft Transaction Server (MTS) running on Windows NT Server. Using MTS, UniAccess developers can use their existing skills with tools such as Visual Basic to build sophisticated three-tiered applications. Developers can generate the business service components of their programs as objects that run on middle-tier servers. These components can use UniAccess ODBC services to access OS 2200 based resources (RDMS, DMS, FCSS, etc.). By combining UniAccess with MTS, customers can see a number of benefits:

• The ability to employ sophisticated run-time services such as automatic thread pooling, database connection pooling, and object instance management for greater performance and scalability.

• The ability to develop application logic components with tools of choice: VB, VC++, VJ++, etc.

The Internet has extended the possible implementation of the three-tier model, providing the ability to split the user services onto a browser client and a Web server. The Web server is actually responsible for formatting the pages that the user sees. The browser is responsible for displaying these pages and downloading additional code they may need. Between the Web server and the database, the choices remain the same for locating the business services logic.

NoteThe above discussion has assumed that the server application is viewing or updating data on a single data source. For information on distributed transactions, that is, on server applications that update data on two or more data sources, see Chapter 13.



Figure 2-3: UniAccess Implementation of Logical Three-Tier Model

The options for implementation of the logical three-tier model will not be discussed further in the UniAccess documentation because they do not affect the essential client/server relationship between clients, Microsoft SQL Servers, and UniAccess on the OS 2200.

Client Tier Data Source Tier Middle Tier

Presentation Services

Browser

clientCOM/DCOM

Data Services


Business ServicesBusiness Services

HTTP

MicrosoftSQL Server (storedprocedures)

ODBC/ TDS

Workstation Enterprise ServerLocal Network Servers

ODBC / TDS

ODBC / TDS

TransactionProcessingEnvironment

ODBC/ TDS



Types of RequestsIn the Microsoft client/server architecture, a client application can access a server application in one of two ways:

• By executing a language request

• By making a remote procedure call (RPC) to a server transaction or to a stored procedure on a server.

The following sections describe each of these types of requests and the comparative advantages of each.

Language Requests

A language request contains character strings that represent requests in a server’s own language. Language requests are flexible and interactive. They may be built on anad hoc basis or be predefined. A language request may contain one or more language statements. If the server’s language includes native support of stored procedures, a language request can contain a procedure call.

A language request can be in any language as long as the server to which it is directedunderstands it. For example, SQL Servers understand Transact-SQL and RDMS 2200understands RDMS 2200-compliant SQL. The client language application, therefore, must send only statements that are understood by the server.

Open Client users must generally handle these language differences themselves, while an ODBC driver will handle many of the language differences for ODBC clients.

Remote Procedure Calls (RPCs)

A procedure is executable code that is stored on the server. Some examples of procedures are a Server-Library transaction on a UniAccess Transaction Server, an Open Server application, an RDMS 2200 stored procedure, and a stored procedure on a Microsoft SQL Server. A remote procedure call (RPC) is a request issued by a client application and directed to a particular procedure on a server. Each RPC must be associated with and mapped to a specific procedure on the server. Thus, to access OS 2200 resources using an RPC, there must be either an OS 2200 TIP transaction or an RDMS 2200 stored procedure to satisfy the request.



NoteThe term RPC is an Open Client term. ODBC applications make procedure calls that are converted to RPCs by UADriver. However, for simplicity of discussion, the UniAccess documentation refers to calls to procedures as RPCs when they may be issued by either ODBC or Open Client applications.

The client and server applications that process RPCs are specifically written to correspond to one another. For example, the format of the request created by the client application must be understood by the server application and the results returned by the server must be understood by the client. Programmers must ensure that each RPC is mapped to a corresponding procedure on the server that will receive it.

Comparing Language Requests and RPCs

Generally, RPCs are faster and more efficient than language requests, while language requests allow end users more flexibility than RPCs. In considering which type of request to use, programmers might consider the following points.

• Each RPC is processed by a unique procedure, designed to perform a specific function or group of functions. Language requests, on the other hand, are processed by general-purpose data-access transactions.

AIS provides two language transactions—UARS and UAHS. These AIS-provided transactions process SQL grammar to provide ad hoc access to either RDMS 2200 or DMS 2200 data respectively. Additional language transactions can be written. A language transaction should be general purpose and must understand both the request format and the database structure.

• Any type of data on the OS 2200 system (e.g. RDMS, DMS, MAPPER, PCIOS, TIP-FCSS, etc.) can be accessed by an RPC, using UniAccess Server-Library transactions as the procedures that process the RPCs. A new language transaction would be required to access any data other than DMS 2200 and RDMS 2200 data.

• Site-written procedures (namely, the Server-Library transactions that process RPCs) can maintain the business rules on the server where they cannot be accidentally or intentionally bypassed by the client application. A language



transaction, however, which allows access to the database via SQL grammar, is not usually written for a specific application and set of business rules.

• Procedures can be better optimized for performance on the server. For example, UniAccess Server-Library transactions accessing an RDMS database can utilize embedded SQL, which will be parsed once, while a language request uses dynamic SQL, which must be parsed every time the request is issued.

• An RPC passes parameters in their native datatypes, in contrast to a language request in which parameters must be converted to ASCII characters.

Client Applications with the UniAccess SystemA UniAccess server (UniAccess Transaction Server for OS 2200, UniAccess ODBC Server for RDMS 2200, or UniAccess ODBC Server for DMS 2200) can be accessed by two categories of client applications:

• ODBC applications, via the UniAccess ODBC Driver

• Open Client applications.

ODBC applications using UADriver access the OS 2200 host the same as they would any other ODBC compliant data source. The ODBC driver sends language requests, catalog procedure requests, and procedure calls to the OS 2200 host. Hundreds of ODBC applications and tools are available to UADriver users. Open Client applications using the UniAccess System access the OS 2200 host the same as they would access a SQL Server. The Open Client may send language requests or RPCs to the OS 2200 host. The same variety of Open Client software products is available to UniAccess System clients as to clients of SQL Servers.

Sample RPCs and SQL language requests, using both ODBC and Open Client interfaces, are provided on the UniAccess 10R3 PC Client CD.



Sending Language Requests

In the UniAccess System, language requests are processed by a TIP transaction, designated by UACS to receive language requests. The user calls one of the language transactions provided by AIS or a user-written language transaction provided by the site (see Figure 2-4).

AIS provides two language transactions to process dynamic SQL requests. The UniAccess Relational Service (UARS) handles dynamic SQL requests directed at RDMS 2200 data; the UniAccess Hierarchical Service (UAHS) handles dynamic SQL requests directed at DMS 2200. (See Chapter 6 for a discussion of UARS and Chapter 9 for a discussion of UAHS.)

NoteUACS can concurrently support three language transactions. Support of three language transactions includes a provision for a user-written language transaction. A user-written language transaction can process whatever syntax (language) the programmer designs into the transaction.

Client language applications must be written to ensure that the language statements and datatypes are compatible with those of the host database that the server transaction has been designed to access. Likewise, the client application must ensure that it will understand the format of the returned data. The extent to which the client programmer must be aware of the difference between the syntax and constructs between the client’s SQL language and the host database language depends on whether the client is an ODBC application or an Open Client application.

For ODBC applications, UADriver will handle many of the differences in SQL grammar to generate compliant SQL for UARS or UAHS. For additional information about using UARS with UADriver see Statement Considerations for ODBC Clients (page 6-6).

For Open Client applications, the application programmer must ensure SQL statement and datatype compatibility. For specific information about compatibility with UARS, see Chapter 6; for information about compatibility with UAHS, see Chapter 9.



Figure 2-4: Two-Tier and Multi-Tier Language Requests

OS 2200 Host

server

MicrosoftSQL Server

server / client

stored procedure

language request

UACS

user-writtenlanguageprocessing

UASL transaction

UAHStransaction

DMS2200

UARStransaction

RDMS2200

Other OS 2200

Data

Note: A stored procedure on a Microsoft SQL Server can issue a language request to a UniAccess Server. The request is made through UADriver.

OpenClient

Workstation

client

client

ADO/OLE DB/ODBCClient

language request



Sending Procedure Calls

An ODBC application using the UniAccess ODBC Driver can call a UASL transaction on OS 2200 or an RDMS 2200 stored procedure (see Figure 2-5). The transaction or procedure is called the same as a procedure on any other ODBC data source.

An Open Client application using the UniAccess System can send a remote procedure call to a UASL transaction on OS 2200 or an RDMS 2200 stored procedure. This arrangement allows a client to use a familiar method, the RPC, to execute various server applications.

Figure 2-5: Two-Tier and Multi-Tier Procedure Callsin the UniAccess Environment

OpenClient

OS 2200 Host

Workstation

client

server

server / client

UACS

UARStransaction

user-writtenRPC processingUASL transaction

RDMSStoredProcedure

RDMS2200

Other OS 2200

Data

DMS2200

MicrosoftSQL Server

stored procedureclient

ADO/OLE DB/ODBCClient

procedure call

RPC

RPC

RPC



Using either the ODBC interface or the Open Client interface, the developer of client applications does not need to be concerned with the processing environment on the server. UACS receives the client request and routes it to the appropriate UASL transaction. Calls to RDMS 2200 stored procedures are routed to the UARS transaction. The client receives and processes the results.

NoteThe procedure name you use must match a procedure on the server. The UniAccess configuration provides a method of mapping procedure names. Check with your system administrator or OS 2200 applications programmer to determine appropriate names.

What’s NextThe following section, Part II, presents information important to all client users of the UniAccess System. Chapter 3 describes UniAccess PC Client installation procedures. Chapter 4 presents specific, shared information about using UniAccess System. Chapter 5 describes the UniAccess ODBC Driver and provides instructions on configuring and connecting to a data source.

II Getting Started

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part II

Getting Started

Chapter 3: Installing Client Software

Chapter 4: Using the UniAccess System

Chapter 5: Using the UniAccess ODBC Driver


3 Installing Client Software

3 Installing Client Software

This chapter describes UniAccess PC Client system requirements and installation procedures for both ODBC clients and Open Clients.

Topics Page

System Requirements 3-2

Client Software 3-2

UniAccess 0S 2200 Software 3-3

Network 3-3

UniAccess ODBC Driver Installation 3-4

Standard PC Installation 3-4

Network Installation 3-5

Microsoft Systems Management Server (SMS) Installation

3-6

Customized Data Source Configuration and Translator Installation

3-7



System RequirementsUniAccess PC client hardware and software requirements are based upon the functionality desired at the workstation. The following sections describe these minimum requirements.

Client Software

PC Client software requirements are driven by the operating system required to support key client functionality.

ODBC Environments. The following table identifies the operating system requirements for the ODBC-related components based on function.

Table 3-1: UniAccess PC Client Software Requirements

Non-ODBC Environments. For customers utilizing Open Client applications in a non-ODBC environment, please refer to your Sybase documentation.

Operating SystemClient Functionality

UADriver1 UADTC MS DTC

Microsoft Windows ME X

Microsoft Windows NT 4.0 with MDAC 2.1 or later

X X

Microsoft Windows 2000 or later X X X

1 In order to participate in distributed transactions, UADriver must be located on a machine running Windows 2000 or later (see page 13-9).


Installing Client Software 3-3

UniAccess 0S 2200 Software

To access OS 2200 with UADriver, you will use one or more of the following UniAccess products on the OS 2200:

• UniAccess ODBC Server for RDMS 2200 with its UARS transaction

• UniAccess ODBC Server for DMS 2200 with its UAHS transaction

• UniAccess Transaction Server for OS 2200, with the UAINFO transaction installed and with site-written RPC-processing or language-processing transactions created using UniAccess Server-Library.

For information about the hardware and software required by UniAccess product packages, see Chapter 3 of the UniAccess for OS 2200 System Administration Guide.

Network

UADriver requires TCP/IP connectivity from the PC to the OS 2200 host. UADriver uses the TCP/IP protocol to communicate with the OS 2200 host.

UADTC, MS DTC, and the COM+ component(s) can be on a single machine or on multiple machines. There must be network connectivity between MS DTC and UADTC, the COM+ component and MS DTC, the COM+ component and UADTC, and UADTC and the OS 2200 host. (See Chapter 13 for more information.)



UniAccess ODBC Driver InstallationThis section describes standard and advanced procedures for UniAccess ODBC Driver (UADriver) installation.

Standard PC Installation

The standard UniAccess ODBC Driver installation is performed by a customized Windows Setup program. This program installs all of the files required to enable ODBC applications to connect with UniAccess. To install the UADriver directly from the UniAccess 10R3 PC Client CD, complete the following steps:

1. You must logon to the PC as a user with administrator privileges, because the UADriver Setup makes changes to the system environment variables.

2. The UniAccess 10R3 PC Client CD will automatically launch the setup menu when the CD is inserted into the CD-ROM drive.

3. Select Install the UniAccess 10R3 ODBC Driver from this menu. This will begin the UADriver installation process.

4. The UADriver Setup displays a welcome dialog box and a license agreement. The installation will proceed if you choose next and yes respectively, otherwise choosing cancel or no will terminate the installation.

5. Setup prompts you to choose a destination location to install UADriver and associated files. The default location is “ \Program Files\Applied Information Sciences\UA10R3” on the boot drive. Choose next if you wish to accept the default location. Select browse if you wish to change the default location.

6. The setup menu allows you to install the UniAccess ODBC Driver and UADTC, install the SDK, browse the CD, view the documentation, contact UniAccess support, or visit the UniAccess web site. Choose Install the UniAccess 10R3 ODBC Driver to install the UADriver and supporting files.

7. Setup prompts you to choose a program folder in which to install the UniAccess product. The default folder is UniAccess 10R3 PC Client. Choose next if you wish to accept the default folder. Alternatively, you can type the name of a new folder or select an existing one from the existing folders list.



8. If a previous UniAccess ODBC Driver installation is found, setup will query you about whether or not you want to remove it. Select yes if you wish to have setup remove the previous installation and continue with the setup. Select no if you wish to retain the previous installation and terminate the 10R3 setup.

9. Setup may display a You must reboot the computer for the changes to take place message. (This message will appear if setup must modify the system environment variables.) Select yes to reboot if you wish to begin using the UniAccess product immediately. Select no if you wish to reboot at a later time.

10. This completes the UniAccess 10R3 ODBC Driver installation.

One or more data sources or translators can be configured automatically as part of the standard installation. Please refer to Customized Data Source Configuration and Translator Installation in this chapter for these instructions.

Network Installation

The UADriver Setup program supports automatic setup from a network directory. Network installations are useful for multi-user environments, allowing users to install from a common location. The setup options are controlled by an ASCII text information file that is read by the setup program during the installation process. The default name of this file is setup.iss. This file is supplied on the UniAccess 10R3 PC Client CD.

When an automatic setup is run, a log file is created in the same folder as the information file. The log file has the default name Setup.log if the -f2 switch is not provided along with -f1.

Setup supports the following command line options to facilitate automated network installs:

odbc –s or /s -f1<path\IssFile> or /f1<path\IssFile> -f2<path\LogFile> or/f2<path\LogFile>

where:

-s or /sperforms an automated installation where no user input is required.



-f1<path\IssFile> or /f1<path\IssFile>specifies an alternate name and location of the iss file. The default iss file is setup.iss and it must reside in the same directory as setup.exe.

-f2<path\LogFile> or /f2<path\LogFile>specifies an alternate name and location of the log file. By default, the log file setup.log is created and stored in the same directory as that of setup.exe.

NoteYou have the option of letting setup create the information file for you. To do so, run your setup with the setup.exe -r command line parameter. The setup will record all your setup choices in setup.iss and place the file in the Windows folder. This file must then be copied to the same directory as setup.exe.

To perform network installations, the contents of the CD-ROM disc must be copied to a single network directory. One or more data sources or translators can be configured automatically as part of the network installation. Please refer to Customized Data Source Configuration and Translator Installation chapter for this instructions.

Microsoft Systems Management Server (SMS) Installation

The UADriver Setup program supports Microsoft System Management Server (SMS) package installation. In order to perform an SMS setup, you must launch the odbc.exe with the command line odbc.exe -s. A package definition file (PDF) is provided on the UniAccess 10R3 PC Client CD for performing an SMS package installation of the UniAccess ODBC Driver. This PDF file can be imported by SMS to define an installation package automatically.

Additionally, the MIF file is created during the installation by using the -m command-line option to the odbc.exe. The optional /mFilename creates an MIF file usually in the temp directory. You can pass a filename for the MIF file, but not an alternative path; if you do not specify a filename, the MIF file is named Status.mif.

One or more data sources or translators can be configured automatically as part of the SMS installation. Please refer to the next section, Customized Data Source Configuration and Translator Installation, for these instructions.



Customized Data Source Configuration and Translator Installation

Customized ODBC Data Source Configuration

The UADriver Setup program is structured to support the installation of one or more ODBC data sources. To accomplish this, the _drivers.ini file must be updated to add an entry to the [Data Sources] section for each data source to be added automatically. The entries must be named DSN1 through DSNn, where n is the number of the last DSN being configured. These numbers must be in sequential order. Then a new section name must be created for each DSN.

NoteThe value supplied after DSNn in the [Data Sources] section must match the name supplied in the corresponding [DSNn] section.

The UADriver attributes described in Table 5-6 summarize all available options that may be specified for a DSN. Required attributes are:

DSN=The name of the DSNHOST=The host i.p. address or namePORT=The port number associated with this UACS.LANGTYPE=Defines the set of services and the default language transaction being used with this data source

Table 3-3 lists all possible LANGTYPE values for all combinations of services and language transactions.



Table 3-2: LANGTYPE Values

Additionally, the following keywords and their values may be modified to provide further customization of the DSN:

Description=The DSN description displayed in the ODBC Administrator.UID=user idISODBCDSNType=The type of data source being installed. The following values are available: user = (default) user data source system = system data source file = (not supported) file data source

Example

The following is an example of the UniAccess ODBC Driver _drivers.ini file that will automatically configure three DSNs named UACS_DSN, UACS1_DSN, and UACS2_DSN.

[Data Sources]DSN1=UACSDSN2=UACS1DSN3=UACS2

ServicesUARS

Language Transaction

UAHS Language

Transaction

User-written Language

Transaction

No Language Transaction

UAHS n/a 18 n/a n/a

UARS 33 n/a n/a n/a

UASL n/a n/a 67 68

UAHS + UARS 49 50 n/a n/a

UAHS + UASL n/a 82 83 84

UARS + UASL 97 n/a 99 100

UAHS + UARS + UASL

113 114 115 116



[UACS]DSN=UACS_DSNHost=hq1s0016Port=2050Description=UniAccess UACS DSNLoginID=ISODBCDSNType=SYSTEMLANGTYPE=33

[UACS1]DSN=UACS1_DSNHost=hq1s0016Port=2050Description=UniAccess UACS1 DSNLoginID=ISODBCDSNType=USERLANGTYPE=33

[UACS2]DSN=UACS2_DSNHost=hq1s0016Port=2050Description=UniAccess UACS1 DSNLoginID=bluefishISODBCDSNType=SYSTEMLANGTYPE=97

Customized Translation DLL Installation

The UADriver Setup program is structured to support the installation of one or more translation DLLs. To accomplish this, the translation DLL and setup DLL (if a separate setup DLL is required) must be placed in a subdirectory named \translator on the first installation disk or in the network directory if a network installation is being performed. Then _drivers.ini file must be updated to specify the name of the translation DLL. A line must be added to the [Translators] section for each translation DLL to install. The entries must be named Translator1 through Translatorn where n is the number of the last translation DLL being configured. Then a new section must be created for each translation DLL specified.



NoteThe value supplied after Translatorn in the [Translators] section must match the name supplied in the corresponding [translator] section.

The entries Translator and Setup must be specified for each new section. These entries specify the name of the translation DLL. When the setup program is run, the customized translation DLL(s) will be installed automatically in the \dll directory of the UADriver installation folder.

The following is an example of the sections of the UniAccess ODBC Driver _drivers.ini file that will install a translator called uatran32.dll:

[Translators]Translator1=UniAccess Translator

[UniAccess Translator]; if used, change "uatran32.dll" to the translator dll; do not remove "<TARGETDIR>\dll" from the Translator or ; Setup statements.; create a\translator directory in the directory containing ; odbc.exe and copy your; translator to this directory.Description=UniAccess TranslatorTranslator=<TARGETDIR>\dll\uatran32.dllSetup=<TARGETDIR>\dll\uatran32.dll


4 Using UniAccess

4 Using the UniAccess System

This chapter presents specific information about the UniAccess System that is applicable to all client environments. It also indicates which subsequent sections of the manual are relevant to specific environments.

Topics Page

General Considerations 4-2

Levels of TDS Support 4-2

Establishing Connections 4-2

Changing Passwords 4-4

Connection Timeout Interactions 4-4

Architecture Considerations 4-4

User Datatypes 4-5

What’s Next 4-8

Pointers for ODBC Users 4-8

Pointers for Open Client Users 4-9



General ConsiderationsThe UniAccess System provides access to OS 2200 resources by facilitating communication between a client application and an OS 2200 TIP transaction. The operations of the UniAccess System in providing this support are transparent to the user. The work of configuring, managing, and maintaining security for the system is performed by the system administrator. However, there are particular features and limitations of the UniAccess System of which the client user must be aware.

Levels of TDS Support

In the 10R3 release, the UniAccess System offers the following levels of support:

• TDS 4.6 and 5.0 are supported at the 4.2 level.

• TDS 4.0 and 4.2 are supported.

• TDS 2.0 and 3.4 are not supported.

Establishing Connections

Several security and environment issues for the UniAccess System and the OS 2200 Operating System are handled through the UniAccess Configuration File. This file is set up and maintained by the system administrator. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide for information about specific configuration statements, including those mentioned below.) The following configuration issues may affect your ability to connect to the UniAccess System.

Required Validation of Userids

The system administrator can require that the UniAccess System validate all userids against a list of specified users. This happens when the COMSRV USEUAUSER parameter of the UniAccess Configuration File is set to YES. In this case, access to invalid users is denied. Otherwise, the UniAccess System does not validate userids, although other ID validation features may be implemented in your system.


Using the UniAccess System 4-3

TIP Session Control Requirements

The UniAccess System allows TIP session control on the OS 2200 mainframe to be turned on. When it is, you must use a valid OS 2200 userid and password. In addition, if the COMSRV USEUAUSER parameter of the UniAccess Configuration File is set to YES, you must use a valid UniAccess userid and password. That is, the userid must be included on the lists maintained by the system administrator in the UniAccess Configuration File. The UniAccess System will then use it to establish an OS 2200 session.

Transaction-Based Security System Requirements

The UniAccess System supports security systems in addition to the Unisys product, TIP session control. To establish communication between the UniAccess System and a transaction-based security system, the system administrator must invoke the UniAccess Security API. This may be done by configuring the COMSRV LOGONTRAN parameter (and optionally the COMSRV LOGOFFTRAN parameter) of the UniAccess Configuration File. When this parameter has been configured, only userids recognized by the security system will be accepted.

Default Language Transaction

The system administrator may specify the language transaction to be used to process client language requests. This is done using the COMSRV DFLTTRAN configuration parameter. Options are the UniAccess Relational Service for RDMS 2200, the UniAccess Hierarchical Service for DMS 2200, or a site-written language transaction. All language requests submitted by Open Client applications and applications using a pre-6R2 UniAccess ODBC Driver are forwarded automatically to the default transaction. For applications using a 6R2 or greater UniAccess ODBC Driver, the default transaction is overridden by the language transaction type specified in the ODBC data source configuration (see page 5-13).



Changing Passwords

ODBC and Open Client users can change their OS 2200 passwords when TIP session control is active by using the following OS 2200 password change syntax in the password field:

oldpas/newpas

where:

oldpas is the current OS 2200 password, and

newpas is the changed OS 2200 password.

Connection Timeout Interactions

The system administrator may specify the amount of time before an inactive connection is terminated. If the COMSRV CONTIMOUT parameter is configured, the UniAccess System terminates the connection after the period specified. If not, inactive connections are not terminated.

Architecture Considerations

The 9-bit-byte architecture of the Unisys OS 2200 mainframe supports different ranges of fixed-point binary (CS-TINYINT/DBTINYINT, CS-SMALLINT/DBSMALLINT, CS-INT/DBINT) and floating-point binary (CS-REAL/DBFLT4, CS-FLOAT/DBFLT8) values than are supported on more typical 8-bit-byte architectures. Fixed-point binary values returned by Server-Library programs must fit within the range supported by 8-bit-byte architectures. Fixed-point binary values specified by a Server-Library program that are outside the range supported by the 8-bit-byte architecture will return an error to the Server-Library program and prohibit the program from passing the value to the client application. Floating-point binary values returned by Server-Library programs that are outside the range supported by the 8-bit-byte architecture will be rounded. Table 4-1 summarizes the pertinent 8-bit-byte architecture and OS 2200 ranges.



Table 4-1: Summary of 8-bit-byte Architecture and OS 2200 Ranges

NoteWhen floating point numbers are converted between 8-bit-byte architectures and OS 2200 architectures, some precision will be lost. This loss of precision may cause problems when an application attempts to compare values. For instance, Microsoft Access attempts to compare the values of all columns within a row it is attempting to update. Floating point values may lead to an erroneous indication that another user has updated the record.

User Datatypes

Open Client and the TDS protocol provides a 4-byte field to return user datatype information. The UARS, UAHS, and UAINFO transactions use this field to return detailed information about OS 2200 datatypes. This information is used by UADriver and is also available to user-written Open Client applications that utilize these UniAccess transactions.

ClientDatatype

8-bit-byteMinimum/Maximum

OS 2200Minimum/Maximum

CS-TINYINT /DBTINYINT /SQL_TINYINT

0 / 255 0 / 511

CS-SMALLINT /DBSMALLINT /SQL_SMALLINT

-32768 / 32767 -131071 / 131071

CS-INT /DBINT /SQL_INTEGER

-2147483648 / 2147483647 -34359738367 / 34359738367

CS-REAL /DBFLT4 /SQL_REAL

machine specific 1.4693679385278600000E-39 /1.7014118219281863170E+38

CS-FLOAT /DBFLT8 /SQL_FLOAT

machine specific 2.7813423231340017320E-309 /8.9884656743115795490E+307



Structure

The following example shows a 4-byte C language data structure in which the UARS, UAHS, and UAINFO transactions return column descriptor information:

typedef struct{

char type;unsigned char nullable:1;unsigned char primarykey:1;unsigned char unused:6;union{struct{

unsigned char precision;unsigned char scale;

} num;unsigned short precision;

} size;} USERDATATYPE;

Field Descriptions

The fields in this user datatype structure are as follows:

• Nullable: indicates whether or not the column is nullable; 1=Y, 0=N.

• PrimaryKey: indicates whether or not the column is a primary key; 1=Y, 0=N.

• Precision: returns the minimum length supported by all dynamic SQL data manipulation statements (SELECT, INSERT, UPDATE, DELETE).

If scale is n/a, precision is a 2-byte length area; otherwise, length is returned as precision in the first byte and as scale in the second byte of the length area.

• Scale: where applicable, scale is the second byte of the length area.



The UARS, UAHS, and UAINFO transactions return information about the datatypes shown in Table 4-2.

Table 4-2: User Datatypes Returned by UARS, UAHS, and UAINFO

ODBC SQL Datatype LengthPrecision1 Scale

SQL_CHAR n n/a

SQL_DATE 10 n/a

SQL_DECIMAL p s

SQL_DOUBLE 18 n/a

SQL_FLOAT p n/a

SQL_INTEGERSQL_DECIMAL2

1012

n/a0

SQL_LONGVARBINARY n n/a

SQL_LONGVARCHAR n n/a

SQL_NUMERIC p s

SQL_REAL 8 n/a

SQL_SMALLINTSQL_DECIMAL2

57

n/a0

SQL_TIME 8 if s = 0;8 + s + 1 if s < > 0

s

SQL_TIMESTAMP 19 if s = 0;19 + s + 1 if s < > 0

s

SQL_UNICODE n n/a

1 When floating point numbers are converted between 8-bit-byte architectures and OS 2200 architectures, some precision will be lost (see page 4-5 for more information).

2 UARS returns columns of type SQL_DECIMAL for INTEGER and SMALLINT datatypes when the system administrator has set the RELSRV INTTOCHAR configuration option to YES.



What’s NextThe UniAccess System services clients operating in a variety of environments and with various host objectives. Users may submit ODBC client or non-ODBC Open Client applications. Client applications may access OS 2200 data by executing a language request or by submitting an RPC. Client applications may access any type of data on the OS 2200, including RDMS 2200 and DMS 2200. And the OS 2200 transactions that process client requests may be supplied by AIS (that is, the UARS and UAHS transactions) or created by the user with UniAccess Server-Library.

The following sections will help you determine which of the subsequent chapters of this manual will be most useful to you. Keep in mind that some of the information in the manual will not apply to your environment.

Pointers for ODBC Users

The essential chapter for ODBC users is Chapter 5, Using the UniAccess ODBC Driver. The chapter describes the UniAccess ODBC Driver, including its supported features and datatypes. It also provides instructions on configuring and connecting to data sources.

The general and ODBC-specific information in the chapters on using UARS and UAHS are important to clients using these language transactions.

Table 4-3: Important Chapters for ODBC Users

OS 2200 Transaction OS 2200 Environment ODBC Client Users

Language Processing

UniAccess Relational Service (UARS)

RDMS 2200 Chapter 5: Using UADriverChapter 6: Using UARSChapter 13: Using UADTC

UniAccess Hierarchical Service (UAHS)

DMS 2200 Chapter 5: Using UADriverChapter 9: Using UAHS

user-written UASL any Chapter 5: Using UADriverChapter 12: Using UATS

RPC Processing

user-written UASL any Chapter 5: Using UADriverChapter 12: Using UATSChapter 13: Using UADTC



Pointers for Open Client Users

The essential chapters for non-ODBC Open Client users are the chapters on using the specific type of OS 2200 transaction that will process client requests in your environment. In addition to general information for all users, these chapters give information specific to Open Client users.

Table 4-4: Important Chapters for Open Client Users

Open Client users should also be aware of the special commands UARSINFO, UAHSINFO, and UAINFO, which may be used to obtain information about the operating environment.

• UARSINFO returns information to Open Clients about the UARS operating environment. It is documented on page 7-26.

• UAHSINFO returns information to Open Clients about the UAHS operating environment. It is documented on page 10-12.

• UAINFO provides connection and version information to Open Client applications operating in a non-UARS, non-UAHS environment. It is documented on page 12-4.

Additional commands for the UARS and UAHS environments are found in Chapter 7 and Chapter 10 respectively.

OS 2200 Transaction OS 2200 Environment Open Client Users

Language Processing

UniAccess Relational Service (UARS)

RDMS 2200 Chapter 6: Using UARSChapter 7: UARS CommandsChapter 8: RDMS Catalog RPCs

UniAccess Hierarchical Service (UAHS)

DMS 2200 Chapter 9: Using UAHSChapter 10: UAHS CommandsChapter 11: UAHS Catalog RPCs

user-written UASL any Chapter 12: Using UATS

RPC Processing

user-written UASL any Chapter 12: Using UATS


5 Using UADriver

5 Using the UniAccess ODBC Driver

This chapter describes the UniAccess ODBC Driver (UADriver) in detail. It provides instructions on configuring and connecting to a data source with UADriver.

Topics Page

The UniAccess ODBC Driver 5-2

ODBC Implementation Level 5-3

Datatypes Supported 5-5

Isolation and Lock Levels Supported 5-9

Number of Connections and Statements Supported 5-10

ODBC Translation Support 5-10

High Speed Connections 5-10

Configuring Data Sources 5-11

Configuring a New or Existing Data Source 5-11

General UADriver Setup Options 5-12

Advanced UADriver Setup Options 5-15

Translation UADriver Setup Options 5-20

UARS Setup Options 5-22

UAHS Setup Options 5-29

Connecting to a Data Source 5-32

Verifying Connectivity 5-32

Using a Login Dialog Box 5-33

Using a Connection String 5-33

5-40



The UniAccess ODBC DriverUADriver provides ODBC access to OS 2200 for Microsoft ODBC-compatible client applications and tools. UADriver allows access to RDMS 2200 through the UARS transaction, to DMS 2200 through the UAHS transaction, and to other OS 2200 databases from user-written UASL-based transactions. The UAINFO transaction is provided to allow UADriver to operate in a non-UARS, non-UAHS environment.

In addition, UADriver provides distributed transaction support through the UniAccess Distributed Transaction Coordinator (UADTC) and the Microsoft Distributed Transaction Coordinator (MS DTC). This service is provided for the UARS transaction and for other UASL-based transactions.

The features and levels of support offered by UADriver depend largely on the host transaction.

The UniAccess ODBC Driver provides the following features:

— All Core, Level 1, and Level 2 functions listed under ODBC Implementation Level on page 5-3

— Forward scrolling

— Multiple connections

— Multiple active statements per connection

— Full procedure support.

The UARS transaction provides these additional services to UADriver users accessing RDMS 2200 data:

— Minimum and core SQL support

— Serializable (default) and read-committed isolation levels

— Row-level (default) and page-level locking.

The UAHS transaction provides a subset of those parts of the Minimum SQL Grammar that are appropriate for a read-only data source.


Using the UniAccess ODBC Driver 5-3

ODBC Implementation Level

Table 5-1 lists the ODBC functions that the UniAccess ODBC Driver supports.

Table 5-1: Supported ODBC Functions

Function Level Transaction Processing Environment

UARS UAHS No Language Service

SQLAllocConnect core yes yes yes

SQLAllocEnv core yes yes yes

SQLAllocStmt core yes yes yes

SQLBindCol core yes yes yes

SQLBindParameter level 2 yes yes yes

SQLBrowseConnect level 2 yes yes yes

SQLCancel core yes yes yes

SQLColAttributes core yes yes yes

SQLColumnPrivileges level 2 yes no no

SQLColumns level 1 yes yes no

SQLConnect core yes yes yes

SQLDataSources* level 2 no no no

SQLDescribeCol core yes yes yes

SQLDescribeParam level 2 no no no

SQLDisconnect core yes yes yes

SQLDriverConnect level 1 yes yes yes

SQLDrivers* level 2 no no no

* Functions implemented by the ODBC Driver Manager.



SQLError core yes yes yes

SQLExecDirect core yes yes yes

SQLExecute core yes yes yes

SQLExtendedFetch level 2 yes yes yes

SQLFetch core yes yes yes

SQLForeignKeys level 2 yes no no

SQLFreeConnect core yes yes yes

SQLFreeEnv core yes yes yes

SQLFreeStmt core yes yes yes

SQLGetConnectOption level 1 yes yes yes

SQLGetCursorName core yes yes yes

SQLGetData level 1 yes yes yes

SQLGetFunctions level 1 yes yes yes

SQLGetInfo level 1 yes yes yes

SQLGetStmtOption level 1 yes yes yes

SQLGetTypeInfo level 1 yes yes no

SQLMoreResults level 2 yes yes yes

SQLNativeSql level 2 yes yes yes

SQLNumParams level 2 yes yes yes

SQLNumResultCols core yes yes yes

SQLParamData level 1 yes yes yes

SQLParamOptions level 2 yes yes yes

SQLPrepare core yes yes yes






Datatypes Supported

This section indicates ODBC datatype correspondences with RDMS datatypes, DMS datatypes, and Server-Library input and output datatypes.

SQLPrimaryKeys level 2 yes no no

SQLProcedureColumns level 2 yes no no

SQLProcedures level 2 yes no no

SQLPutData level 1 yes yes yes

SQLRowCount core yes yes yes

SQLSetConnectOption level 1 yes yes yes

SQLSetCursorName core yes yes yes

SQLSetParam core yes yes yes

SQLSetPos level 2 no no no

SQLSetScrollOptions level 2 yes yes yes

SQLSetStmtOption level 1 yes yes yes

SQLSpecialColumns level 1 yes yes no

SQLStatistics level 1 yes yes no

SQLTablePrivileges level 2 yes no no

SQLTables level 1 yes yes no

SQLTransact core yes yes yes






RDMS Datatype Correspondences

RDMS 2200 datatypes are mapped to standard ODBC datatypes according to the following list. (For precision, length, and scale of supported RDMS 2200 datatypes, see Table 6-4.)

Table 5-2: RDMS 2200 and ODBC Datatype Correspondences RDMS 2200 Datatype ODBC SQL Datatype

BLOB SQL_LONGVARBINARY

CHARACTER SQL_CHAR or SQL_LONGVARYCHAR1

DATE SQL_DATE

DECIMAL SQL_DECIMAL

DOUBLE PRECISION SQL_FLOAT2

FLOAT SQL_FLOAT2

INTEGER SQL_INTEGER or SQL_DECIMAL3

NCHARACTER SQL_CHAR, SQL_LONGVARYCHAR1, or SQL_UNICODE4 (either truncated or not)

NUMERIC SQL_NUMERIC

REAL SQL_REAL2

SMALLINT3 SQL_SMALLINT or SQL_DECIMAL

TIME SQL_TIME

TIMESTAMP SQL_TIMESTAMP

1 If Support SQL_LONGVARYCHAR is allowed, CHARACTER and NCHARACTER columns will be returned as SQL_LONGVARCHAR columns. This conversion will occur when CHARACTER columns have a precision greater than 255. It will also occur when NCHARACTER columns have a precision greater than 127 and Support SQL_UNICODE is turned off.


3 If Convert integers to characters is allowed, UARS will convert INTEGER and SMALLINT columns to character strings (SQL_DECIMAL). Otherwise, INTEGER and SMALLINT columns will be returned as fixed-point binary values (SQL_INTEGER and SQL_SMALLINT).

4 If Support SQL_UNICODE is allowed, NCHARACTER columns are returned as SQL_UNICODE.



DMS Datatypes Correspondences

DMS 2200 datatypes are mapped to the standard ODBC datatypes as described in the table below. (For precision, length, and scale of supported DMS 2200, see Table 9-3.)

Table 5-3: DMS 2200 and ODBC Datatype Correspondences

DMS 2200 Datatype

DDL Item Description ODBC SQL Datatype

PICTURE USAGE

AlphabeticAlphanumeric

A(y)X(y)

DISPLAY SQL_CHAR

Numeric 9(n)9(n)V9(m)S9(n)S9(n)V9(m)

DISPLAYCOMP

SQL_DECIMAL

Single-Precision Floating-Point

n/a COMP-1 SQL_REAL*

Double-Precision Floating-Point

n/a COMP-2 SQL_DOUBLE*

DMS Key n/a DATABASE- KEY,AREA-KEY

SQL_DECIMAL

DMS Date/Time n/a DATE,TIME,DATE-TIME

SQL_DECIMAL

Where: A = Only alphabetic (no numeric or special) characters and spaces are allowed in the field.

X = Any characters are allowed in the field. 9 = Only numeric characters are allowed in the field. y = The character length of the field. n = The number of digits to the left of the decimal. m = The number of digits to the right of the decimal. V = An assumed decimal position. S = The field is signed, that is, negative values are allowed.

* When floating point numbers are converted between OS 2200 architectures and 8-bit-byte architectures, some precision will be lost (see page 4-5 for more information).



Client/Server-Library Datatype Correspondences

For user-written transactions, Table 5-4 shows how the ODBC SQL datatypes specified for ODBC procedure parameters are sent to a UniAccess Server-Library transaction. The first column is the ODBC SQL datatype specified by the application for the procedure parameter. The second column is the Client-Library datatype the UniAccess ODBC Driver sends to the UASL transaction. The third column is the UASL datatype received by the UASL transaction.

Table 5-4: ODBC to UASL Datatype Correspondence

ODBC SQL Datatype Client-Library Datatype UASL Datatype

SQL_CHAR CS_CHAR TDSVARYCHAR

SQL_VARCHAR CS_CHAR TDSVARYCHAR

SQL_LONGVARCHAR N/A Driver does not support

SQL_DECIMAL CS_CHAR TDSVARYCHAR

SQL_NUMERIC CS_CHAR TDSVARYCHAR

SQL_SMALLINT CS_SMALLINT TDSINT2

SQL_INTEGER CS_INT TDSINT4

SQL_REAL CS_REAL TDSREAL

SQL_FLOAT* CS_FLOAT TDSFLT8

SQL_DOUBLE* CS_FLOAT TDSFLT8

SQL_BIT CS_BIT TDSBIT

SQL_TINYINT CS_TINYINT TDSINT1

SQL_BIGINT N/A Driver does not support

SQL_BINARY CS_BINARY TDSVARYBINARY

SQL_VARBINARY CS_BINARY TDSVARYBINARY

SQL_LONVARBINARY N/A Driver does not support

SQL_DATE CS_DATETIME TDSDATETIME

SQL_TIME CS_DATETIME TDSDATETIME

SQL_TIMESTAMP CS_DATETIME TDSDATETIME

* When floating point numbers are converted between 8-bit-byte architectures and OS 2200 architectures, some precision will be lost (see page 4-4 for more information).



Table 5-5 indicates how TDS datatypes returned by a UniAccess Server-Library transaction are presented to an ODBC application. The first column is the UASL datatype specified by the UASL transaction. The second column is the Client-Library datatype received by the UniAccess ODBC Driver. The third column is the ODBC SQL datatype reported to the ODBC application.

Table 5-5: UASL to ODBC SQL Datatype Correspondence

Isolation and Lock Levels Supported

RDMS 2200 supports isolation level 1 and 3. The default is 3. RDMS 2200 supports record and page-level locking. The default is record-level locking.

UASL Datatype Client-Library Datatype ODBC SQL Datatype

TDSCHAR CS_CHAR SQL_CHAR

TDSVARYCHAR CS_VARCHAR SQL_VARCHAR

TDSBINARY CS_BINARY SQL_BINARY

TDSVARYBINARY CS_VARBINARY SQL_VARBINARY

TDSINT1 CS_TINYINT SQL_TINYINT

TDSINT2 CS_SMALLINT SQL_SMALLINT

TDSINT4 CS_INT SQL_INTEGER

TDSBIT CS_BIT SQL_BIT

TDSDATETIME CS_DATETIME SQL_TIMESTAMP

TDSMONEY CS_MONEY SQL_DECIMAL

TDSFLT8* CS_FLOAT SQL_FLOAT

TDSFLT4*, TDSREAL* CS_REAL SQL_REAL

TDSDATETIME4 CS_DATETIME4 SQL_TIMESTAMP

TDSMONEY4 CS_MONEY4 SQL_DECIMAL




Number of Connections and Statements Supported

The UniAccess ODBC Driver supports multiple connections and multiple statements within a connection. By default, UADriver allows only a single active statement (with results pending) within a connection at any one time. If a particular UniAccess ODBC data source requires multiple active statements within a connection, that data source can be configured using the ODBC Data Source Administrator program. From the UniAccess Advanced Settings dialog box, enable Allow Multiple Active Statements/Connection. The Maximum Statements/Connection and Maximum Idle Connections settings may be configured as desired. (See page 5-18 for information on allowing multiple active statements/connections.)

ODBC Translation Support

The UniAccess ODBC Driver supports ODBC translation DLLs. For clients using the UARS transaction to access RDMS 2200, UADriver passes two-byte character (NCHARACTER) data as SQL_UNICODE to the translation DLL, in addition to the standard ODBC SDK-defined datatype translations. If a translation DLL does not support the SQL_UNICODE datatype, the Support SQL UNICODE setup option can also be used to prevent SQL_UNICODE from being returned to the translation DLL and the ODBC application. Additionally, the RELSRV/UAUSER DOUNICODE configuration parameter can be used to prevent SQL_UNICODE columns from being returned to UADriver (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide).

If you plan to create your own customized translation DLL, please refer to the section Customized Translation DLL Installation on page 3-9 for information on how to use the UADriver setup routines to install your translation DLL. Also see the Microsoft ODBC SDK for further details on creating translation DLLs.

High Speed Connections

The high speed connection option supported by UADriver can improve connection speed in some environments. The conventional connection process involves one or two round trips to the host to retrieve information about the OS 2200 UniAccess Configuration File and to determine which Configuration File settings can be overridden by clients. In environments such as web-based applications, the cost of repeated connections to the host can be expensive, both in time and in resource usage. The High Speed Connection Option, available on the Advanced tab of the UADriver Setup dialog (see page 5-19), removes these



extra round trips by retrieving the current host settings in advance and storing them in the Windows registry. UADriver then retrieves these values from the registry when establishing connections, and the extra round trips to the host are avoided. This option eliminates the client’s ability to override default settings on the OS 2200. Experiments have shown as much as an 80% improvement in connection speed using this option.

NoteWhenever changes are made to the OS 2200 UniAccess Configuration File, the changes must also be made in the Windows registry by selecting the Get Current Settings button on the Advance tab of the UADriver Setup dialog.

Configuring Data SourcesAfter you have installed UADriver, you will use the UADriver Setup dialog to configure it to use the ODBC Administrator data sources you require. The information you need to accomplish this task is presented in the following sections.

Configuring a New or Existing Data Source

You configure a new data source when you select ODBC Data Sources from the UniAccess 10R3 PC Client Program Group or from the Control Panel. If you are configuring a new data source, click Add. A list of installed drivers appears. Select UniAccess, and click Finish. If you are configuring an existing data source, select a UniAccess data source and click Configure... . The UADriver Setup dialog box, illustrated in Figure 5-1, appears.

Using the UADriver Setup Dialog box

The initial UADriver Setup dialog presents several configurable fields required for all data sources. In addition, the user can select from among several tabs for other configuration options. The sections that follow describe the fields presented on the General, Advanced, Translation, UARS, and UAHS options of the UADriver Setup. For information on the Test and Trace features, see Appendix D.



Saving a Data Source Configuration

After you have configured all desired fields in the UADriver Setup dialogs, click OK to exit the main dialog. Assuming no conflicts with host configuration settings, the values you configured are now the defaults whenever you connect to the data source. (To determine whether or not the UniAccess host Configuration File has disallowed any options you selected during the data source configuration, use the Host Connectivity Test described on page D-2). The default values for the configured data source are stored in the registry.

You can see the list of data sources you have configured by using the ODBC Data Source Administrator (accessed through the Windows Control Panel). Use the ODBC Data Source Administrator to reconfigure your data source.

General UADriver Setup Options

The options displayed in the General dialog of the UADriver Setup are illustrated in Figure 5-1 and described below. Please note that all fields are required except the Description field.

General Information

Data Source NameIdentifies a single connection to a UniAccess Communication Server. This can be any string. Examples include “Accounting” or “UniAccess_Server”. The maximum length is 30 characters. This field is required.

DescriptionA long description of a data source name. For example, “My Accounting Database” or “UACS on Host #1”. The maximum length is 255 characters. This field is optional.



Figure 5-1: UADriver Setup Dialog Box

Host Features

Services and Language TransactionDefines the set of services and the default language transaction being used with this data source.

The Services specify the type of requests that may be used with this data source. Select UniAccess Relational Service (UARS) if language requests, catalog RPCs, or RDMS stored procedure calls will be issued to



RDMS 2200 using the UARS transaction. Select UniAccess Hierarchical Service (UAHS) if language requests or catalog RPCs will be issued to DMS 2200 using the UAHS transaction. Select UniAccess Server-Library if any user-written RPCs will be issued. More than one service may be selected.

The choice of a default Language Transaction is dependent upon the Service selected. If the UARS service is specified, the UARS transaction will be selected automatically. If the UAHS service is specified, the UAHS transaction will be selected automatically. If the UniAccess Server-Library is specified, the user may designate either a user-written transaction or no language transaction as the default. If more than one Service is specified, a single default language transaction should be selected.

NoteFor environments where a user-written transaction or no language transaction is being used, the system administrator must have installed the UAINFO transaction and have configured the COMSRV UAINTRAN UniAccess configuration parameter for UADriver to function. (For information on the use of this command, see Chapter 12 of this manual. For information on installing and configuring UAINFO, see Chapter 4 and Chapter 16 respectively in the UniAccess for OS 2200 System Administration Guide.)

Connection Information

IP Address/Host NameDefines the IP address or the Internet host name of the UniAccess Communication Server. If an IP address is specified, it must be in the format of nnn.nnn.nnn.nnn where nnn ranges from 0 to 255. If the Internet host name is specified, the name must be resolvable to an IP address. This field is required.

PortDefines the port of the UniAccess Communication Server. The valid range is from 1 to 65535. This field is required.



Advanced UADriver Setup Options

The options displayed in the Advanced dialog of the UADriver Setup are illustrated in Figure 5-2 and described below.

Figure 5-2: Advanced UADriver Setup Dialog



General Information

Default Login IdThis option specifies the default Login ID used to connect to your UniAccess Communication Server. Your ODBC application may override this value or you may override this value in the Login dialog box. If security has not been enabled on your OS 2200 host nor your UniAccess Communication Server, you will not require a Login ID. If it has been enabled, contact your system administrator to get your Login ID for your host. The maximum length is 30 characters.

Logon TimeoutThis option defines the maximum amount of time in seconds UADriver will wait for a login acknowledgment. The default value is 60. A value of -9999 indicates no timeout limit. The maximum value is 2147483.

Max ConnectionsThis option defines the maximum number of connections that can be established from a single instance of UADriver. The default value is the SYBASE Open Client default, which is typically 25. A value of 0 indicates that the SYBASE Open Client default should be used. The valid range is from 1 to 10000.

WorkAroundsThis option defines application-specific workarounds. The values for this option are cumulative. That is, if you want WorkArounds settings 1, 2, and 8, you should set WorkArounds to a value of 11. The following WorkArounds settings are valid:

1 When some applications make ODBC catalog function calls such as SQLTables, they escape ('\') the underscore character ('_'). When this workaround is selected, UADriver removes the escape character before sending the catalog request to the OS 2200 host.

2 Some applications generate table names with the form "A.B".C , where A is the qualifier and B is the owner of the table. By default, UADriver will treat the "A.B" as an owner name and remove it before sending the request to the OS 2200 host. With this workaround selected, UADriver



will treat the A as a qualifier and the B as an owner name. Then the table name will be submitted to the OS 2200 host as A.C.

8 Some applications generate table names with the form A.B, where A is the qualifier of the table and B is the name of the table. By default, UADriver will treat the A as an owner name and remove it before sending the request to the OS 2200 host. With this workaround selected, UADriver will treat the A as a qualifier. Then the table name will be submitted to the OS 2200 host as A.B.

16 Some applications require that fixed-length character columns be blank-padded to their maximum lengths. This option causes all result set columns that are retrieved via SQLFetch or SQLExtendedFetch to be blank-padded to their maximum lengths.

32 Some applications require the data source to support the owner field in DML commands. This option causes UADriver to return a value of SQL_OU_DML_STATEMENTS when SQLGetInfor is called with the SQL_OWNER_USAGE parameter. Normally, UADriver returns zero, which indicates that the owner field is not valid in any command.

NoteThe workarounds cannot be specified as part of a connection string.

Packet SizeThis value specifies the packet size in bytes that will be used by UADriver and UACS. Larger packet sizes may improve performance when large result sets are being processed. Valid packet sizes are 512, 1024, 2048, and 4096. Defaults to 512.

NoteIf the packet size value exceeds the value configured in the OS 2200 UniAccess Configuration File, the packet size is dynamically adjusted downwards to match the UAMM BLOCKSIZE setting.



Distributed Transaction Options

Support Distributed TransactionsThis optional value indicates whether or not UADriver will support distributed transactions by allowing connections to be enlisted in a Microsoft Distributed Transaction Coordinator (MS DTC) transaction. This option will be deactivated if the Allow Multiple Active Statements/Connection option under the Advanced Setup Options is selected. The default distributed transaction setting and the ability to override this option are determined by the OS 2200 UniAccess Configuration File UAUSER DISTTRAN setting.

NoteThe Support Distributed Transaction option is only available under Windows 2000 and greater.

UADTC LocationThis optional value is configurable when the Support Distributed Transactions option is selected or allowed to default to the Host Value. It defines the name of the machine on which the UADTC service is running. This option is only required if you are using the UniAccess distributed transaction features. If this value is left blank, UADriver will assume the UADTC service is running locally.

Statement Options

Allow Multiple Active Statements/ConnectionThis option indicates whether or not UADriver will support multiple active statements per connection. By default, UADriver supports one active statement per connection. When this option is selected, UADriver will support multiple active statements per connection by establishing a physical TCP/IP connection with the host for every statement that is allocated. This option will be deactivated if the Support Distributed Transaction option (under Advanced Setup Options) or the Support Manual Commit option (under UARS Setup Options) is selected.



Maximum Statements/ConnectionThis option is configurable when the Allow Multiple Active Statements/Connection option is selected. It indicates the maximum number of active statements UADriver will support per connection. The number of TCP/IP sockets available on the ODBC client workstation will limit this number. The valid configuration range is from 1 to 99. The default value is 1.

Maximum Idle ConnectionsThis option is configurable when the Allow Multiple Active Statements/Connection option is selected. It indicates the maximum number of idle connections to maintain as statements are freed. Maintaining idle connections allows UADriver to reuse a previously established physical connection when new statements are allocated. However, each idle connection consumes a connection on the host. The valid configuration range is from 1 to the specified Maximum Statements/Connection value. The default value is 1.

High Speed Connection Option

Activate High Speed Connection OptionThis optional value indicates whether or not UADriver will support high-speed connections. Normally, connections require one or two round trips to the OS 2200 to reconcile host settings with workstation settings. If the high-speed option is selected, the current values for these settings are retrieved from information placed in the registry by the Get Current Settings option, thus removing the need for the round trip(s) at connection time (see page 5-10). When this option is selected, the action triggered by the Get Current Settings option is automatically invoked. Selecting this option eliminates the client’s ability to override default settings on the OS 2200.

NoteChanges to the UniAccess Configuration File are not retrieved automatically. To maintain consistency, the Get Current Settings button (see below) should be used anytime changes are made to the UniAccess Configuration File.



NoteSettings retrieved for this option do not replace the locally configured values, which are also saved in the registry. If the High Speed Connection Option is de-selected, settings will automatically revert to their locally configured values.

Get Current SettingsThis option is active only when the High Speed Connection Option is selected. Selecting it will cause Setup to query the OS 2200 Configuration File for values related to UADriver Setup and store them in the registry. A connection to the OS 2200 is required for this action, so a separate dialog is used to request the userid and password for the connection.

NoteIf UniAccess Configuration File settings are changed after the high speed option is selected, the Configuration File and the registry could be out of synchronization. It is imperative that synchronization be maintained by selecting this option anytime Configuration File settings are changed.

Translation UADriver Setup Options

The options displayed in the Translation dialog of the UADriver Setup are illustrated in Figure 5-3 and described below.

Host Translation Settings

Activate TranslationThis optional value activates the language service translation routine on the server. Translation is dependent upon a site-written translation routine. If no translation routine is provided, this option will not provide any translation. (See Chapter 12 in the UniAccess for OS 2200 System Administration Guide for information on creating and using the translation routines). The default setting for the user and the ability to override this value are determined by the OS 2200 UniAccess Configuration File



HIERSRV/UAUSER TRANSACTIVEH or RELSRV/UAUSER TRANSACTIVE setting.

Figure 5-3: Translation Options Dialog



Translation OptionThis value is passed to the site-written translation routine when the Activate Translation option is selected, or when the UniAccess Configuration File is set for a site-written translation routine. If the UADriver Language Transaction Type is UARS, this value also indicates which Kanji character set is to be used by RDMS. The options are None, LETS-J, or Shift-JIS, where None indicates that no value will be passed. The default value for the user and the ability to override this value are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER TRANSOPTIONH or RELSRV/UAUSER TRANSOPTION setting.

ODBC Translator

To activate ODBC Translation, select the Translation... button at the bottom of the Advanced dialog. The ODBC translation DLL Configuration dialog box appears. Select a translation DLL from among the list of installed DLLs. (See page 5-10 for a discussion of ODBC translation support).

The selection of the translation DLL will automatically enter values for the Translation DLL Name (TRANSNAME), Translation DLL Path (TRANSDLL), and Translation DLL Option (TRANSOPT) into the registry .

The TRANSNAME, TRANSDLL, and TRANSOPT parameters may be passed as connection options in a UADriver connection string.

UARS Setup Options

The options displayed in the UARS dialog of the UADriver Setup are illustrated in Figure 5-4 and described below. (For references to settings in the UniAccess Configuration File, see Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

General Information

DatabaseThis option defines a default RDMS 2200 qualifier. The driver automatically makes this the default qualifier when the user connects to a UniAccess data source. The default qualifier for the user and the ability to



override this value are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER SCHEMA setting. This field is case sensitive. The maximum length is 30 characters.

Figure 5-4: UARS Setup Options Dialog Box



VersionThis option defines a default RDMS 2200 version. The driver automatically makes this the default version when the user connects to a UniAccess data source. The default version for the user and the ability to override this value are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER VERSION setting. The maximum length is 30 characters.

Storage AreaThis option defines an RDMS 2200 storage area into which newly created tables are placed. The storage area must be created by an RDMS 2200 administrator before tables can be created. If this field is left blank, RDMS 2200 implicitly will create a storage area for a newly created table. The maximum length of this field is 30 characters.

NoteAn implicitly created storage area will not be deleted by a DROP TABLE command and must be deleted manually by an RDMS 2200 administrator before a table with the same name can be created.

Row LimitThis option limits the number of rows that will be returned by a SELECT command. The default number of rows to return and the ability to override this value are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER ROWLIMIT setting. The ability to use this option can be disallowed by UniAccess Configuration File setting. The valid range is from 0 to 2147483647 where 0 indicates that all rows should be returned.

Thread AccessThis option defines the type of RDMS thread access to use when establishing a thread. Options are READ, UPDATE, and ACCESS. When READ is specified, the Thread Recovery value is ignored. The default thread access for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER ACCESS setting.



Thread RecoveryThis option defines the type of RDMS thread recovery to use when establishing a thread. Options are NONE, COMMANDLOOKS, QUICKLOOKS, and DEFERRED. When Thread Access is READ, Thread Recovery is ignored. The default thread recovery for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER RECOVERY setting.

RSA WorksizeThis option defines the size of the RSA worksize to use when performing RDMS commands. The default RSA worksize for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER WORKSIZE setting. The valid range is from 2000 to 100000.

UARS BlobsizeThis option defines the size of the maximum precision of a BLOB column that UARS returns to a single SELECT request. The default UARS blobsize for the user and the ability to override this value are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER MAXBLOBSIZE setting. The valid range is from 0 to 2147483647.

Operational Values

In the fields provided under Operational Values, specify the values as described below by selecting items from the scroll-down menu and then using the radial buttons beneath it to set the option to On, Off, or Default to Host Value (where applicable). Multiple items may be configured. (For references to settings in the UniAccess Configuration File, see Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Activate RDMS access control when creating tablesThis option indicates whether or not UADriver will generate an ALTER TABLE command automatically to define ownership and access control for tables defined with the CREATE TABLE command. This option should only be used when tables are being created in unowned schemas.



Convert integers to charactersThis option causes RDMS SMALLINT and INT columns to be converted to character columns. YES indicates that UARS will convert SMALLINT columns (precision = 7, scale = 0) and INT columns (precision = 12, scale = 0) to zero-filled SQL_DECIMAL columns. NO indicates that SMALLINT columns are returned as fixed-point 16-bit binary values and that INT columns are returned as fixed-point 32-bit binary values.

This option can be used to workaround overflow errors that can occur when converting 18-bit SMALLINT and 36-bit INT values to 16-bit SQL_SMALLINT and 32-bit SQL_INTEGER values. The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER INTTOCHAR setting.

Convert VARCHAR to CHARThis option indicates whether or not UADriver will convert VARCHAR references to CHAR automatically before sending the SQL request to the host. This option is provided to help ODBC applications that ignore the datatype information returned in the SQLGetTypeInfo result set.

Order procedure columns This option modifies the result set order for SQLProcedureColumns to return procedure parameter columns in the order the procedure expects them. By default the result set is ordered as defined by the ODBC SDK. Enabling this option will cause UADriver to return a result set that does not adhere to the ODBC SDK specification. This option works in conjunction with the PARAM_SEQ_NUM column of the UNIACCESS1S1.SPT_PROCEDURE_COLUMNS table.

Prefix DROP TABLE commands with DELETE TABLEThis option indicates whether or not UADriver will prefix a DELETE TABLE command before a DROP TABLE command prior to sending the SQL request to the host. This option is provided to help ODBC applications that assume a DROP TABLE command will delete all records in the table automatically before dropping the table. RDMS 2200 will return an error if an attempt is made to drop a table before deleting all the records in the table.



Quote all identifiersThis option indicates whether or not UADriver will place quotes around identifiers automatically before sending the SQL request to the host. This option is provided to help ODBC applications that ignore UADriver's identifier quoting requirements. (For information on identifier quoting requirements, see page 6-13.)

Remove control characters from literal stringsThis option causes control characters (ASCII value less than 32) to be removed from literal strings before they are submitted to RDMS for processing. If YES is specified, UARS will convert all control characters to spaces regardless of whether or not those control characters are part of a character literal. If NO is specified, UARS will only convert control characters that are not part of a character literal to spaces. The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER STRIPCTRL setting.

Remove trailing spaces from character columnsThis option causes character columns to be returned as variable length fields with trailing spaces trimmed. The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER SPACETRIM setting.

Support manual commit This option indicates whether or not to support manual commit mode (BEGIN TRAN) allowing user-defined transactions. This option will be deactivated if the “Allow Multiple Active Statements/Connections” option under the Advanced Setup Options is selected. When this option is configured, no user-written UniAccess Server-Library transaction may be initiated. The default mode for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER USERTRAN setting.

NoteOS 2200 resources are utilized most efficiently when UADriver is in auto-commit mode rather than manual commit mode.



Support SQL_LONGVARCHARThis option indicates whether or not CHARACTER and NCHARACTER columns will be returned as SQL_LONGVARCHAR columns. This conversion will occur when CHARACTER columns have a precision greater than 255. It will also occur when NCHARACTER columns have a precision greater than 127 and SQL_UNICODE processing is turned off. The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER LONGCHAR setting.

NoteWhen this option is not selected, the UniAccess Configuration File COMSRV CHARTRUN setting determines whether CHARACTER and NCHARACTER columns are truncated or an error is generated.

Support SQL Server ReplicationThis option indicates whether or not Microsoft SQL Server replication is supported for this DSN. If YES is selected, support is provided for both snapshot and transactional replication. (See the Microsoft SQL Server 7.0 Enterprise Manager documentation for a discussion of replication.)

NoteReplication also requires that the Support manual commit option be specified as YES.

Support SQL_UNICODEThis option indicates whether or not RDMS NCHARACTER columns are returned as SQL_UNICODE types. (If NO is specified, NCHARACTER columns are treated as SQL_CHAR datatypes.) The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File RELSRV/UAUSER DOUNICODE setting.



UAHS Setup Options

The options displayed in the UAHS Setup dialog of the UADriver Setup are illustrated in Figure 5-5 and described below. (For references to settings in the UniAccess Configuration File, see Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Figure 5-5: UAHS Setup Options Dialog Box



General Information

DatabaseThis option defines a default UAHS database. The driver makes this the default database automatically when the user connects to a UniAccess data source. The default UAHS database for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER SCHEMAH setting. The maximum length is 30 characters.

Row LimitThis option limits the number of rows that will be returned by a SELECT command. The default number of rows to return and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER ROWLIMITH setting. The maximum length is 30 characters. The valid range is from 0 to 2147483647 where 0 indicates that all rows should be returned.

Operational Values

In the fields provided under Operational Values, specify the values as described below by selecting items from the scroll-down menu and then using the radial buttons beneath it to set the option to On, Off, or Default to Host Value (where applicable). Multiple items may be configured. (For references to settings in the UniAccess Configuration File, see Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Activate host debugging This option indicates that the UAHS transaction should generate debug information in its print file. It should only be used to assist in debugging SELECT command problems. The default debug setting for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER DEBUG setting. The maximum length is 30 characters.

NoteDebug tracing increases system overhead.



Perform area search This option indicates whether or not UAHS should perform searches when key data is not provided. These searches may read the entire DMS database and, as a result, host performance may suffer. The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER AREASEARCH setting.

NoteSelecting this option may have a severe performance impact on the host environment.

Remove control characters from literal stringsThis option causes control characters (ASCII value less than 32) to be removed from literal strings before they are processed. If YES is specified, UAHS will convert all control characters to spaces regardless of whether or not those control characters are part of a character literal. If NO is specified, UAHS will only convert control characters that are not part of a character literal to spaces. The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER STRIPCTRLH setting.

Remove trailing spaces from character columnsThis option causes character columns to be returned as variable length fields with trailing spaces trimmed. The default value for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER SPACETRIMH setting.



Connecting to a Data SourceAfter you have configured your data sources, you will need to learn how to connect to them. The information you need to accomplish this task is presented in the following section. Several connection options are available.

Verifying Connectivity

UADriver provides two tests to verify connectivity and troubleshoot connectivity problems, as explained in the sections that follow.

Host Connectivity Test

If you are experiencing problems connecting to the OS 2200 host from your ODBC application, you can use the Host Connectivity Test option under the Test tab of the UADriver setup dialog to help diagnose the problem. The Host Connectivity Test will perform a series of tests and provide an analysis of the results of those tests. The test analysis will assist you in solving your connectivity problems.

The Host Connectivity test is described in Appendix D.

Transaction Coordinator Connectivity Test

If you are experiencing problems connecting to the UniAccess Distributed Transaction Coordinator (UADTC) from your ODBC application, you can use the Transaction Coordinator Connectivity Test option under the Test tab of the UADriver setup dialog to help diagnose your problems. The Transaction Coordinator Connectivity Test will attempt to connect to UADTC and will provide an analysis of the results. The test analysis will assist you in solving your connectivity problems.

For information on the Transaction Coordinator Connectivity Test Results, see Appendix D.

NoteBefore performing this test, the Support Distributed Transaction option must be configured in the UADriver Setup / Advanced Setup dialog. In addition, if UADTC is running remotely, the location of UADTC must be configured in the same UADriver Setup dialog.



Using a Login Dialog Box

Some ODBC applications display a Login dialog box when you are connecting to a data source. Enter values in the required fields as described below.

Login IDYour Login ID (case-sensitive). If UniAccess security is active, this must be a valid UniAccess userid. If OS 2200 TIP session control is active, this must be a valid OS 2200 userid.

PasswordYour password for the system (case-sensitive). If OS 2200 TIP session control is active, this must be a valid OS 2200 password. If the UniAccess Security API is in use, this password must be a valid password for the local security system.

Click OK to logon to UACS. If the connection is successful, the Login ID is updated in the registry.

Using a Connection String

If your application requires a connection string to connect to a data source, specify the data source name to use the default connection information. Optionally, you may specify attribute/value pairs in the connection string to override the default values.

You can specify either long or short names in the connection string. The connection string has the form:

"DSN=data source name[;attribute=value;[attribute=value;]...]"

An example of a UniAccess connection string is:

"DSN=UACSSERVER;UID=JOHN;PWD=XYZZY"

Attributes

Table 5-6 lists the attributes used by the UADriver. These attributes may be used when you are connecting to a data source using a connection string. The short names for attribute values are listed in parentheses next to the long names. For a more complete description of these attributes, see their comparable configuration options in the Configuring Data Sources section.



Table 5-6: UniAccess ODBC Driver Attributes

Configuration / Long and Short Category / Attribute Names Meaning

General

DSN (DSN) A string that identifies a single connection to a UACS.

Host (HOST) Defines the IP address or the Internet host name of the UACS.

If the IP address is specified, it must be in the format of nnn.nnn.nnn.nnn where nnn ranges from 0 to 255.

If the Internet host name is specified, the name must be resolvable to an IP address.

LanguageType (LANGTYPE) The set of services and the default transaction being used with this data source. Table 3-3 lists all possible LANGTYPE values for all combinations of services and transactions.

Port (PORT) Defines the port of the UACS. The valid range is from 1 to 65535.

Other

Driver (DRIVER) Name of the UniAccess ODBC Driver. The name of this driver is UniAccess.

Password (PWD) Case-sensitive password; there is no default.

Advanced

DistributedTran (DISTTRAN) Indicates whether or not UADriver will support distributed transactions. This option is ignored if the MultActiveStmts option is enabled.

YES indicates that distributed transactions are allowed.NO indicates that distributed transactions are not allowed.

LoginID (UID) Case-sensitive Login ID.

LoginTimeout (LOGTIM) The maximum amount of time in seconds to wait for a login acknowledgment The maximum value is 2147483. A value of -9999 indicates a no timeout limit. Defaults to 60.

MaxConnections (MAXCONN) The maximum number of connections that can be established from a single instance of UADriver. Range from 0 to 10000. Defaults to the SYBASE Open Client default, (typically 25). 0 indicates the SYBASE Open Client default will be used.



MaxIdleConns (MAXIDLE) The maximum number of idle connections to maintain as statements are freed. This attribute is ignored if MultActiveStmts is disabled. Range from 1 to the value specified in MaxStmts. Defaults to 1.

MaxStmts (MAXSTMT) The maximum number of active statements UADriver will support per connection. This attribute is ignored if MultActiveStmts is disabled. Range from 1 to 99. Defaults to 1.

MultActiveStmts (MULTSTMT) Indicates whether or not the MultActiveStmts option is enabled.

YES indicates that the option should be enabled. NO indicates that the option should be disabled.

PacketSize (PACKETSIZE) Specifies the packet size in bytes that will be used by UADriver and UACS. Valid packet sizes are 512, 1024, 2048, and 2096. Defaults to 512.

UADTC (UADTC) Defines the name of the machine on which the UADTC service is running. This optional value is configurable when the Support Distributed Transactions option is selected.

Translation

HostTransactive (TRANSACTIVE) Indicates whether or not a user-supplied translation routine will be called.

YES indicates that the translation routine will be called, in which case the TRANSOPTION value is also passed to the translation routine.

NO indicates that the translation routine should not be called.

HostTransoption (TRANSOPTION) This value is used both as a parameter to the user-supplied translation routine if Host Transactive is YES; and, for UARS, to indicate what type of translation RDMS should provide internally.

NONE indicates that the value ua_no_xlate should be passed to the translation routine

LETSJ indicates that the value ua_letsj should be passed, and for UARS, that the LETS-J Kanji character set will be used.

SJIS indicates that the value ua_sjis should be passed, and for UARS, that the Shift-JIS Kanji character set will be used.




TranslationDll (TRANSDLL) Specifies the full path of the translation DLL. This value is required for ODBC translation support.

TranslationName (TRANSNAME) Descriptive name of the translation DLL.

TranslationOption (TRANSOPT) Specifies a translation DLL option. Range from 0 to 4294967295. Defaults to 0.

UARS

AccessControl (ACCESS) Indicates whether or not UADriver should generate an ALTER TABLE command (to activate RDMS 2200 security) automatically when a CREATE TABLE command is issued by an application.

YES indicates that the ALTER TABLE command will be issued.

NO indicates that the ALTER TABLE command will not be issued.

AutoQuote (QUOTE) Indicates whether or not UADriver will automatically place quotes around identifiers before sending the SQL request to the host.


ConvertVarchar (VARCHAR) Indicates whether or not UADriver will automatically convert VARCHAR references to CHAR before sending the SQL request to the host.


DefaultDatabase (DBASE) The default RDMS 2200 qualifier. Maximum length is 30 characters. Defaults to the UniAccess Configuration File setting. This field is case sensitive.

DefaultVersion (VERSION) The default RDMS 2200 version. Maximum length is 30 characters. Defaults to the UniAccess Configuration File setting.

HideSQLUnicode (UNICODE) Indicates that UADriver will drop the SQL_UNICODE datatype from the SQLGetTypeInfo result set.





Inttochar (INTTOCHAR) Converts RDMS SMALLINT and INT columns to character columns.

YES indicates that integer columns will be converted to character strings.

NO indicates that integer columns will not be converted.

Longchar (LONGCHAR) Indicates whether or not CHARACTER and NCHARACTER columns will be retuned as SQL_LONGVARCHAR columns.

YES indicates that SQL_LONGVARCHAR will be returned for CHARACTER columns with a length greater than 255 characters and for NCHARACTER columns with a precision greater than 127 (length 254 characters).

NO indicates that SQL_LONGVARCHAR will not be returned for CHARACTER and NCHARACTER columns.

ManualCommit (MANCOMMIT) Indicates whether or not UADriver will support the manual commit mode.

YES indicates that only the auto-commit mode is supported.

NO indicates that the manual commit mode is supported.

OrderProcColumns (ORDERPCOL) Indicates whether or not the order of the SQLProcedureColumns result set will be modified to return procedure parameter columns in the order the procedure expects them.

YES indicates that the result set will be returned in the order the procedure expects them.

NO indicates that the result set will be returned in the order defined by the ODBC SDK.

PrefixDropTable (DROPTABLE) Indicates whether or not UADriver will prefix a DELETE TABLE command before a DROP TABLE COMMAND prior to sending the SQL request to the host.


Replication (REPLICATION) Indicates whether or not UADriver will support Microsoft SQL Server replication. YES indicates that SQL Server replication is supported. NO indicates that SQL Server replication is not supported.




Rowlimit (ROWLIMIT) The number of rows that will be returned by a SELECT command. The valid range is from 0 to 2147483647 where 0 indicates that all rows should be returned. Defaults to the UniAccess Configuration File setting.

Spacetrim (SPACETRIM) Causes character columns to be returned as variable length fields with trailing spaces trimmed.

YES indicates that trailing spaces will be trimmed from character fields.

NO indicates that trailing spaces will not be trimmed.

StorageArea (SAREA) The name of the RDMS 2200 storage area in which tables are created. Maximum length is 30 characters.

Stripctrl (STRIPCTRL) Causes control characters to be removed from literal strings before they are submitted for processing.

YES indicates that all control characters will be converted to spaces, regardless of whether or not they are part of a literal string.

NO indicates that only control characters that are not part of a literal string will be converted.

TAccess (TACCESS) Defines the type of RDMS thread access to use when establishing a thread. Options are READ, UPDATE, and ACCESS. Defaults to the UniAccess Configuration File setting.

TRecovery (TRECOVERY) Defines the type of RDMS thread recovery to use when establishing a thread. Options are NONE, COMMANDLOOKS, QUICKLOOKS, and DEFERRED. Defaults to the UniAccess Configuration File setting.

Worksize (WORKSIZE) Defines the size of the RSA worksize to use when performing RDMS commands. The valid range is from 2000 to 100000. Defaults to the UniAccess Configuration File setting.

BLOBSIZE (BLOBSIZE) Defines the size of the maximum precision of a BLOB column that UARS returns to a single SELECT request. The valid range is from 0 to 2147483647. Defaults to the UniAccess Configuration File setting.




UAHS

AreaSearch (AREASEARCH)

Indicates whether or not the UAHS transaction should perform searches when key data is not provided. These searches may read the entire DMS database and, as a result, host performance may suffer.

YES indicates that when key DMS information is not

provided in the SELECT WHERE clause, every area associated with the selected record will be read sequentially.

NO indicates that when key DMS information is not provided in the SELECT WHERE clause, an error will be returned.

NOTE: Setting this value to YES may have a severe performance impact on the host environment.

Debug (DEBUG) Indicates whether or not the UAHS transaction should generate debug information in its print file. It should only be used to assist in debugging SELECT command problems.

YES indicates that the UAHS transaction will generate debug information in its print file.

NO indicates that it will not generate debug information.

DefaultDatabase (DBASE) The default UAHS database. Maximum length is 30 characters. Defaults to the UniAccess Configuration File setting.

Rowlimit (ROWLIMIT) The number of rows that will be returned by a SELECT command. The valid range is from 0 to 2147483647 where 0 indicates that all rows should be returned. Defaults to the UniAccess Configuration File setting.

Spacetrim (SPACETRIM) Causes character columns to be returned as variable length fields with trailing spaces trimmed.

YES indicates that trailing spaces will be trimmed from character fields.

NO indicates that trailing spaces will not be trimmed.




Application NotesThis section documents the UADriver settings required to support several popular ODBC tools with UniAccess for OS 2200. The list is limited to settings that are not the configured defaults. Most ODBC-compliant tools require no special settings and, therefore, are not listed here.

Andyne GQL

The Automatically Convert VARCHAR to CHAR option must be selected under the UADriver’s Advanced options setup.

Centura SQL Windows

The Allow Multiple Active Statements/Connection option must be selected under the UADriver’s Advanced options setup. Additionally, the Maximum Statement/Connection value should be configured.

Stripctrl (STRIPCTRL) Causes control characters to be removed from literal strings before they are submitted for processing.

YES indicates that all control characters will be converted to spaces, regardless of whether or not they are part of a literal string.

NO indicates that only control characters that are not part of a literal string will be converted.


III Accessing RDMS with UARS

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part III

Accessing RDMS 2200 with UARS

Chapter 6: Using UniAccess Relational Service for RDMS 2200

Chapter 7: UARS Commands

Chapter 8: RDMS Catalog RPCs


6 Using UARS

6 Using UniAccess Relational Service for RDMS 2200

This chapter provides information that allows client applications to use the UniAccess Relational Service (UARS) to communicate successfully with RDMS 2200. The information is relevant to both ODBC clients and Open Clients using the UniAccess ODBC Server for RDMS 2200.

Topics Page

UARS Overview 6-2

UARS Operational Settings 6-3

ODBC and Open Client API Support 6-3

RDMS 2200 Statement Support 6-4

RDMS 2200 Statements Supported by UARS 6-4

Statement Considerations for ODBC Clients 6-6

Statement Considerations for Open Clients 6-10

RDMS 2200 Datatype Support 6-20

Client and RDMS 2200 Datatype Correspondence 6-20

RDMS 2200 Datatype Descriptions 6-22

Datatype Considerations for Open Clients 6-26

RDMS 2200 Stored Procedure Support 6-28

Routing Procedure Requests 6-28

Error Processing 6-29

Datatype Correspondence 6-29

RDMS Scalar Functions 6-34

ODBC Scalar Functions 6-35

RDMS Scalar Functions 6-39



UARS OverviewUARS, the UniAccess Relational Service for RDMS 2200, is a component of the UniAccess ODBC Server for RDMS 2200 product package. UARS is an AIS-written transaction that services client SQL requests to RDMS 2200 databases. It updates and retrieves data using the RDMS 2200 interpretive SQL interface. It also handles catalog RPC requests from the UniAccess ODBC Driver and may be configured to call RDMS stored procedures.

Although UARS runs on the mainframe, it does not require customer programming at the mainframe. Customers need only install and configure the UniAccess ODBC Server for RDMS 2200 to make RDMS data available to network workstations and applications. Note that the default name of the transaction, UARS, can be changed during installation at a customer site, but its function remains the same.

Working in conjunction with UACS and other UniAccess components, UARS performs the following tasks:

• Processes client language requests by retrieving and/or modifying RDMS 2200 data

• Translates RDMS 2200 error messages to their SQL Server equivalents

• Processes Catalog RPCs from the UniAccess ODBC Driver (see page 8-2 for more information on Catalog RPCs)

• Calls RDMS 2200 stored procedures (see page 6-28 for more information on RDMS 2200 stored procedure support)

• Returns data and messages to the client.

While performing these actions, UARS performs significant preprocessing and postprocessing functions. Many of these functions may be determined by UARS operational settings.


Using UniAccess Relational Service for RDMS 2200 6-3

UARS Operational Settings

A UARS user or client developer should be aware that there are a number of settings that govern the behavior of UARS. These settings can be specified in three different places:

• On the client workstation in the UniAccess ODBC Driver/UARS data source configuration (see Chapter 5)

• On the client workstation at run-time, using special UARS SET commands (particularly for Open Client applications) (see Chapter 7)

• On the host in the UniAccess Configuration File (maintained by the system administrator) (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide).

There are also two commands available to obtain information about your operating environment:

• UARSINFO — returns the current operational settings (the information listed above), and other information about the UniAccess environment. The details of UARSINFO are documented in Chapter 7.

• UAINFO — returns only environment data (a subset of UARSINFO attributes) and is documented in Chapter 12. This command is not specific to UARS; it returns operating system and connections data for the UniAccess environment.

ODBC and Open Client API Support

UARS supports several APIs, including the ODBC API, through UADriver, and Open Client APIs—Client-Library and DB-Library. The ODBC API defines the SQL syntax for the client; Open Clients, however, need to support RDMS compliant syntax. Thus, Open Client programmers must ensure SQL and datatype compatibility between client applications and RDMS 2200. This chapter discusses the SQL statement, datatype, and RDMS 2200 stored procedure support features held in common among all supported APIs as well as those issues specific to Open Client programmers.



RDMS 2200 Statement SupportThis section lists and discusses the RDMS 2200 statements supported by UARS. The section Statement Considerations for ODBC Clients describes modifications made by UADriver to SQL commands received from an application. The section Statement Considerations for Open Clients explains SQL compatibility issues with RDMS 2200. It also describes useful methods of grouping SQL statements and of observing the results of database changes before committing to them.

RDMS 2200 Statements Supported by UARS

The following table lists all RDMS dynamic SQL command verbs supported by UARS. (These commands are explained in detail in the Unisys OS 2200 Relational Data Management System (RDMS 2200) SQL Programming Reference Manual.) The commands shared by both RDMS SQL and Transact-SQL (T-SQL) are indicated in the second column.

Table 6-1: Supported RDMS 2200 Statements UARS Supported RDMS 2200 SQL Statements

Shared T-SQL Command Description

ALTER TABLE yes Adds new columns to an existing table, activates access control, or adds, changes, or drops constraints on an existing table.

COMMIT* no Writes all updates made to the database since the last COMMIT.

CREATE INDEX yes Creates indexes on column(s) in a table.

CREATE SCHEMA no Creates a new schema.

CREATE TABLE yes Creates new tables and optional integrity constraints.

CREATE VIEW yes Creates a view, which is an alternative way of looking at the data in one or more tables.

DEBUG* no Checks the syntax of SQL statements without actually executing them.

* See the section Notes on Supported Statements following this table.



DELETE yes Removes rows from a table.

DROP INDEX yes Removes an index from the database.

DROP TABLE yes Removes a table definition and all of its data, indexes, views, and permission specifications from the database.

DROP VIEW yes Removes views from the database.

GRANT yes Assigns permissions to users.

INSERT yes Adds new rows to a table or view.

LEVEL* no Causes RDMS to return the internal level numbers of RDMS and its component RSA.

LOCK no Locks one or more tables during a step.

REVOKE yes Revokes permissions from users.

ROLLBACK*/OMIT yes Rolls a user-defined transaction back to the last savepoint inside the transaction or to beginning of the transactions.

SELECT* yes Retrieves rows from database objects.

SET STATISTICS no Directs RDMS to use or stop using previously collected statistics.

UNLOAD* no Dumps selected rows into a system data format (SDF) file.

UNLOCK no Releases the locking protocol for one or more tables.

UPDATE yes Changes data in existing rows, either by adding data or modifying existing data.

USE DEFAULT* no Establishes a new default qualifier or a new version name.

UARS Supported RDMS 2200 SQL Statements

Shared T-SQL Command Description

* See the section Notes on Supported Statements following this table.



Notes on Supported Statements

COMMIT/ROLLBACK. These commands can be used in a batch to encompass more than one transaction. See Grouping SQL Statements on page 6-14 for more information.

DEBUG. The output of the DEBUG command will be placed in the UARS print file on the OS 2200 host.

LEVEL. The results of the LEVEL command will be returned to the client application in a columnar result set.

SELECT. The maximum number of rows returned by a SELECT request can be defined for UARS. The system administrator may specify the maximum number of return rows allowed by using the RELSRV ROWLIMIT configuration parameter. When the number of rows generated by a SELECT request exceeds the ROWLIMIT value, no more rows are returned. If the value of ROWLIMIT is 0 (its default value), UARS does not limit the number of rows returned.

UNLOAD. The cursor form of this command cannot be used. A query-expression must be used.

USE DEFAULT. The user-specified USE DEFAULT command overrides the RDMS 2200 qualifier specified by the RELSRV SCHEMA or UAUSER SCHEMA UniAccess configuration parameters. The ability to override the configured schema may be disallowed by the system administrator. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide)

Statement Considerations for ODBC ClientsThe following sections summarize the modifications made by UADriver to ODBC-compliant SQL commands received from an application. Each SQL statement submitted to the UADriver via the SQLExecDirect or SQL Prepare interface is parsed by the driver. If the driver determines that a statement is not ODBC compliant (i.e., cannot be parsed), these modification will not occur.

• If a parsing error is detected using the SQLExecDirect interface, the original statement will be passed to RDMS for processing. The modifications to the SQL statements discussed in this section will not be applied to SQL statements submitted by the SQLExecDirect interface that UADriver couldn’t parse.



Handling SQLExecDirect parsing errors in this manner allows RDMS syntax to be passed by UADriver to RDMS.

• If a parsing error is detected using the SQLPrepare interface, the client application is notified by the return code of SQL_ERROR. After failing the SQLPrepare, this statement is not eligible for execution through the SQLExecute interface.

NoteThe semicolon is not used as an SQL statement terminator in ODBC SQL grammar. If a semicolon is used in an SQL statement passed to the UADriver, the statement will encounter a parsing error.

General Modifications

Owner Name Modifications

Owner names are removed from object names. For example, when UADriver receives the following SQL command from an application:

select * from schema1.owner1.table1

the owner (owner1) is removed and the following SQL command is sent to the RDMS 2200 database:

select * from schema1.table1

Empty String Conversion

When UADriver detects the use of an empty string ("''") in an otherwise valid SQL statement, it will convert the syntax to use NULL. For example, when UADriver receives the following SQL command from an application:

select * from schema1.table1 where column1=''

then the "‘’" will be changed to use a valid check for NULL, and the following syntax will be sent to the RDMS 2200 database:

select * from schema1.table1 where column1 IS NULL



Conversion of the Not Equal (!=) Operator

When UADriver detects the use of a not equal operator (!=) in an otherwise valid SQL statement, it will convert the operator to the RDMS not equal operator (<>). For example, when UADriver receives the following SQL command from an application:

select * from schema1.table1 where column1!='ABC'

the "!=" will be changed to "<>", and the following syntax will be sent to the RDMS 2200 database:

select * from schema 1.table1 where column1<>'ABC'

CREATE TABLE Modifications

When UADriver receives a CREATE TABLE statement, it determines what modification to make to the statement based upon what UADriver configuration options are selected. The Storage Area option pertains to the storage area in which a table is placed when it is created (see page 5-24). The Activate RDMS Access Control upon CREATE TABLE option (see page 5-25), pertains to the ownership and access control that will exist for a newly created table. These modifications are independent of each other. If both UADriver options are defined, both modifications will be made to the CREATE TABLE command before it is sent to RDMS 2200.

Storage Area Modifications

If the UADriver option Storage Area has been set, UADriver will use the schema name specified in the input SQL statement and the UADriver Storage Area setting to add a “,in schema.storagearea” clause to the CREATE TABLE statement. For example, if the UADriver Storage Area is set to “samplearea” and UADriver receives the following SQL statement from an application:

create table s1..t1 (fld1 integer not null)

the command is reformatted as follows and sent to the RDMS 2200 database:

create table s1.t1 (fld1 integer not null, in s1.samplearea)

If a schema name has not been included in the SQL statement received from the application, a schema name is not specified as part of the storage area. For example, if the UADriver



option Storage Area is set to “samplearea” and UADriver receives the following SQL statement from an application:

create table t1 (fld1 integer not null)


create table t1 (fld1 integer not null, in samplearea)

Ownership and Access Control Modifications

If the UADriver option Activate RDMS Access Control upon CREATE TABLE is set to YES, two additional SQL commands will automatically be sent to RDMS 2200 in a command batch. The first command is a COMMIT statement and the second command is an ALTER TABLE statement. The ALTER TABLE statement defines an owner for the newly created table and activates access control. For example, if the UADriver option Storage Area is set to YES and UADriver receives the following SQL statement from an application:

create table t1 (fld1 integer not null)

a command batch is formatted as follows and sent to the RDMS 2200 database:

create table t1 (fld1 integer not null); commit; alter table t1 owner is user, data access control is active;

DROP INDEX Modifications

When UADriver receives a DROP INDEX command, it will reformat the command into RDMS 2200 syntax if a table name has been included as part of the index name. If a table name has not been included as part of the index name, no manipulation is performed on the command. For example, when UADriver receives the following SQL command from an application:

drop index table1.index1


drop index index1 from table1



However, if UADriver received the following command from an application:

drop index index1

no modifications would be performed by UADriver.

DROP TABLE, DROP VIEW and REVOKE Modifications

The CASCADE keyword is removed from the DROP TABLE, DROP VIEW, and REVOKE commands. The RESTRICT keyword, however, is not removed from these commands. For example, when UADriver receives the following SQL command from an application:

drop table t1 cascade

the cascade keyword is removed and the following SQL command is sent to the RDMS 2200 database:

drop table t1

However, if UADriver received the following command from an application:

drop table t1 restrict

no modifications would be performed by UADriver.

Statement Considerations for Open ClientsWhen your Open Client application sends requests to RDMS 2200, you must be sure that its statements are compatible with RDMS 2200 SQL, the host database language. Likewise, you need to ensure that your application understands the format of the returned data. To accomplish these tasks, you need to write your applications using syntax and constructs that will be understood by the UARS transaction on the OS 2200 host.

ANSI 89 SQL is a standard definition of the language published by the American National Standards Institute, Inc. RDMS conforms to entry level SQL 92. RDMS also supports some features of intermediate and full-level SQL 92. To ensure SQL compatibility with RDMS, refer to the Unisys OS 2200 Relational Data Management System (RDMS 2200) SQL Programming Reference.



Another common SQL syntax is Transact-SQL (T-SQL). Both Microsoft SQL Server and Sybase SQL Server use T-SQL syntax.

The following sections explain the general rules you will need to follow and important syntax issues that must be addressed.

General Guidelines

Although UARS performs some processing on SQL strings before passing them to RDMS 2200, the basic rule is this: to access RDMS 2200 data, you must send SQL statements that can be understood by RDMS 2200. That is, you must use SQL syntax that is compatible with RDMS 2200 syntax.

When you send requests to UARS to access RDMS 2200 data, follow these general guidelines for SQL compatibility:

• SQL statements sent to RDMS 2200 must use RDMS SQL syntax. You can use any RDMS SQL command supported by UARS (see page 6-4 for a list of supported commands).

• SQL commands common to both RDMS 2200 SQL and T-SQL can be used to communicate with either RDMS 2200 or a SQL Server, but syntax differences may limit their compatibility.

• UARS uses RDMS’s dynamic SQL facility. This means that when you use UARS, you can only send dynamic SQL language requests; you cannot use any RDMS SQL commands restricted to static SQL.

T-SQL Versus RDMS Syntax Differences

Some of the SQL commands shared by RDMS 2200 SQL and T-SQL have syntax differences. Therefore, when you write a SQL command, use the syntax understood by the destination database.

In general, the more complex the SQL command, the more likely it is to use database-specific clauses and parameters. The major differences between the two versions of SQL are discussed below.



Naming Conventions

In T-SQL, table, view, and column names can be modified by the names of the owner and database, with each modifier followed by a period:

[[database.]owner.]table_name[.column_name][[database.]owner.]view_name[.column_name]

You can omit one or more of the modifiers, using the period as a place-holder. T-SQL uses the default value for omitted modifiers.

For example, to omit the owner in a table name, you would enter:

database..table_name

A T-SQL identifier can be up to 30 characters in length.

In RDMS 2200 SQL, a table name and a view name can have a qualifier prefix followed by a period and a version name suffix preceded by a colon. The combination of qualifier, table name, and version name are referred to as a table specification:

[qualifier.]table_name[:version_name]

Column names may be qualified by a table specification prefix followed by a period:

[table_specification.]column_name

Each of these naming components (qualifier, table_name, version_name and column_name) can be up to 30 ASCII characters. Additionally, index names may also be up to 30 ASCII characters.

Qualifiers and Versions

The term qualifier refers to the first portion of a table or view specification, which is prefixed to a table name to reduce ambiguity. Version refers to another copy of a table, which may contain different data. These concepts are unique to RDMS 2200 SQL.



Segments

Segments (named subsets of the database devices available to a particular SQL Server database) are unique to T-SQL; you cannot use segment names in SQL statements destined for RDMS 2200.

SELECT Statements

SELECT statements included within other SQL statements (e.g., CREATE VIEW) must also follow the syntax for the destination database.

Empty Strings vs. Null Strings

T-SQL differentiates between an empty string (" ' ' ") and a null (or undefined) value. RDMS 2200 does not support empty strings. Open Client users must avoid sending empty strings to RDMS 2200.

Apostrophes and Quotes

While T-SQL allows you to use either apostrophes or double quotes to delineate literal strings, RDMS 2200 recognizes only apostrophes as delimiters for literal strings. Double quotes are used to delineate identifiers.

As a general rule, RDMS 2200 expects:

• Delimiter identifiers to be enclosed by double quotes

select . . . from "UNIACCESS"."SAMPLETB"

• Character string constants (literals) to be enclosed by single quotes

select 'Employee' from . . .

To include an apostrophe (or single quote) in a SQL string, you must type the apostrophe twice in succession. For example,

select 'Employee''s Name' from . . .

Otherwise, if an apostrophe is included in a literal string in the following format:

'Employee's Name'



RDMS 2200 reads the apostrophe before the s as the end of the literal string, and interprets the single quote after Name as the beginning of a new literal. To avoid this problem, you must double any apostrophe you send to RDMS 2200 as part of a literal string.

Grouping SQL Statements

Batch SQL statements are useful for grouping a series of SQL statements into a single transaction or remote unit of work. UARS ensures that either all or none of the statements in a batch is committed, unless the batch itself contains COMMIT or ROLLBACK statements.

Syntax

To send SQL statements to UARS as a batch, you must use a semicolon after each statement as a delimiter. (A semicolon after the last SQL statement is optional, but will improve performance.) UARS processes each statement in a batch in the order it is listed in the batch.

NoteCREATE TABLE commands contained in a command batch should be followed by a COMMIT command. RDMS 2200 will not allow the table to be referenced by other commands in the batch until the CREATE TABLE command has been committed.

To create batches that include more than one transaction (unit of work), include the following subset of transaction control statements within a string of batched SQL statements:

• Committing transactions, that is, making any updates to the database permanent

commit [work]

• Rolling back transactions, that is, undoing any updates to the database to the point of the last commit.

rollback [work]



These statements end the current transaction (unit of work) and begin a new one. The first COMMIT or ROLLBACK within a batch applies to all the SQL statements from the beginning of the batch; a subsequent commit or rollback applies only to those statements between it and the preceding COMMIT or ROLLBACK.

Example

Using Interactive SQL, you can batch SQL statements to add an employee to the employee table and then check to see that the employee has been added.

insert employees (emp_lname, emp_fname, empid, dept)values('Wilson', 'Willy', '100009', '1357');

select * from employeeswhere empid = '100009';

go

This batch returns the row of information just added.

(1 row affected)emp_lname emp_fname empid dept--------- --------- -------- ----Wilson Willy 100009 1357(1 row affected)

In this example, the group of SQL commands constitutes a single transaction or unit of work; either all or none of the statements is committed.

Errors

If a SQL batch string contains an error, UARS returns an error message to the client and rolls back any changes made to the database during the current transaction. That is, no changes are made in the database for that unit of work.

Since results are returned as each statement is processed, be aware that the results you see on your screen may reflect data updates that are subsequently undone because of an error later in the batch. For example, assume a batch contains five SQL statements and that:

Statement #1 inserts a row into a table.

Statement #2 selects the inserted row and displays the results on the screen.



Statement #3 contains an error.

Statement #4 does a calculation.

Statement #5 displays more results on the screen.

The results requested in statement #2 will display on the screen; then an error message will be generated by statement #3. Statements #4 and #5 will not be processed.

Because the error occurs in statement #3, the rollback will occur after the results in statement #2 display on the screen. Since the error causes a rollback of all statements, the new row inserted by statement 1 will be erased, and subsequent statements selecting that row will return an error. If you want to add that row, you must send a new insert statement to the host.

UARS User-Defined Transaction Support

User-defined transactions are a feature of UARS for Open Clients accessing RDMS 2200. User-defined transactions are useful for observing the results of database changes before the user decides to commit or roll back the changes.

Transaction control statements are used to define a group of single, non-batched SQL statements explicitly as a user-defined transaction. This ensures that the group is treated as a unit: all statements are committed or all statements are rolled back. Once begun, a user-defined transaction continues until it is explicitly ended by a transaction control statement or by an error.

User-defined transactions are implemented on the OS 2200 host by directing all client requests within a user-defined transaction to the same execution of the UARS (TIP) transaction. UARS does not exit after returning results from a SQL statement; the client-to-mainframe connection and database locks are maintained until a COMMIT or ROLLBACK is issued. As a result, RDMS 2200 resources may be effected by an incomplete transaction.



Syntax

UARS supports the following transaction control statements for user-defined transactions:

• Beginning transactions

begin {transaction | tran}

• Committing transactions

commit [thread | work] [advance | terminate]

• Rolling back transactions

rollback [work] [keep | requeue | discard]

omit thread [keep | requeue | discard]

NoteAs indicated by { } and [ ] in the syntax, transaction control statements must include TRANSACTION or TRAN with BEGIN, but no options are required with COMMIT and ROLLBACK.

User-defined transactions cannot contain batch SQL statements delimited by semicolons.

Example

Using Interactive SQL, the following statement adds a job_category to the job_category table.

begin trangoinsert uasample.job_category values (55, 'Test Description' )go

The transaction is not finished; you can submit another command to see the values just added.

select * from uasample.job_category where category_code = 55go



The preceding statement returns a row of information for the new employee that reflects the values you added:

CATEGORY_CODE DESCRIPTION ------------- ------------------------------ 55 Test Description

Depending on the results, you can either commit or roll back the transaction. The changes to the database are not completed, and no one else can access the changes until you explicitly end the transaction. If the new employee’s information is correct, you can finalize the addition with:

commit workgo

Restrictions

User-defined transactions are subject to the restrictions shown in the following table. A more complete explanation of these restrictions follows the table:

Table 6-2: Restrictions on User-Defined Transactions

Restriction Reason Result Message

Nested transactions Not supported by UARS. UARS ignores the second BEGIN TRAN and continues processing.

Warning message

Transaction names Not supported by UARS. The transaction is rolled back. Error message

Batch SQL Not supported with user-defined transactions.

UARS rolls back user-defined transactions containing semicolons.

Error message

Canceled requests Cancel applies only to the command being processed, not to the entire transaction.

The transaction is not rolled back; UARS processes the next SQL statement.

No message

RPCs Not supported within user-defined transactions.

RPC requests are not processed and an error message is returned to the client; the transaction is not effected.

Error message



To protect the integrity of the transactions (units of work) that you define using transaction control statements, you must observe the restrictions described below:

Nested transactions. Nested transactions, supported by T-SQL, are not supported by UARS. If UARS encounters another BEGIN TRAN while it is already processing a user-defined transaction, it sends a warning message to the client and continues processing the transaction.

Transaction names. Transaction names, supported by T-SQL, are not supported by UARS. If UARS encounters a transaction_name parameter, it sends an error message to the client and rolls back the transaction.

Batch SQL. Batch SQL statements cannot be used in user-defined transactions. If UARS encounters semicolon delimited batch SQL statements, an error is sent to the client, the transaction is rolled back, and UARS exits. See Grouping SQL Statements on page 6-14 for more information about error handling in batch SQL statements.

Cancelled requests. If a client cancels a request (by issuing DB_CANCEL or by pressing ctrl-c in Interactive SQL) while UARS is processing a user-defined transaction, the cancel affects only the return of the result set being processed at the time the cancel is issued. The transaction is not rolled back, and UARS continues processing the next statement in the transaction.

RPCs. If a client issues a remote procedure call while a user-defined transaction is active, the request is not processed and an error message is returned to the client.

Errors

Transaction control statements provide the user with considerable control over rollbacks and commits. However, the following errors always result in a rollback of user-defined transactions:

• Communication errors

• RDMS errors that generate a rollback

• UARS internal errors.



Error handling can also be affected by the optional UARS translation. The routines allow a site to customize UARS processing. These routines can raise errors. As a result, the translation routines can alter transaction control statements. (See Chapter 12 of the UniAccess for OS 2200 System Administration Guide for more information about the translation routines, or consult your UniAccess system administrator to see if this option is in use at your site.)

RDMS 2200 Datatype SupportRDMS 2200 shares a number of datatypes with SQL Server that you can use in ODBC and Open Client programs without conversion. It also has datatypes that require conversion into similar SQL Server datatypes by UARS. This section discusses datatype compatibility and UARS datatype processing.

Client and RDMS 2200 Datatype Correspondence

UniAccess Relational Service maps or converts RDMS 2200 datatypes to the client datatypes shown in Table 6-3. The notes following the table offer further explanation about datatype correspondences and conversions.

Table 6-3: Supported RDMS 2200 Datatypes and Client Correspondences

RDMS 2200 Datatype ODBC SQL Datatype Client-Library

Datatype6DB-Library Datatype6

BLOB SQL_LOGVARBINARY CS_IMAGE DBBINARY (SYBIMAGE)

CHARACTER1 SQL_CHARSQL_LONGVARCHAR

CS_VARCHARCS_TEXT

DBVARYCHARDBBINARY (SYBTEXT)

DATE2 SQL_DATE CS_CHAR DBCHAR

DECIMAL2 SQL_DECIMAL CS_CHAR DBCHAR

DOUBLEPRECISION

SQL_DOUBLE CS_FLOAT3 DBFLT8

FLOAT SQL_FLOAT CS_FLOAT3 DBFLT8

INTEGER4 SQL_INTEGERSQL_DECIMAL

CS_INTCS_CHAR

DBINTDBCHAR



NCHARACTER5 SQL_CHARSQL_UNICODESQL_LONGVARCHAR

CS_VARCHARN/ACS_TEXT

DBVARYCHARN/ADBBINARY (SYBTEXT)

NUMERIC2 SQL_NUMERIC CS_CHAR DBCHAR

REAL SQL_REAL CS_REAL DBREAL

SMALLINT4 SQL_SMALLINTSQL_DECIMAL

CS_SMALLINTCS_CHAR

DBSMALLINTDBCHAR

TIME2 SQL_TIME CS_CHAR DBCHAR

TIMESTAMP2 SQL_TIMESTAMP CS_CHAR DBCHAR

1 CHARACTER columns are retuned as SQL_CHAR unless the system administrator has set the RELSRV LONGCHAR configuration option to YES. In this case, UARS returns CHARACTER columns greater than 255 bytes as SQL_LONGVARCHAR.

2 Indicates datatypes converted by UARS.


4 INTEGER and SMALLINT columns are returned as fixed-point binary values (SQL_INTEGER and SQL_SMALLINT respectively) unless the system administrator has set the RELSERV/UAUSER INTTOCHAR configuration option to YES. In this case UARS converts INTEGER and SMALLINT columns to character strings (SQL_DECIMAL).

5 NCHARACTER columns are returned as SQL_CHAR if the RELSRV DOUNICODE configuration option is set to NO and, for ODBC clients, as SQL_UNICODE if the configuration option is set to YES. Additionally, UARS returns NCHARACTER columns greater than 254 bytes as SQL_LONGVARCHAR if the RELSRV LONGCHAR configuration option is set to YES.

6 For a discussion of issues specific to DB-Library and Client-Library datatype correspondences, see page 6-26

RDMS 2200 Datatype ODBC SQL Datatype Client-Library

Datatype6DB-Library Datatype6



RDMS 2200 Datatype Descriptions

This section provides descriptions of the supported RDMS 2200 datatypes listed in Table 6-3. The section also includes information about the precision, scale, and length of supported datatypes.

NoteFor ease of discussion, the notes on datatypes below mention only the ODBC SQL datatype. For a discussion of issues related to the DB-Library and Client-Library datatype equivalents, see page 6-26, Datatype Considerations for Open Clients.

CHARACTER. A CHARACTER column is a 9-bit-byte field (such as ASCII) of up to 7000 bytes. CHARACTER columns shorter than 255 characters are returned as 8-bit-byte SQL_CHAR fields with the high-order bit being dropped. UARS will truncate fields longer than 255 characters, generate an error, or return the field as a SQL_LONGVARCHAR column depending on the COMSRV CHARTRUN and RELSRV LONGCHAR configuration values (see Chapter 16 of UniAccess for OS 2200 System Administration Guide).

DATE. A DATE column can store date values from 0001-01-01 to 9999-12-31. DATE columns are returned as SQL_DATE fields.

DECIMAL. A DECIMAL column is an exact numeric field that can store values to ±999999999999999999999. You can specify that some of the digits be to the right of the decimal point. DECIMAL columns are returned as SQL_DECIMAL columns.

DOUBLE PRECISION. A DOUBLE PRECISION column is an approximate numeric field that can store values to ±8.988465674311579549E+307. The smallest positive value you can store in a DOUBLE PRECISION column is 2.781342323134001732E-309. DOUBLE PRECISION columns are returned as SQL_DOUBLE columns.

FLOAT. A FLOAT column is an approximate numeric field that can store values to ±8.988465674311579549E+307. The smallest positive value you can store in a FLOAT column is 2.781342323134001732E-309. FLOAT columns are returned as SQL_FLOAT columns.



INTEGER. An INTEGER column is an exact numeric field that can store values to ±34359738367. UARS generates a truncation error for numbers smaller than -2147483648 and numbers larger than 2147483647. INTEGER columns are returned as SQL_INTEGER or SQL_DECIMAL, depending on the setting of the RELSRV INTTOCHAR configuration option (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide.)

NCHARACTER. An NCHARACTER column holds 16-bit data (such as Kanji characters) of up to 3500 characters. By default, NCHARACTER columns are returned as SQL_CHAR datatypes, and columns longer than 254 characters (precision of 127) are either truncated or return an error, depending on the setting of the COMSRV CHARTRUN configuration option.

However, the system administrator may set the RELSRV/UAUSER DOUNICODE configuration option to cause UADriver to return NCHARACTER columns as SQL_UNICODE datatypes. This setting can be used when ODBC applications are capable of handling double-byte characters. Additionally, the Support SQL_UNICODE Datatype setup option for the UADriver can be used to control the presentation of the SQL_UNICODE datatype to individual ODBC applications when the DOUNICODE parameter of the RELSRV/UAUSER configuration statement is set to YES.

In addition, the system administrator may set the RELSRV/UAUSER LONGCHAR configuration option to return NCHARACTER columns longer than 254 characters as SQL_LONGVARCHAR columns. (See Chapter 16 of the UniAccess for OS 2200 System Administration Guide for a discussion of the configuration options mentioned above.)

NUMERIC. A NUMERIC column is an exact numeric field that can store values to ±999999999999999999999. You can specify that some of the digits be to the right of the decimal point. NUMERIC columns are returned as SQL_NUMERIC columns.REAL. A REAL column is an approximate numeric field that can store values to ±1.70141182E+38. The smallest positive value you can store in a REAL column is 1.46936794E-39. REAL columns are returned as SQL_REAL columns.

SMALLINT. A SMALLINT column is an exact numeric field that can store values ±131071. UARS generates a truncation error for numbers smaller than -32768 and numbers larger than 32767. SMALLINT columns are returned as SQL_SMALLINT or SQL_DECIMAL columns, depending on the setting of the RELSRV/UAUSER INTTOCHAR configuration option (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide.)



TIME. A TIME column can store time values from 00:00:00.000000 to 23:59:59.999999. TIME columns are returned as SQL_TIME fields.

TIMESTAMP. A TIMESTAMP column can store time values from 0001-01-01 00:00:00.000000 to 9999-12-31 23:59:59.999999. TIMESTAMP columns are returned as SQL_TIMESTAMP fields.

Precision

Precision specifications apply to both numeric and non-numeric datatypes.

• For numeric datatypes, precision refers to the maximum number of digits used by the datatype of the column.

• For character datatypes, precision refers to either the actual or maximum number of characters of a column or parameter.

• For DATE, TIME, and TIMESTAMP datatypes, precision refers to the maximum number of characters in the string representation.

Table 6-4 describes the precision of each RDMS 2200 datatype.

Scale

Scale indicates how many digits there are to the right of the decimal point. Scale applies only to some datatypes.

• For DECIMAL datatypes, scale is the second value specified in the datatype definition. For example, the scale of DECIMAL(10,3) is 3.

• The meaning of scale for those datatypes to which it applies is shown in Table 6-4.

Length

The length of the column is the maximum number of bytes returned to the application. Table 6-4 describes the length of each RDMS 2200 datatype. Note the following points:



• For character data, the length does not include the null termination byte.

• Length can be different than the number of bytes required to store the data on the data source.

Table 6-4: Precision, Scale, and Length of RDMS 2200 Datatypes

RDMS 2200 Datatype Precision Scale Length

BLOB n n/a n bytes

CHARACTER n n/a n bytes

DATE 10 n/a 10 bytes

DECIMAL p s p + 1 bytes

DOUBLE PRECISION* 18 n/a 8 bytes

FLOAT* n n/a 4 bytes if n < or = 27; 8 bytes if n > 27

INTEGER 10 n/a 4 bytes

NCHARACTER n n/a n * 2 bytes

NUMERIC p s p + 2 bytes

REAL 8 n/a 4 bytes

SMALLINT 5 n/a 2 bytes

TIME 8 if s = 0;8 + s + 1 if s < > 0

s 8 if s = 0;8 + s + 1 if s < > 0

TIMESTAMP 19 if s = 0;19 + s + 1 if s < > 0

s 19 if s = 0;19 + s + 1 if s < > 0

Where: n = The defined length of the column or parameter. For example, if CHAR(n) = CHAR(10), then the precision is 10. p = The defined maximum number of digits. For example, if DECIMAL (p,x) = DECIMAL(10,3), then the precision is 10. s = The number of digits to the right of the decimal point. For example, if DECIMAL(x,s) = (10,3), then the scale is 3.




Datatype Considerations for Open Clients

Empty Strings vs. Null Strings

T-SQL differentiates between an empty string (" ' ' ") and a null (or undefined) value. RDMS 2200 does not support empty strings. Open Client users must avoid sending empty strings to RDMS 2200.

Automatic Datatype Conversions

When UARS retrieves data in response to a client’s SELECT command, it does the following datatype conversions before returning the data to the client:

• RDMS DATE, DECIMAL, NUMERIC, TIME, and TIMESTAMP datatypes are converted to CHARACTER data (see the following section for more information).

• If the system administrator has set the RELSRV INTTOCHAR configuration option to YES, UARS will automatically convert INTEGER and SMALLINT datatypes into character data. Otherwise, they are returned as fixed-point binary values (see page 6-23).

NoteRDMS 2200’s Interpretive SQL does not differentiate between regular column values and aggregate column values. It sends all columns back in a regular data row.

Date and Time Datatype Conversion

RDMS 2200 DATE, TIME, and TIMESTAMP fields support dates from 0001-01-01 00:00:00.000000 to 9999-12-31 23:59:59.999999. However, DB-Library and Client-Library DATETIME columns hold dates between 1753-01-01 and 9999-12-31. This means that not all RDMS 2200 DATE, TIME, and TIMESTAMP fields can be converted to SQL DATETIME or SMALLDATETIME fields. Therefore, UARS returns DATE, TIME, and TIMESTAMP fields as character fields (see the datatype descriptions beginning on page 6-22).



Long CHARACTER / NCHARACTER strings

UARS has several options for returning CHARACTER columns longer than 255 bytes and NCHARACTER columns longer than 254 bytes.

• If long character support has been turned on by the system administrator, long CHARACTER and NCHARACTER columns are returned as CS_TEXT for Client-Library and as DBBINARY (SYBTEXT) for DB-Library.

• If long character support has been turned off and truncation has been turned on by the system administrator, long CHARACTER and NCHARACTER columns are truncated after 255 and 254 bytes respectively when they are returned to the client application.

• If both long character support and truncation have been turned off by the system administrator, the request will fail and an error message will be returned, but no data.

The system administrator can turn long character support on or off with the RELSRV/UAUSER LONGCHAR configuration parameter; truncation can be turned on or off with the COMSRV CHARTRUN configuration parameter (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide).

User Datatypes

Information about RDMS 2200 datatypes is available to ODBC clients from Catalog RPCs. UARS also allows Open Client applications to get this information from a user datatype that returns RDMS 2200 column descriptor information. For more information about user datatypes, see page 4-5.



RDMS 2200 Stored Procedure SupportAs of RDMS 2200 Level 9R1, RDMS supports stored procedures. An RDMS stored procedure is a group of SQL commands that reside in RDMS 2200 and can be executed as one unit (see the RDMS documentation, listed in Appendix E, for implementation details). Currently, they cannot generate result sets as can UniAccess Server-Library transactions.

In the UniAccess System, support for RDMS 2200 stored procedures is provided through the UniAccess Relational Service (UARS). The following section explains how UniAccess routes RDMS procedure calls, the kinds of errors detected by UARS, and parameter type conversions between client datatypes and RDMS 2200 datatypes.

Routing Procedure Requests

RDMS 2200 stored procedures are accessed by client procedure requests (RPCs) routed by UACS through the UARS transaction. Since UACS may also receive RPCs directed to Server-Library Transactions, it must have a method of determining how to route procedure requests and replies.

RPCs may be mapped individually by the system administrator using the RPCMAP configuration statement (see page 12-9). Alternatively, the administrator may chose to send all RPCs to either UARS for forwarding to an RDMS 2200 stored procedure or to the UniAccess Transaction Server for processing by a Server-Library transaction.

When RDMS 2200 sp_procedure and sp_procedure_column catalog information is returned to the client and UACS encounters duplicate RDMS stored procedure and Server-Library transaction names, the information returned in the result set is determined as follows:

• If an RPCMAP statement exists for this procedure, the TRANCODE value determines which procedure definition to return. If the TRANCODE is “%%UARS”, the RDMS procedure information is returned. Otherwise, the Server-Library procedure information is returned.

• If an RPCMAP statement does not exist, the OSPARM DFLTPROCENV statement determines which procedure definition to return. If the OSPARM DFLTPROCENV value is RDMS, the RDMS procedure information is returned. If the OSPARM DFLTPROCENV value is UATS, the Server-Library procedure information is returned.



Error Processing

UARS verifies that the format of the RPC request matches the RDMS procedure’s definition. UARS will detect the following kinds of errors. (For specific numbered error messages, see Appendix B.)

• Parameter datatype mismatch. UARS returns an error if the datatype of the parameter received does not match the datatype of the parameter defined for the RDMS 2200 stored procedure. The expected and actual parameter datatype will be returned in the error message. (Refer to the next section, Datatype Correspondence, for datatype correspondence tables.)

• Parameter name mismatch. UARS returns an error message if an incorrect named parameter is submitted. Named parameters are only available with the Open Client Interface; they are not avaiable to those using the ODBC interface.

• Parameter type mismatch. An RPC’s parameter is defined as input only, while the corresponding RDMS 2200 procedure’s parameter is defined as INOUT or OUT. The parameter with the invalid type and the expected type will be returned in the error message.

NoteAn RPC’s input-output parameter must be defined to receive RDMS 2200 OUT parameter values.

Datatype Correspondence

The following tables summarize the datatypes that are supported as parameters to RDMS 2200 stored procedures. Table 6-5 lists ODBC SQL to RDMS datatype correspondence; Table 6-6 lists Client-Library to RDMS datatype correspondence. These tables, along with Table 5-4 (Chapter 5), provide a comprehensive list of the type of parameter conversions that will be supported. Note that ODBC SQL datatypes in addition to those listed in Tables 6-5 and 6-6 can be used. If the ODBC SQL datatype is translated into a valid Client-Library datatype, the ODBC SQL datatype can be used.



Table 6-5 shows the ODBC SQL datatypes that are reported for the specified RDMS 2200 datatypes through SQLProcedureColumns. The first column is the RDMS 2200 datatype specified in the stored procedure. The second column lists Client-Library datatype equivalents. The ODBC request to execute the RDMS stored procedure will normally use these datatypes.

Table 6-5: ODBC SQL to RDMS 2200 Datatype Correspondence

Table 6-6 shows all valid Client-Library datatypes for a given RDMS stored procedure parameter datatype. The first column is the RDMS 2200 datatype specified in the stored procedure. The second column lists Client-Library datatype equivalents and those converted by UARS into the appropriate corresponding RDMS datatype. Note that for a Client-Library datatype to be converted to an RDMS datatype, it must be in a valid format for this conversion.

RDMS 2200 Datatype ODBC SQL Datatype

CHARACTER SQL_CHAR

DATE SQL_DATE

DECIMAL SQL_DECIMAL

DOUBLE PRECISION SQL_DOUBLE

FLOAT SQL_FLOAT

INTEGER SQL_INTEGER

NCHARACTER SQL_CHAR

NUMERIC SQL_NUMERIC

REAL SQL_REAL

SMALLINT SQL_SMALLINT

TIME SQL_TIME

TIMESTAMP SQL_TIMESTAMP



Table 6-6: Client-Library to RDMS 2200 Datatype Correspondence

RDMS 2200 Datatype

Client-Library Datatype Notes

CHARACTER CS_CHAR

CS_BINARY

CS_DATETIME

CS_DATETIME4

CS_REAL

CS_FLOAT

CS_TINYINT

CS_SMALLINT

CS_INT

CS_MONEY

CS_MONEY4

DATE CS_CHAR Fixed YYYY-MM-DD format

CS_DATETIME The TIME portion is discarded after conversion and the DATE portion reduced to adhere to CS_CHAR DATE format.

CS_DATETIME4 The TIME portion is discarded after conversion and the DATE portion reduced to adhere to CS_CHAR DATE format.

DECIMAL CS_CHAR +/-nn.nn format

CS_TINYINT

CS_SMALLINT

CS_INT

CS_MONEY

CS_MONEY4

DOUBLE PRECISION CS_CHAR +/-nn.nn or scientific notation

CS_REAL

CS_FLOAT

CS_INT



FLOAT CS_CHAR +/-nn.nn or scientific notation

CS_REAL

CS_FLOAT

CS_INT

INTEGER CS_CHAR +/-nnn format (precision normally limited to 10)

CS_TINYINT

CS_SMALLINT

CS_INT

NCHARACTER CS_CHAR

NUMERIC CS_CHAR +/-nn.nn format (precision normally limited to 21)

CS_TINYINT

CS_SMALLINT

CS_INT

CS_MONEY

CS_MONEY4

REAL CS_CHAR +/-nn.nn or scientific notation

CS_REAL

CS_FLOAT

SMALLINT CS_CHAR +/-nnn format (precision normally limited to 10)

CS_TINYINT

CS_SMALLINT

CS_INT

TIME CS_CHAR Fixed HH:MM:SS format plus optional variable sub-second portion “.xxxxxx”. Range is 00:00:00.000000 to 23:59:59.999999.

Note: RDMS allows the variable portion to be up to 6 digits, whereas ODBC allows only 3 digits. When converting between RDMS and ODBC TIME datatypes, the conversion will round up or down as appropriate.

RDMS 2200 Datatype




CS_DATETIME The DATE portion is discarded after conversion and the TIME portion reduced to adhere to CS_CHAR TIME format.

CS_DATETIME4 The DATE portion is discarded after conversion and the TIME portion reduced to adhere to CS_CHAR TIME format.

TIMESTAMP CS_CHAR Fixed YYY-MM-DD HH:MM:SS format plus variable sub-second portion “.xxxxxx”

The DATE portion of TIMESTAMP follows the DATE rules and the TIME portion of TIMESTAMP follows the TIME rules.

CS_DATETIME Conversion to fixed YYY-MM-DD HH:MM:SS format plus variable sub-second portion “.xxxxxx”


CS_DATETIME4 Conversion to fixed YYY-MM-DD HH:MM:SS format plus variable sub-second portion “.xxxxxx”


RDMS 2200 Datatype




RDMS Scalar FunctionsAs of RDMS 2200 Level 10R1, scalar functions have been added that can be called from a SQL statement. Scalar functions are built-in to a database engine and return a value for each row selected. (RDMS calls these scalar functions Built-in Functions or BIFs.) The UniAccess ODBC Driver will parse SQL statements containing the RDMS scalar functions using the long ODBC syntax, the short ODBC syntax, or RDMS syntax.

The long ODBC syntax for calling a scalar function is:

-–(*vendor(Microsoft),product(ODBC) fn scalar function *)--

For example:

select --(* Vendor(MICROSOFT),Product(odbc)fn add_months(birth_date, 4)*)—from employee

The short ODBC syntax for calling a scalar function is:

{ fn scalar function }

For example:

select {fn add_months(birth_date, 4)} from employee

The RDMS syntax for calling a scalar function is:

scalar function

For example:

select add_months(birth_date, 4) from employee

The names and functionality of the RDMS scalar functions have slight variations from the ODBC scalar functions. The UniAccess ODBC Driver will allow the ODBC application to use either the ODBC scalar function name, or the RDMS scalar function name.



ODBC Scalar Functions

Table 6-7 shows the ODBC scalar function and the mapping to the RDMS scalar function. When the ODBC function name is used, it will be mapped to the associated RDMS scalar function. Application portability is enhanced when the ODBC scalar functions are used exclusively.

Table 6-7: ODBC Scalar Functions

ODBC Scalar Function

RDMS Scalar Function Comments

ABS abs

ACOS acos

ASCII ascii

ASIN asin

ATAN atan

ATAN2 atan2

CEILING ceiling

CHAR char

CONCAT concat

CONVERT Not supported

COS cos

COT cot

CURDATE curdate

CURTIME curtime

DATABASE Not supported

DAYNAME dayname

DAYOFMONTH dayofmonth

DAYOFWEEK dayofweek

DAYOFYEAR dayofyear

DEGREES degrees

DIFFERENCE difference



EXP exp

FLOOR floor

HOUR hour

IFNULL ifnull

INSERT insert

LCASE lcase

LEFT left (See footnote*)

LENGTH length

LOCATE locate

LOG log The RDMS log function may be called with either one or two parameters. The ODBC LOG function only uses one parameter.

If the function is called with two parameters, the UniAccess ODBC Driver will assume it is using RDMS syntax.

LOG10 log10

LTRIM ltrim The RDMS ltrim function may be called with either one or two parameters. The ODBC LTRIM function only uses one parameter.


(See footnote*)

MINUTE minute

MOD mod

MONTH month

MONTHNAME monthname

NOW now

PI pi





POWER power

QUARTER quarter

RADIANS radians

RAND rand

REPEAT repeat

REPLACE replace The RDMS replace function may be called with either one or two parameters. The ODBC REPLACE function only uses one parameter.


RIGHT right (See footnote*)

ROUND round

RTRIM rtrim The RDMS rtrim function may be called with either one or two parameters. The ODBC RTRIM function only uses one parameter.


(See footnote*)

SECOND second

SIGN sing

SIN sin

SOUNDEX soundex

SPACE space

SQRT sqrt





SUBSTRING substring The RDMS substring function may be called with either one or two parameters. The ODBC SUBSTRING function only uses one parameter.


TAN tan

TIMESTAMPADD timestampadd

TIMESTAMPDIFF timestampdiff

TRUNCATE truncate The RDMS truncate function may be called with either one or two parameters. The ODBC TRUNCATE function only uses one parameter.


UCASE ucase

USER user

WEEK week

YEAR year

*The UADriver configuration setting “Remove trailing spaces from character columns (SPACETRIM)” will impact the behavior of any function that reduces the length of character strings being returned to the client application. If SPACETRIM is not set, the length of the string returned to the client application will be the original string length.

The UADriver configuration setting “Remove trailing spaces from character columns (SPACETRIM)” is dependent upon the UniAccess Configuration File setting SPACETRIM. SPACETRIM may be defined on the RELSRV and UAUSER configuration statements.

For example the results of the following SQL statement differ based upon the setting of SPACETRIM.

select concat (rtrim(first_name), concat(' ', rtrim(last_name))) from employee If SPACETRIM is not set, the results for employee_id 9011281 in the sample database will be: "Roger Harmon " If SPACETRIM is set, the results for employee_id 9011281 in the sample database will be: "Roger Harmon"





RDMS Scalar Functions

The UniAccess ODBC driver supports the following RDMS scalar functions:

Table 6-8: Supported RDMS Scalar Functions

A-I I-O O-W

ABS INITCAP OCTET_LENGTH

ABSVAL INSERT PATINDEX

ACOS INSESC PERMUTED_ID

ADD_MONTHS INSTR PI

ASCII ISALNUM POSITION

ASIN ISALPHA POSSTR

ATAN ISCNTRL POWER

ATAN2 ISDIGIT PUT_FILE

CEIL ISGRAPH QUARTER

CEILING ISLOWER RADIANS

CHAR_LENGTH ISPRINT RAND

CHARACTER_LENGTH ISPUNCT REPEAT

CHARINDEX ISSPACE REPLACE

CHR ISUPPER REPLICATE

COALESCE ISXDIGIT REVERSE

CONCAT JULIAN_DAY ROUND (mathematical)CONCATRTRIM LAST_DAY ROUND (date/time/timestamp)CONCATSTRIM LCASE RPAD

CONVERT LENGTH RTRIM

COS LN SECOND

COSH LOB_CRC SIGN

COT LOB_END_ADDRESS SIN

CURDATE LOB_END_PAGE SINH

CURTIME LOB_FILE SOUNDEX



For documentation on the RDMS scalar functions, please see the Unisys OS 2200 Enterprise Relational Database Server for ClearPath OS 2200 SQL Programming Reference Manual.

DATALENGTH LOB_ID SPACE

DATEADD LOB_ID_CRC SQRT

DATEDIFF LOB_START_ADDRESS STR

DATENAME LOB_START_PAGE STRFTIME

DATEPART LOCATE STRPTIME

DAYNAME LOG STUFF

DAYOFMONTH LOG10 SUBSTR

DAYOFWEEK LOWER SUBSTRING

DAYOFYEAR LPAD TAN

DAYS LTRIM TANH

DECODE MICROSECOND TIME

DEGREE MIDNIGHT_SECONDS TIMESTAMP

DEGREES MINUTE TIMESTAMPADD

DELESC MOD TIMESTAMPDIFF

DIFFERENCE MONTH TO_CHAR

EXP MONTHNAME TRUNC

EXTRACT MONTHS_BETWEEN TRUNCATE

FLOOR NEW_TIME UCASE

GETDATE NEXT_DAY UNIQUE_ID

GET_FILE NOW UPPER

HEX NSPACE VALUE

HOUR NVL WEEK

IFNULL OCTAL YEAR

A-I I-O O-W


7 UARS Commands

7 UARS Commands

This chapter describes the operational commands available through the UniAccess Relational Service (UARS). The information in this chapter is most relevant to Open Client users of UARS.

Topics Page

UARS Commands 7-2

BEGIN TRAN 7-5

SET ACCESS 7-6

SET BLOBSIZE 7-8

SET DISTTRAN 7-9

SET INTTOCHAR 7-11

SET LONGCHAR 7-12

SET RECOVERY 7-13

SET ROWLIMIT 7-15

SET SPACETRIM 7-16

SET STRIPCTRL 7-17

SET TRANSACTIVE 7-18

SET TRANSOPTION 7-19

SET UNICODE 7-22

SET USERTRAN 7-23

SET WORKSIZE 7-24

UARSINFO 7-26



UARS CommandsThe following commands are available through UARS. Also referred to as SET commands, these commands do not operate on RDMS 2200, but control the operating characteristics of the UARS transaction. For more information, see the description of each command that follows.

Table 7-1: UARS Commands

UARS COMMAND Description

BEGIN TRAN Begins a user-defined transaction sequence.

SET ACCESS Defines the type of RDMS thread access to use when establishing a thread.

SET BLOBSIZE Indicates whether or not BLOB column data may be returned and sets the allowable size of BLOB column data.

SET DISTTRAN Defines capability for the client to participate in distributed transactions.

SET INTTOCHAR Causes RDMS SMALLINT and INT columns to be converted to character columns.

SET LONGCHAR Indicates whether or not CHARACTER and NCHARACTER columns will be returned as SQL_LONGVARCHAR columns.

SET RECOVERY Defines the type of RDMS thread recovery to use when establishing a thread.

SET ROWLIMIT Limits the number of rows that will be returned by a SELECT command.

SET SPACETRIM Causes control character columns to be returned as variable length fields with trailing spaces trimmed.

SET STRIPCTRL Causes control characters to be removed from literal strings.

SET TRANSACTIVE Defines whether or not user-supplied translation routines should be invoked by UARS.

SET TRANSOPTION Provides a parameter that will be passed by UARS to the user-supplied translation routines.

SET UNICODE Indicates whether or not RDMS NCHARACTER columns are returned as SQL_UNICODE types.

SET USERTRAN Indicates whether or not UARS will allow user-defined transactions to be initiated. (User-defined transactions are initiated with the BEGIN TRAN command.)


UARS Commands 7-3

Most UARS commands have a related UADriver Setup command (and UADriver connection string attribute), and most are controlled by UniAccess Configuration File settings. The Configuration File settings establish default values for the user and indicate whether or not the user may override these default values by issuing UARS commands. The result set for the UARSINFO command indicates the current value of each attribute and whether or not the default value in the Configuration File may be overridden.

Table 7-2: UARS Command Relationships

SET WORKSIZE Defines the size of the RSA worksize to use when performing RDMS commands.

UARSINFO Returns information about the UARS operating environment.

UARS Command

UADriver Setup Command*

UniAccess Configuration File

Parameter

UARSINFO Attribute

BEGIN TRAN none none none

SET ACCESS Thread Access RELSRV/UAUSER ACCESS

THREAD ACCESS (25)

SET BLOBSIZE UARS Blobsize RELSRV/UAUSER MAXBLOBSIZE

UARS_BLOBSIZE

SET DISTTRAN Support Distributed Transactions

UAUSER DISTTRAN DISTTRAN (28)

SET INTTOCHAR Convert integers to characters RELSRV/UAUSER INTTOCHAR

UARS_INTTOCHAR (19)

SET LONGCHAR Support SQL_LONGCHAR RELSRV/UAUSER LONGCHAR

UARS_LONGCHAR (20)

SET RECOVERY Thread Recovery RELSRV/UAUSER RECOVERY

THREAD_RECOVERY (26)

SET ROWLIMIT Rowlimit RELSRV/UAUSER ROWLIMIT

UARS_ROWLIMIT (10)

* For a list of UADriver connection string attributes, see page 5-34.

UARS COMMAND Description



SET SPACETRIM Remove trailing spaces from character columns

RELSRV/UAUSER SPACETRIM

UARS_SPACETRIM (9)

SET STRIPCTRL Remove control characters from literal strings

RELSRV/UAUSER STRIPCTRL

UARS_STRIPCTRL (22)

SET TRANSACTIVE

Activate Translation RELSRV/UAUSER TRANSACTIVE

UARS_TRANSACTIVE (29)

SET TRANSOPTION

Translation Option RELSRV/UAUSER TRANSOPTION

UARS_TRANSOPTION (30)

SET UNICODE Support SQL_UNICODE RELSRV/UAUSER DOUNICODE

UARS_UNICODE (11)

SET USERTRAN Support manual commit RELSRV/UAUSER USERTRAN

USER_TRANSACTIONS (14)

SET WORKSIZE RSA Worksize RELSRV/UAUSER WORKSIZE

UARS_WORKSIZE (27)

UARSINFO none none none

UARS Command



Parameter

UARSINFO Attribute



UARS Commands BEGIN TRAN 7-5

BEGIN TRAN

Function

This command begins a user-defined transaction sequence.

Syntax

BEGIN {TRANSACTION | TRAN}

Comments

• User-defined transactions must be supported for the current connection. This can be configured using the RELSRV/UAUSER USERTRAN setting or by issuing the SET USERTRAN command.

• User-defined transactions cannot be initiated on connections that are enlisted in a distributed transaction.

• Once a user-defined transaction is initiated, no user-written UniAccess Server-Library transactions may be initiated on this connection until the user-defined transaction is terminated.

• For more information about the use of user-defined transactions see page 6-16.

Results

The BEGIN TRAN command does not return a result set.

7-6 SET ACCESS UniAccess for OS 2200 Client Guide


SET ACCESS

Function

This command defines the type of RDMS thread access to use when establishing a thread.

Syntax

SET ACCESS {READ | UPDATE | ACCESS}

Comments

• When READ is specified, the SET RECOVERY command is ignored.

• ACCESS is available to support features in RDMS 7R1 (SB6) and later releases; it should not be used with earlier RDMS versions.

• If this command is not used, the default thread access is determined by the OS 2200 UniAccess Configuration File settings.

• The default thread access for the user and the ability to override this value are determined by the RELSRV/UAUSER ACCESS setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

• If this command is contained as part of a batch of commands, it will not affect commands that follow it in the batch. It will only affect subsequent command batches. Also, if this command is contained within a transaction sequence, it will not affect other commands within the transaction. It will only affect subsequent commands after the transaction is committed or rolled back.

For example, if the following is a batched command:

SELECT * FROM TESTTABLE;SET ACCESS UPDATE;UPDATE TESTTABLE SET COL1 = 1


UARS Commands SET ACCESS 7-7

the SET ACCESS UPDATE command will not affect the thread access for the UPDATE TESTTABLE command. However, the thread access will be UPDATE for all subsequent commands.

If this command is contained within a transaction sequence (BEGIN TRAN — COMMIT/ROLLBACK sequence), it will not affect other commands within the transaction. It will only affect subsequent commands after the transaction is committed or rolled back.

For example, in the following transacted set of commands:

BEGIN TRAN;SELECT * FROM TESTTABLE;SET ACCESS UPDATE;UPDATE TESTTABLE SET COL1 = 1;COMMIT;

The SET ACCESS UPDATE command will not affect the UPDATE TESTTABLE command. However, the thread access will be UPDATE for all subsequent commands after the COMMIT command.

Results

The SET ACCESS command does not return a result set.

7-8 SET BLOBSIZE UniAccess for OS 2200 Client Guide


SET BLOBSIZE

Function

Indicates whether or not BLOB column data may be returned and sets the allowable size of BLOB column data that may be returned by a SELECT command.

Syntax

SET BLOBSIZE {0-2147483647}

Comments

• A value of 0 indicates that UARS should not honor any SELECT statement which includes a BLOB column in its result set.

• A non-zero value constrains a SELECT command to only return BLOB column data for columns whose precision does not violate the blobsize value. SELECT statements that result in blobsize violations will generate an error message instead of row data.

• The default blobsize value for the user and the ability to override this value are determined by the RELSRV/UAUSER BLOBSIZE setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Results

The SET BLOBSIZE command does not return a result set.


UARS Commands SET DISTRAN 7-9

SET DISTTRAN

Function

This command defines capability for the client to participate in distributed transactions.

Syntax

SET DISTTRAN {ON | OFF}

Comments

• If ON is specified, the client application will be allowed participate in distributed transactions.

If OFF is specified, the client application will be prevented from participating in distributed transactions.

NoteEven if SET DISTRAN is ON, the client does not automatically participate in distributed transactions. The client must still observe standard distributed transaction protocol in order to participate.

• For more information about the use of distributed transactions, see Chapter 13.

• The default value for the user and the ability to override this value are determined by the UAUSER DISTTRAN setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

• If this command is contained as part of a batch of commands, it will not affect commands that follow it in the batch. It will only affect subsequent command batches. Also, if this command is contained within a transaction sequence, it will not affect other commands within the transaction. Once the batch has been processed, the client is switched to the state indicated by the SET DISTTRAN request.

7-10 SET DISTRAN UniAccess for OS 2200 Client Guide


Results

The SET DISTTRAN command does not return a result set.


UARS Commands SET INTTOCHAR 7-11

SET INTTOCHAR

Function

This command causes RDMS SMALLINT and INT columns to be converted to character columns.

Syntax

SET INTTOCHAR {ON | OFF}

Comments

• ON indicates that UARS will convert SMALLINT and INT columns to zero-filled character strings of length 6 (7 if negative) and 11 (12 if negative) respectively. ODBC applications will be presented with columns of type SQL_DECIMAL where SMALLINT columns have a precision of 7 and a scale of 0 and where that INT columns have a precision of 12 and a scale of 0.

OFF indicates that SMALLINT columns are returned as fixed-point 16-bit binary values and INT columns are returned as fixed-point 32-bit binary values.

• This command can be used to workaround overflow errors that can occur when converting 18-bit SMALLINT and 36-bit INT values to 16-bit SQL_SMALLINT and 32-bit SQL_INTEGER values.

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER INTTOCHAR setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET INTTOCHAR command does not return a result set.

7-12 SET LONGCHAR UniAccess for OS 2200 Client Guide


SET LONGCHAR

Function

This command indicates whether or not CHARACTER and NCHARACTER columns will be returned as SQL_LONGVARCHAR columns.

Syntax

SET LONGCHAR {ON | OFF}

Comments

• ON will cause UARS to return any CHARACTER column with a precision greater than 255 characters as a TEXT column (ODBC SQL_LONGVARCHAR). It will also cause UARS to return any NCHARACTER column with a length greater than 254 characters (precision of 127) as a TEXT column, if SET UNICODE processing is turned OFF.

OFF will cause UARS to return CHARACTER columns as SQL_CHAR types. NCHARACTER columns will be returned as SQL_UNICODE types if SET UNICODE processing is turned ON; they will be returned as SQL_CHAR types if SET UNICODE processing is turned OFF.

• When this command not used, the UniAccess Configuration File COMSRV CHARTRUN setting determines whether CHARACTER and NCHARACTER columns are truncated or an error is generated.

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER LONGCHAR setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET LONGCHAR command does not return a result set.


UARS Commands SET RECOVERY 7-13

SET RECOVERY

Function

This command defines the type of RDMS thread recovery to use when establishing a thread.

Syntax

SET RECOVERY {NONE | COMMANDLOOKS |QUICKLOOKS |DEFERRED}

Comments

• When the SET ACCESS command is READ, SET RECOVERY is ignored.

• If this command is not used, the default thread recovery is determined by the OS 2200 UniAccess Configuration File settings.

• The default thread recovery for the user and the ability to override this value are determined by the RELSRV/UAUSER RECOVERY setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

• If the SET RECOVERY command is contained as part of a batch of commands, it will not affect commands that follow it in the batch. It will only affect subsequent command batches. Also, if this command is contained within a transaction sequence, it will not affect other commands within the transaction. It will only affect subsequent commands after the transaction is committed or rolled back.


SELECT * FROM TESTTABLE;SET RECOVERY COMMANDLOOKS;UPDATE TESTTABLE SET COL1 = 1

the SET RECOVERY COMMANDLOOKS command will not affect the thread recovery for the UPDATE TESTTABLE command. However, the thread recovery will be COMMANDLOOKS for all subsequent commands.If this command is contained within a transaction sequence (BEGIN TRAN —

7-14 SET RECOVERY UniAccess for OS 2200 Client Guide


COMMIT/ROLLBACK) sequence, it will not affect other commands within the transaction. It will only affect subsequent commands after the transaction is committed or rolled back.


BEGIN TRAN;SELECT * FROM TESTTABLE;SET RECOVERY COMMANDLOOKS;UPDATE TESTTABLE SET COL1 = 1;COMMIT;

The SET RECOVERY COMMANDLOOKS command will not affect the UPDATE TESTTABLE command. However, the thread recovery will be COMMANDLOOKS for all subsequent commands after the COMMIT command.

Results

The SET RECOVERY command does not return a result set.


UARS Commands SET ROWLIMIT 7-15

SET ROWLIMIT

Function

This command limits the number of rows that will be returned by a SELECT command.

Syntax

SET ROWLIMIT {0-34359738367}

Comments

• The valid range is from 0 to 2147483647 where 0 indicates that all rows should be returned.

• If the number of rows generated by a SELECT request exceeds the ROWLIMIT defined value, UARS stops generating rows.

• The default rowlimit for the user and the ability to override this value are determined by the RELSRV/UAUSER ROWLIMIT setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET ROWLIMIT command does not return a result set.

7-16 SET SPACETRIM UniAccess for OS 2200 Client Guide


SET SPACETRIM

Function

This command causes character columns to be returned as variable length fields with trailing spaces trimmed.

Syntax

SET SPACETRIM {ON | OFF}

Comments

• ON indicates that trailing spaces will be truncated.

OFF indicates that UARS will not trim trailing spaces from character fields before returning them to the user.

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER SPACETRIM setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The set SPACETRIM command does not return a result set.


UARS Commands SET STRIPCTRL 7-17

SET STRIPCTRL

Function

This command causes control characters (ASCII value less than 32) to be removed from literal strings before they are submitted to RDMS for processing.

Syntax

SET STRIPCTRL {ON | OFF}

Comments

• If ON is specified, UARS will convert all control characters (values ranging from 0x01 to 0x1F) to spaces (value 0x20), regardless of whether or not those control characters are part of a character literal.

If OFF is specified, UARS will convert only control characters that are not part of a character literal to spaces.

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER STRIPCTRL setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET STRIPCTRL command does not return a result set.

7-18 SET TRANSACTIVE UniAccess for OS 2200 Client Guide


SET TRANSACTIVE

Function

This command defines whether or not the UARS user-supplied translation routines should be invoked.

Syntax

SET TRANSACTIVE {ON | OFF}

Comments

• If ON is specified, UARS will call the user-supplied translation routines.

If OFF is specified, UARS will not call user-supplied translation routines.

NoteTranslation is dependent upon the site-supplied translation routine. If no translation routine is provided, this option will not provide any translation.

• For more information on creating and using the translation routines, see Chapter 12 in the UniAccess for OS 2200 System Administration Guide.

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER TRANSACTIVE setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Results

The SET TRANSACTIVE command does not return a result set.


UARS Commands SET TRANSOPTION 7-19

SET TRANSOPTION

Function

This command provides a parameter that will be passed by UARS to the user-supplied translation routines if the SET TRANSACTION value is YES. If this value is LETSJ or SJIS, UARS will also pass this value to RDMS.

Syntax

SET TRANSOPTION { NONE | LETSJ | SJIS}

Comments

• The SET TRANSOPTION command serves two purposes. First, it passes a value to the user-supplied translation routine when called by UARS. Second, if this parameter is LETSJ or SJIS, UARS also passes the value to RDMS. Based upon the value received, RDMS will determine the proper handling of Kanji identifiers and error messages.

• NONE indicates that the value ua_no_xlate should be passed to the user-supplied translation routine if SET TRANSACTIVE is YES. It also indicates that RDMS should use its default identifier format when returning Kanji identifiers.

LETSJ indicates that the value ua_letsj should be passed to the user-supplied translation routine if SET TRANSACTIVE is YES. It also indicates that RDMS should return Kanji identifiers in LETS-J format.

SJIS indicates that the value ua_sjis should be passed to the user-supplied transaction routine if SET TRANSACTIVE is YES. It also indicates that RDMS should return Kanji identifiers in Shift-JIS format.

• The result of SET TRANSOPTION LETSJ or SJIS may cause RDMS to perform a translation from Shift-JIS or LETSJ.

7-20 SET TRANSOPTION UniAccess for OS 2200 Client Guide


• UARS will only pass the LETSJ or SJIS option to RDMS once during the existence of a transaction. RDMS will either be called at the beginning of a transaction if LETSJ or SJIS is the current TRANSOPTION setting or, if not, later when the first SET TRANSOPTION command with a value of LETSJ or SJIS is processed. Once RDMS has been called with the TRANSOPTION value, this value is always be passed to the user-provided translation routines.

• If the SET TRANSOPTION command is issued to UARS with a value of LETSJ or SJIS and the current TRANSOPTION setting is NONE then UARS will pass the LETSJ or SJIS value to RDMS immediately to facilitate appropriate Kanji translation.

• If the SET TRANSOPTION command is issued to UARS with a value of LETSJ, SJIS or NONE and the current TRANSOPTION setting is either LETSJ or SJIS, then UARS will not pass the designated TRANSOPTION value to RDMS and the original TRANSOPTION LETSJ or SJIS value will continue to be passed to the user provide translation routines until the transaction completes. However, the newly designated TRANSOPTION value will take effect when the next transaction is initiated.

• The above rules are illustrated by the following example: assume that current TRANSOPTION value is NONE and the following batched set of commands is issued to UARS.

set transoption letsj:select * from uasample.employee;set transoption sjis:select * from uasample.job_category;

The first SET TRANSOPTION command requests that the LETSJ option become operative and the second SET TRANSOPTION command requests that the SJIS option become operative. The first SET TRANSOPTION command is honored by calling RDMS with the value of LETSJ. The second SET TRANSOPTION command will not result in calling RDMS, but when the batch has been processed SJIS will become the TRANSOPTION setting for the next suite of UARS commands. Both SELECT commands will result in the user provide translation routines being called with a TRANSOPTION value of LETSJ.


UARS Commands SET TRANSOPTION 7-21

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER TRANSOPTION setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Results

The SET TRANSOPTION command does not return a result set.

7-22 SET UNICODE UniAccess for OS 2200 Client Guide


SET UNICODE

Function

This command indicates whether or not RDMS NCHARACTER columns are returned to an ODBC application as SQL_UNICODE types.

Syntax

SET UNICODE {ON | OFF}

Comments

• If ON is specified, NCHARACTER columns are presented to the ODBC client application as SQL_UNICODE datatype columns.

If OFF is specified, NCHARACTER columns are treated as SQL_CHAR datatypes.)

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER DOUNICODE setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

• This parameter is only relevant when the UniAccess Relational Service is being used with ODBC clients.

Results

The SET UNICODE command does not return a result set.


UARS Commands SET USERTRAN 7-23

SET USERTRAN

Function

This command indicates whether or not to support manual commit mode (BEGIN TRAN) allowing user-written transactions.

Syntax

SET USERTRAN {ON | OFF}

Comments

• User-defined transactions (either initiated by UADriver in manual commit mode or sent directly by an Open Client) do not utilize OS 2200 resources efficiently.

• ON indicates that UARS should process user-defined transaction requests.

OFF indicates that UARS should treat user-defined transaction requests as unrecognized commands.

• If this command is not used, the default mode is determined by the OS 2200 UniAccess Configuration File settings.

• The default value for the user and the ability to override this value are determined by the RELSRV/UAUSER USERTRAN setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET USERTRAN command does not return a result set.

7-24 SET WORKSIZE UniAccess for OS 2200 Client Guide


SET WORKSIZE

Function

This command defines the size of the RSA worksize to use when performing RDMS commands.

Syntax

SET WORKSIZE {2000-100000}

Comments

• The valid range is from 2000 to 100000.

• If this command is not used, the default RSA worksize is determined by the OS 2200 UniAccess Configuration File Settings.

• The default RSA worksize for the user and the ability to override this value are determined by the RELSRV/UAUSER WORKSIZE setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

• If this command is contained as part of a batch of commands, it will not affect commands that follow it in the batch. It will only affect subsequent command batches. Also, if this command is contained within a transaction sequence, it will not affect other commands within the transaction. It will only affect subsequent commands after the transaction is committed or rolled back.


SELECT * FROM TESTTABLE;SET WORKSIZE 50000;UPDATE TESTTABLE SET COL1 = 1

The SET WORKSIZE command will not affect the RSA worksize for the UPDATE TESTTABLE command. However, the RSA worksize will be 50000 for all subsequent commands.


UARS Commands SET WORKSIZE 7-25

If this command is contained within a transaction sequence (BEGIN TRAN — COMMIT/ROLLBACK) sequence, it will not affect other commands within the transaction. It will only affect subsequent commands after the transaction is committed or rolled back.


BEGIN TRAN;SELECT * FROM TESTTABLE;SET WORKSIZE 50000;UPDATE TESTTABLE SET COL1 = 1;COMMIT;

The SET WORKSIZE command will not affect the UPDATE TESTTABLE command. However, the RSA worksize will be 50000 for all subsequent commands after the COMMIT command.

Results

The SET WORKSIZE command does not return a result set.

7-26 UARSINFO UniAccess for OS 2200 Client Guide


UARSINFO

Function

This command returns information about UARS’ operating environment, including general information about RDMS 2200, UARS, and other UniAccess components, in a row/column format.

Syntax

UARSINFO

Comments

UARSINFO returns the list of attributes and their values described in Table 7-3.

Table 7-3: Information Returned by UARSINFO

Attribute Attribute Name Description

1 HOST_TDS_LEVEL TDS level supported by UARS.

2 HOST_RSA_LEVEL Relational syntax analyzer level.

3 HOST_RDMS_2200_LEVEL RDMS 2200 level.

4 HOST_MACHINE_TYPE Type of Unisys mainframe.

5 HOST_EXEC_LEVEL Host EXEC level.

6 UARS_LEVEL UniAccess Relational Service level.

7 UAFG_LEVEL UniAccess Fixed-gate level.

8 UARS_WAITTIME UARS self-initializing wait time in seconds.

9 UARS_SPACETRIM UARS character field space trim characteristics.YES indicates that spacetrim is active. NO means that spacetrim is inactive.

10 UARS_ROWLIMIT UARS return row limit. Zero indicates no limit.

11 UARS_DOUNICODE NCHARACTER ODBC client presentation. YES indicates that NCHARACTER columns are

presented to ODBC client applications as SQL_UNICODE datatype columns.


UARS Commands 7-27

NO indicates that NCHARACTER columns are presented to ODBC client applications as SQL_CHAR datatype columns.

12 DEFAULT_SCHEMA Default RDMS 2200 schema for this connection.

13 CURRENT_SCHEMA Current RDMS 2200 schema for this connection.

14 USER_TRANSACTIONS UARS user-defined transaction capability. YES indicates that user-defined transactions are

allowed. NO means that user-defined transactions are not

allowed.

15 CHANGE_DATABASE UARS change database capability.YES indicates that a database change can be made for

a session.NO indicates that a database change cannot be made

for a session.

16 CONNECTION_PID PID assigned to the connection.

17 CLIENT_INTR_ADDR Client’s IP address.

18 CLIENT_INTR_PORT Client’s port number.

19 UARS_INTTOCHAR UARS convert integer data to character strings indicator. YES indicates that SMALLINT and INT columns

will be converted to character strings. NO indicates that SMALLINT and INT columns will

be returned in their binary format.

20 UARS_LONGCHAR CHARACTER and NCHARACTER conversion indicator.

YES indicates that SQL_LONGVARCHAR will be returned for CHARACTER columns longer than 255 characters and for NCHARACTER columns longer than 254 characters.

NO indicates that CHARACTER columns will be returned as SQL_CHAR and that NCHARACTER columns will be returned as SQL_CHAR or SQL_UNICODE.




21 CHARACTER_TRUNCATION Character string truncation indicator. YES indicates that character strings longer than 255

characters should be truncated. NO indicates that character strings longer than 255

will generate an error.

22 UARS_STRIPCTRL Control character pre-processing indicator.YES indicates that all control characters will be

converted to spaces.NO indicates that only control characters that are not

part of a literal string will be converted.

23 DEFAULT_VERSION The default RDMS 2200 version.

24 CURRENT_VERSION The current RDMS 2200 version.

25 THREAD_ACCESS RDMS thread access definition. Options are READ, UPDATE, and ACCESS.

26 THREAD_RECOVERY RDMS thread recovery definition. Options are NONE, COMMANDLOOKS, QUICKLOOKS, and DEFERRED.

27 UARS_WORKSIZE RSA worksize definition. The valid range is from 2000 to 100000.

28 DISTTRAN UARS distributed transaction capability indicator.YES indicates that distributed transactions are

allowed.NO indicates that distributed transactions are not

allowed.

29 UARS_TRANSACTIVE UARS user translation capability indicator.YES indicates that user-supplied translation routines

should be called.NO indicates that user-supplied translation routines

should not be called.

30 UARS_TRANSOPTION UARS translation option. This value is passed to the user-supplied translation routine when UARS_TRANSACTIVE is YES. If this value is LETSJ or SJIS, the value is also passed to RDMS.

NONE indicates that the value ua_no_xlate should be passed to the user-supplied translation routine if UARS_TRANSACTIVE is YES. It also indicates that RDMS should use its default identifier format when returning Kanji identifiers.



UARS Commands 7-29

Results

The Table 7-4 describes the result set generated by the UARSINFO command.

Table 7-4: Result Set for UARSINFO

LETSJ indicates that the value ua_letsj should be passed to the user-supplied translation routine if UARS_TRANSACTIVE is YES. It also

indicates that RDMS should return Kanji identifiers in LETSJ format.

SJIS indicates that the value ua_sjis should be passed to the user-supplied transaction routine if UARS_TRANSACTIVE is YES. It also indicates that RDMS should return Kanji identifiers in Shift-JIS format.

31 UAMM_BLOCKSIZE The size in bytes of the configured UACS UAMM fixed memory blocks. UACS is capable of settingthe value of the UAMM BLOCKSIZE configuration parameter to 512, 1024, 2048, or 4096 bytes. The CS_PACKETSIZE should normally match this value.

32 UARS_BLOBSIZE The maximum precision of a BLOB column that may be retrieved by a SELECT command. Range 0 to 2147483647. Zero indicates that no BLOB column data may be retrieved.

Column NameDatatype (length) Notes

attribute_id int Numeric representation of the attribute whose value is returned in this row. This is one of the attributes listed in Table 7-3.

attribute_name varchar(30) Name of the attribute.

attribute_value varchar(80) Current value of the attribute.

useroverride short Indicates whether useroverride is on or off. 0 the attribute value cannot be overridden (off) 1 the attribute value can be overridden (on)




Example

The following is an example of the UARSINFO result set.

1, "HOST_TDS_LEVEL", "4.2", 02, "HOST_RSA_LEVEL", "6-41-1", 03, "HOST_RDMS_2200_LEVEL", "6-41-1", 04, "HOST_MACHINE_TYPE", "2200/500", 05, "HOST_EXEC_LEVEL", "44R4B", 06, "UARS_LEVEL", "10R3-0", 07, "UAFG_LEVEL", "10R3-0", 08, "UARS_WAITTIME", "0", 09, "UARS_SPACETRIM", "NO", 110, "UARS_ROWLIMIT", "0", 111, "UARS_DOUNICODE", "NO", 112, "DEFAULT_SCHEMA", "WORMHOLE", 013, "CURRENT_SCHEMA", "WORMHOLE", 114, "USER_TRANSACTIONS", "YES", 115, "CHANGE_DATABASE", "YES", 016, "CONNECTION_PID", "1000", 017, "CLIENT_INTR_ADDR", "192.168.1.128", 018, "CLIENT_INTR_PORT", "2707", 019, "UARS_INTTOCHAR", "NO", 120, "UARS_LONGCHAR", "NO", 121, "CHARACTER_TRUNCATION", "YES", 022, "UARS_STRIPCTRL", "NO", 123, "DEFAULT_VERSION", "PRODUCTION", 024, "CURRENT_VERSION", "PRODUCTION", 125, "THREAD_ACCESS", "UPDATE", 126, "THREAD_RECOVERY", "DEFERRED", 127, "UARS_WORKSIZE", "10000", 128, "DISTTRAN", "YES", 129, "UARS_TRANSACTIVE", "YES", 130, "UARS_TRANSOPTION", "NONE", 131, "UAMM_BLOCKSIZE", "4096", 032, "UARS_BLOBSIZE", "2000000", 1


8 UARS Catalog RPCs

8 RDMS Catalog RPCs

This chapter explains the function and use of Catalog RPCs for RDMS 2200. The reference section describes each supported Catalog RPC. The information in this chapter is relevant to both ODBC and non-ODBC users who use UARS to send language requests to RDMS 2200.

Topics Page

Overview of RDMS Catalog RPCs 8-2

Using Catalog RPCs 8-5

Coding Instructions 8-5

Datatypes 8-7

RDMS Catalog RPC Descriptions 8-8

sp_column_privileges 8-10

sp_columns 8-14

sp_databases 8-18

sp_datatype_info 8-19

sp_fkeys 8-24

sp_pkeys 8-28

sp_server_info 8-30

sp_special_columns 8-35

sp_sproc_columns 8-38

sp_statistics 8-43

sp_stored_procedures 8-47

sp_table_privileges 8-51

sp_tables 8-55



Overview of RDMS Catalog RPCsCatalog Remote Procedure Calls (RPCs) are the component of the UniAccess Relational Service (UARS) that provide access to RDMS 2200 catalog information. This information enables the UniAccess ODBC Driver to present an ODBC compliant view of the RDMS 2200 catalog to the client. It also allows UARS to return catalog information about RDMS 2200 stored procedures.

Catalog RPCs provide a simplified view of RDMS 2200 catalog information. These RPCs are compatible with the catalog interface for the Open Database Connectivity (ODBC) Application Programming Interface (API).

From a client perspective, the Catalog RPCs are simply a set of remote procedure calls that access RDMS 2200 catalog information. Actually, these RPCs are processed by the UARS transaction with its accompanying AIS-defined tables and views (see Figure 8-1). These components work together with the UniAccess System to enable transparent client access to RDMS 2200 catalog information. This catalog information may then be used to retrieve and/or modify RDMS 2200 data, using UARS.


RDMS Catalog RPCs 8-3

Figure 8-1: How RDMS Catalog RPCs are Used

As illustrated in Figure 8-1, the UARS transaction accesses two kinds of RDMS 2200 tables: RDMS 2200 System tables and AIS-defined RDMS 2200 tables. The RDMS System tables are accessed by AIS-created views. These tables are automatically maintained by the database management system; they cannot be changed by the system administrator. The AIS-defined tables were created for the UniAccess System for use with the UARS transaction; data in these tables may be modified by the system administrator using RDMS 2200 SQL commands. (See Appendix E of the UniAccess for OS 2200 System Administration Guide for information on maintaining the AIS-defined tables.)

U n i A c c e s s F i x e d - g a t e S h a r e d S u b s y s t e m

U n i A c c e s sS e r v e r - L i b r a r y

( U A S L )

U n i A c c e s sS e r v e r - L i b r a r y

( U A S L )

U n i A c c e s s M e s s a g e M a n a g e r ( U A M M )

M G M T B a n k M G M T B a n k

M M P R O C B a n k M M P R O C B a n k

M E M L I S T B a n k M E M L I S T B a n k

U A M M B l o c k B a n k ( sU A M M B l o c k B a n k ( s

U n i A c c e s sC l i e n t - L i b r a r y

( U A S L )

U n i A c c e s sC l i e n t - L i b r a r y

( U A S L )

G e n e r a l B a n k G e n e r a l B a n k

R P C M A P B a n k R P C M A P B a n k

U A U S E R B a n k U A U S E R B a n k

M M Q B a n k ( s ) M M Q B a n k ( s )

U n i A c c e s s D a t a M a n a g e r ( U A D T )



Table 8-1 lists the Catalog RPCs supported by UARS, gives the name of the entity being accessed, and indicates whether the entity being accessed by the Catalog RPC is a view of RDMS 2200 System tables or an AIS-defined table. For RDMS 2200 stored procedures (described on page 6-28), the lists of available procedures and the attributes of procedure columns are retrieved directly from RDMS 2200 System tables.

Table 8-1: UniAccess Catalog RPCs and Corresponding RDMS 2200 Entities

UniAccess Catalog RPC UNIACCESS1S1 Entity Accessed Entity Type

sp_column_privilegessp_columnssp_databasessp_datatype_infosp_fkeyssp_pkeyssp_server_infosp_special_columnssp_sproc_columns

sp_statisticssp_stored_proceduressp_table_privilegessp_tables

SPT_COLUMN_AUTHORIZATIONSSPT_COLUMNSSPT_TABLESSPT_DATATYPE_INFOSPT_FKEYS1, SPT_FKEYS2SPT_PKEYSSPT_SERVER_INFOSPT_SPECIAL_COLUMNS SPT_PROCEDURE_COLUMNSSPT_IOTYPESSPT_INDEX_STATSSPT_PROCEDURESSPT_TABLE_PRIVILEGESSPT_TABLES

VIEWVIEWVIEWTABLEVIEWVIEWTABLEVIEWTABLE*TABLE*VIEWTABLE*VIEWVIEW

* Under RDMS level 9 or greater, sp_sproc_columns and sp_stored_procedures also access RDMS 2200 system tables directly for information about RDMS 2200 stored procedures.



Using Catalog RPCsCatalog RPCs are often used implicitly by client applications on behalf of the user, but these requests can also be coded explicitly.

Coding Instructions

General coding information for all RPCs is included in this section. For the syntax of a particular RPC, see the Catalog RPC Descriptions section that begins on page 8-8.

Parameters

Catalog RPCs have both optional and required parameters. Required parameters must have values supplied; optional parameters default to predefined values.

ODBC applications. Parameters for Catalog RPCs are positional. All Catalog RPC parameters must be unnamed and passed in the order that corresponds to the Catalog RPC definition.

Open Client applications. Parameters for Catalog RPCs are positional or named. The following rules apply:

• If positional parameters are used, all parameters must be positional.

• If named parameters are used, all parameters must be named.

• Parameters should be coded in the positional order specified for that RPC.

Coding Example

The example below shows the syntax for the sp_tables Catalog RPC followed by a coded sample of the RPC. The coded example uses ODBC syntax. This syntax would be used if the request were sent through UADriver.

sp_tables [@table_name], [@table_owner], [@table_qualifier], [@table_type]

{call sp_tables ('EMPLOYEE','%','UASAMPLE','"TABLE"')}



The sample request could use named parameters as follows:

{call sp_tables (@table_name='EMPLOYEE', @table_owner='%', @table_qualifier='UASAMPLE',

@table_type='"TABLE"')}

Note that the name for each parameter begins with the “@” symbol. This is a convention used on all parameters used by the Catalog RPCs.

Table Owner and Qualifier Parameters

In the UniAccess Catalog RPCs, the terms table_owner and table_qualifier are used as follows:

• table_owner. The client can specify a particular table owner in the table_owner parameter. In this case, the TABLE_OWNER column of the result set contains the table owner specified in the parameter. If the table_owner is not specified, the catalog procedures ignore table ownership. For an unowned table, an owner of PUBLIC is returned.

• table_qualifier. Many Catalog RPCs have a table_qualifier parameter. The catalog support feature uses this parameter to identify the particular schema about which to return catalog information. If this parameter is omitted, the catalog procedures return catalog information using the user’s default schema defined in UACF.

Wild Cards

The following wild cards can be used in parameters that allow wild cards:

• percent ( % ) — any string of zero or more characters

• underscore ( _ ) — any single character.

To use a wild card as its corresponding character, use the backslash (\) as an escape character. If these characters are used in parameters that do not allow wild cards, they are treated as literals.



Table 8-2 shows some examples of wild cards and their use:

Table 8-2: Wild Card Examples

Datatypes

Three Catalog RPCs return datatype information: sp_datatype_info, sp_columns and sp_special_columns. The datatype descriptions returned in the result sets of these RPCs include information about precision, scale, length, and radix. For information about ODBC datatype correspondences, see Table 6-3. For information about the precision, length, and scale of supported datatypes, see Table 6-4.

Sample String Matches

%A% All names that contain the letter “A“For example: A AT CAT

B__

(“B” followed by two underscores)

All names that are three characters long and begin with the letter “B”For example: BAL BCD

% All names

Total% All names beginning with “Total”



RDMS Catalog RPC DescriptionsThe Catalog RPCs supported by the UniAccess Relational Service are described in this section. The discussion of each RPC includes its function, syntax, and a description of result set formats. Table 8-3 provides a brief description of the Catalog RPCs and a quick reference to the syntax and basic coding of each.

Table 8-3: Quick Reference for Catalog RPCs

Catalog RPC and Syntax Wild Cards? Datatype Type of Information Retrieved by RPC

sp_column_privileges @table_name, [@table_owner], [@table_qualifier], [@column_name]

NNNY

varchar(30)varchar(12)varchar(30)varchar(30)

Column privilege information for one table

sp_columns @table_name, [@table_owner], [@table_qualifier], [@column_name]

YYNY


Column descriptions for a table

sp_databases no parameters

List of available databases

sp_datatype_info* @data_type n/a int

Datatype descriptions

sp_fkeys @pktable_name, [@pktable_owner], [@pktable_qualifier], @fktable_name, [@fktable_owner], [@fktable_qualifier]

NNNNNN

varchar(30)varchar(12)varchar(30)varchar(30)varchar(12)varchar(30)

Foreign and primary key relationships

sp_pkeys @table_name, [@table_owner], [@table_qualifier]

NNN

varchar(30)varchar(12)varchar(30)

Primary key information for one table

* These catalog RPCs return information that is contained in AIS-defined tables. The data in these tables may be modified by the system administrator.



sp_server_info* [@attribute_id] n/a int

Server terms, limits, and capabilities

sp_special_columns @table_name, [@table_owner], [@table_qualifier], [@column_type], [@scope], [@nullable]

NNNn/an/an/a

varchar(30)varchar(12)varchar(30)intintint

Additional column information

sp_sproc_columns* [@sp_name], [@sp_owner],

[@sp_qualifier],

[@column_name]

YRDMS level 8, n/a; level 9 & greater, YRDMS level 8, n/a; level 9 & greater, NY

varchar(30)varchar(12)

varchar(30)

varchar(30)

Attributes of input parameters and result sets

sp_statistics @table_name, [@table_owner], [@table_qualifier}, [@unique], [@accuracy]

NNNn/an/a

varchar(30)varchar(12)varchar(30)intint

Statistics and/or indexes of one table

sp_stored_procedures* [@sp_name], [@sp_owner],

[@sp_qualifier]

YRDMS level 8, n/a; level 9 & greater, YRDMS level 8, n/a; level 9 & greater, N

varchar(30)varchar(12)

varchar(30)

List of available procedures

sp_table_privileges [@table_name], [@table_owner], [@table_qualifier]

YYN

varchar(30)varchar(12)varchar(30)

Table privilege information for one table


YYNN


List of table and views


* These catalog RPCs return information that is contained in AIS-defined tables. The data in these tables may be modified by the system administrator.

8-10 sp_column_privileges UniAccess for OS 2200 Client Guide


sp_column_privileges

Function

Returns column permission information for a single RDMS 2200 object.

Syntax

sp_column_privileges table_name, [table_owner], [table_qualifier], [column_name]

Parameters

table_name [varchar(30)](I) The name of the RDMS 2200 object whose column privilege information is requested. This parameter names a single RDMS 2200 object.

— Wild cards are not allowed.— This parameter is required.

table_owner [varchar(12)](I) The owner of the named object as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.

— Wild cards are not allowed.— This parameter is optional.

table_qualifier [varchar(30)](I) The schema name of the object(s) as defined to RDMS 2200. If you omit this value, information on object(s) in the user’s default schema is returned.


column_name [varchar(30)](I) The set of columns whose privilege information is requested. This value represents the name of one or more columns in the specified object. If you omit this value, information about all columns in the specified object is returned.

— Wild cards are allowed.— This parameter is optional.


RDMS Catalog RPCs sp_column_privileges 8-11

Comments

• You can use sp_column_privileges to find out which privileges the current user has on specified columns in a named RDMS 2200 object.

• Two catalog RPCs return information about user privileges. sp_table_privileges lists privileges granted for all columns in an object; sp_column_privileges lists privileges granted for individual columns in an object.

• The only privilege granted at the column level for RDMS 2200 objects is UPDATE authority.

If a user has SELECT, DELETE, and/or INSERT privilege on any one column in an RDMS 2200 object, then the user has that privilege on all columns in the object.

• This procedure returns one row for each privilege/grantee/column combination. For example, if a user has INSERT and SELECT privileges and PUBLIC has SELECT privileges on a column, three rows are returned for the column: one row for SELECT/user, one row for INSERT/user, and one row for SELECT/PUBLIC.

This procedure also indicates whether or not the grantee is authorized to grant the specified privilege to others (IS_GRANTABLE).

• If no rows are returned for a queried column, either the column does not exist or the user does not have any privileges on that column.

• Privilege information is returned only for those columns whose names are included in the column_name specification. No rows are returned for other columns, even if the user has been granted privileges on those columns.

Results

sp_column_privileges returns one row for each privilege a user has on a column in a table. For example, if a user has SELECT and INSERT privileges on three columns in a particular table, then a total of six rows are returned for that user.

8-12 sp_column_privileges UniAccess for OS 2200 Client Guide


Results are ordered by the following columns:

• TABLE_OWNER• TABLE_NAME• COLUMN_NAME• PRIVILEGE

The result set consists of the following columns:

Table 8-4: Result Set for sp_column_privileges

Column Name Datatype Notes

TABLE_QUALIFIER varchar (30) The qualifier of the table.

TABLE_OWNER varchar (12) The object’s RDMS 2200 owner.

Always NULL

TABLE_NAME varchar (30)

not NULL

The name of the object whose column information is returned.

This value is provided by the caller.

COLUMN_NAME varchar (30)

not NULL

The name of the column whose privilege information is returned in this row.

This is one of the columns specified by the caller.

GRANTOR varchar(12) RDMS 2200 authorization ID of the user who granted this privilege.

GRANTEE varchar(12)

not NULL

RDMS 2200 authorization ID of the user to whom this privilege was granted.


RDMS Catalog RPCs sp_column_privileges 8-13

See Also

sp_columns, sp_table_privileges

PRIVILEGE varchar(128)

not NULL

The privilege granted to the grantee on this column.

One of the following values: SELECT Grantee has permission to select rows in the associated object.

INSERT Grantee has permission to insert rows into the associated object.

UPDATE Grantee has permission to update rows in the associated object.

DELETE Grantee has permission to delete rows in the associated object.

IS_GRANTABLE varchar(3) Determines whether or not the grantee has permission to grant this privilege on this column to others.

One of the following values: YES Grantee can grant this privilege to others.

NO Grantee cannot grant this privilege to others.


8-14 sp_columns UniAccess for OS 2200 Client Guide


sp_columns

Function

Returns column descriptions for one or more RDMS 2200 objects.

Syntax

sp_columns [table_name], [table_owner], [table_qualifier], [column_name]

Parameters

table_name [varchar(30)](I) The name(s) of one or more RDMS 2200 objects whose column information is requested.


table_owner [varchar(12)](I) The owner(s) of the object(s) as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.




column_name [varchar(30)](I) The set of columns for which information is requested. This value represents the name of one or more columns in the named object(s). If you omit this value, information about all columns in the named object(s) is returned.



RDMS Catalog RPCs sp_columns 8-15

Comments

• You can use sp_columns to get descriptive information about one or more columns in one or more RDMS 2200 objects.

This procedure does not return the contents of a column; it returns descriptive information about the column’s contents.

• The descriptive information includes:

— The name of the column and its associated datatype

— The name by which RDMS 2200 knows the datatype

— The integer code for the equivalent ODBC SQL datatype

— The precision, length, scale, and radix for the column

— Whether or not the column can be NULL.

• Table 6-3 lists supported datatypes and gives their ODBC SQL equivalents.

• You will be returned information for an object regardless of your authorization to access that object.

• If you request columns that do not exist, no rows are returned.

• For a discussion of precision, length, and scale, see page 6-24.

Results

sp_columns returns one row containing a description of each column in a table. Results are ordered by the following columns:

• TABLE_QUALIFIER• TABLE_OWNER• TABLE_NAME.



The columns contained in the sp_columns result set are described in Table 8-5.

Table 8-5: Result Set for sp_columns



TABLE_OWNER varchar (12) The object’s RDMS 2200 owner.

This value is provided by the caller; if left blank, the value is the owner of the object in RDMS.


not NULL




not NULL

The name of the column whose information is returned in this row.


DATA_TYPE smallint

not NULL

ODBC SQL datatype. Integer code for the ODBC SQL equivalent of this column’s datatype.1

TYPE_NAME varchar (32)

not NULL.

RDMS datatype. String representation of this column’s RDMS datatype.

PRECISION int The number of significant digits. For non- numeric datatypes, this column contains NULL values. 2

LENGTH int The length of the column in bytes.2

1 Table 6-3 shows how ODBC datatypes correspond with supported RDMS 2200, DB-Library, and Client-Library datatypes.

2 Table 6-4 gives the precision, length, and scale of each supported datatype.


RDMS Catalog RPCs sp_columns 8-17

See Also

sp_column_privileges, sp_sproc_columns

SCALE smallint The number of digits to the right of the decimal point, if the RDMS datatype is DECIMAL.

For INTEGER and SMALLINT data, this value is 0. For all other datatypes, this column contains NULL values. 2

RADIX smallint The numeration system (base) used for this RDMS datatype. For FLOAT data, this value is 2, indicating binary. For integer and decimal datatypes, this value is 10. For character datatypes, this column contains NULL values.

NULLABLE smallint The NULL value indicator. One of the following values:

0 (FALSE) Column cannot contain NULL values.

1 (TRUE) Column can contain NULL values.

REMARKS varchar (254) Always NULL.




8-18 sp_databases UniAccess for OS 2200 Client Guide


sp_databases

Function

Lists the RDMS 2200 databases available.

Syntax

sp_databases

Comments

You can use sp_databases to find out what RDMS 2200 databases are available.

Results

A list of the RDMS 2200 databases available to the client. Results are ordered by DATABASE_NAME.


Table 8-6: Result Set for sp_databases


DATABASE_NAME varchar(30)

not NULL

Name of an available database.

DATABASE_SIZE int Size of the named database in kilobytes.

Always NULL.

REMARKS varchar(254) Always NULL.


RDMS Catalog RPCs sp_datatype_info 8-19

sp_datatype_info

Function

Returns information about the datatypes supported by RDMS 2200.

Syntax

sp_datatype_info data_type

Parameters

data_type [int](I) The ODBC datatype about which information is requested. To get information about all datatypes, give this parameter a value of ALL_TYPES.

— This parameter is required.

Assign this parameter one of the following values.

ODBC Datatype RDMS 2200 Datatype Name

0 ALL_TYPES1

1 CHAR

9 DATE

3 DECIMAL

8 DOUBLE PRECISION

6 FLOAT

4 INTEGER

-95 NCHARACTER2

2 NUMERIC

1 Not an RDMS 2200 datatype; this value returns information about all RDMS 2200 datatypes.

2 If the UniAccess Configuration RELSRV DOUNICODE parameter is NO, NCHARACTER information will not be returned.

8-20 sp_datatype_info UniAccess for OS 2200 Client Guide


Comments

• You can use sp_datatype_info to get descriptive information about one or more RDMS 2200 datatypes.

• Table 6-3 lists supported datatypes and their ODBC SQL equivalents.

• The requested information is stored in an AIS-defined RDMS 2200 table. This is not an RDMS 2200 system table, but a table created and maintained by the RDMS 2200 database administrator.

NoteRemember that the table queried by this RPC is maintained by the database administrator and is not an RDMS 2200 system table. Errors and inconsistencies can be corrected by updating the RDMS 2200 table.

Results

sp_datatype_info returns a list of datatypes with information about each. Results are ordered by the columns DATA_TYPE and TYPE_NAME. The result set consists of the columns described in Table 8-7.

7 REAL

5 SMALLINT

10 TIME

11 TIMESTAMP

ODBC Datatype RDMS 2200 Datatype Name

1 Not an RDMS 2200 datatype; this value returns information about all RDMS 2200 datatypes.

2 If the UniAccess Configuration RELSRV DOUNICODE parameter is NO, NCHARACTER information will not be returned.



Table 8-7: Result Set for sp_datatype_info


TYPE_NAME varchar(32)

not NULL

The name of the RDMS 2200 datatype that corresponds to the ODBC datatype in DATA_TYPE column.

DATA_TYPE smallint

not NULL

The ODBC datatype. This value is specified by the caller.

PRECISION int The maximum length allowed for this datatype. Table 6-4 gives the precision of each supported datatype.

LITERAL_PREFIX varchar(32) The character(s) used to mark the beginning of a literal. If a prefix is not used with this datatype, this column contains NULL values.

LITERAL_SUFFIX varchar(32) The character(s) used to mark the end of a literal. If a suffix is not used with this datatype, this column contains NULL values.

CREATE_PARAMS varchar(32) A description of the creation parameters required for this type.

For example, the creation parameters for RDMS 2200 DECIMAL type are “precision, scale”; for CHAR, “length”. If the datatype has no creation parameters, this column contains NULL values.

NULLABLE smallint

not NULL

The NULL value indicator. One of the following values: 0 SQL_NO_NULLS Datatype does not allow NULL values.

1 SQL_NULLABLE Datatype allows NULL values.



CASE_SENSITIVE smallint

not NULL

Uppercase or lowercase sensitivity. Indicates whether or not this datatype distinguishes between uppercase and lowercase characters.

One of the following values: 0 (FALSE) Columns of this datatype are not case-sensitive.

1 (TRUE) Columns of this datatype are case-sensitive.

SEARCHABLE smallint

not NULL

The rule for using this datatype in WHERE clauses.

One of the following values: 0 SQL_UNSEARCHABLE Datatype cannot be used in a WHERE clause.

1 SQL_LIKE_ONLY Datatype can be used in a WHERE clause only with LIKE.

2 SQL_ALL_EXCEPT_LIKE Datatype can be used in a WHERE clause with any comparison operator except LIKE.

3 SQL_SEARCHABLE Datatype can be used in a WHERE clause with any comparison operator.

Defaults 2 (for all numeric datatypes) 3 (for all non-numeric datatypes)

UNSIGNED_ATTRIBUTE smallint Indicates whether or not this attribute is unsigned (that is, it does not accept signed numeric values).

One of the following values: 0 (FALSE) Columns of this datatype are signed.

1 (TRUE) Columns of this datatype are unsigned.

NULL This column is not numeric and has no sign.




See Also

sp_server_info

MONEY smallint

not NULL

Indicates whether or not this is a money datatype.

One of the following values: 0 (FALSE) This is not a money datatype.

1 (TRUE) This is a money datatype.

NOTE: This field will always be 0.

AUTO_INCREMENT smallint Determines whether or not this datatype automatically increments. (Applies to numeric datatypes only).

One of the following values: 0 (FALSE) Columns of this datatype do not automatically increment. This is the case for all RDMS 2200 datatypes.

1 (TRUE) Columns of this datatype do increment automatically.

NULL This column is not numeric.

LOCAL_TYPE_NAME varchar(128) The localized version of the RDMS 2200 name of the datatype.

If localization is not supported, this field returns NULL values.

Currently, this field always returns NULL.

MINIMUM_SCALE smallint The minimum scale of the datatype in RDMS 2200. If the datatype has a fixed scale, this value is the same as the MAXIMUM_SCALE value.

This value will be NULL if scale is not applicable.

MAXIMUM_SCALE smallint The maximum scale of the datatype in RDMS 2200.



8-24 sp_fkeys UniAccess for OS 2200 Client Guide


sp_fkeys

Function

Returns information about the primary/foreign key relationships between RDMS 2200 tables.

Syntax

sp_fkeys pktable_name, [pktable_owner], [pktable_qualifier], fktable_name, [fktable_owner], [fktable_qualifier]

Parameters

pktable_name [varchar(30)](I) The name of the table containing the primary key. This value names a single RDMS 2200 table. If you omit this value, you must assign a value to fktable_name.

— Wild cards are not allowed.— This parameter is conditionally optional.

pktable_owner [varchar(12)](I) The owner of the table containing the primary key as defined to RDMS 2200. If you omit this value and if fktable_owner is omitted as well, the default returns all owners.


pktable_qualifier [varchar(30)](I) The schema name of the object(s) as defined to RDMS 2200. If you omit this value, information on object(s) in the user’s default schema is returned.



RDMS Catalog RPCs sp_fkeys 8-25

fktable_name [varchar(30)](I) The name of the table containing the foreign key. This value names a single RDMS 2200 table. If you omit this value, you must assign a value to pktable_name.

— Wild cards are not allowed.— This parameter is conditionally optional.

fktable_owner [varchar(12)](I) The owner of the table containing the foreign key as defined to RDMS 2200. If you omit this value, the default returns all owners.


fktable_qualifier [varchar(30)](I) The schema name of the object(s) as defined to RDMS 2200. If you omit this value, information on object(s) in the user’s default schema is returned.


Comments

• You can use sp_fkeys to retrieve information about the logical primary and foreign keys for RDMS 2200 tables.

• If fktable_name is omitted, sp_fkeys returns the set of all foreign keys that are related to the primary key of the specified primary key table.

• If pktable_name is omitted, sp_fkeys returns the set of all primary keys that are related to the foreign key of the specified foreign key table.

• If both fktable_name and pktable_name are provided, sp_fkeys returns all foreign keys in the named foreign key table that are related to the primary key of the named primary key table. This result set should include either zero or one key.

8-26 sp_fkeys UniAccess for OS 2200 Client Guide


Results

sp_keys returns a row for each column that is part of the foreign key or primary key in a PK/FK relationship.

If the request is for the foreign keys associated with a primary key (a value is given for pktable_name but not for fktable_name), results are ordered by the following columns:

• FKTABLE_OWNER• FKTABLE_NAME• KEY_SEQ

If the request is for the primary keys associated with a foreign key (a value is given for fktable_name but not for pktable_name), results are ordered by the following columns:

• PKTABLE_OWNER• PKTABLE_NAME• KEY_SEQ


Table 8-8: Result Set for sp_fkeys


PKTABLE_QUALIFIER varchar(30) The qualifier of the primary key table.

PKTABLE_OWNER varchar(12) Authorization ID of the owner of the table specified in PKTABLE_NAME.


PKTABLE_NAME varchar(30)

not NULL

The name of a table (primary key table) whose primary key is related to the foreign key of the table named in FKTABLE_NAME.

PKCOLUMN_NAME varchar(30)

not NULL

The name of a column in the primary key table.

FKTABLE_QUALIFIER varchar(30) The qualifier of the foreign key table.


RDMS Catalog RPCs sp_fkeys 8-27

See Also

sp_pkeys, sp_statistics

FKTABLE_OWNER varchar(12) Authorization ID of the owner of the table specified in FKTABLE_NAME.


FKTABLE_NAME varchar(30)

not NULL

The name of a table (foreign key table) whose foreign key is related to the primary key of the table named in PKTABLE_NAME.

FKCOLUMN_NAME varchar(30)

not NULL

The name of a column in the foreign key table.

KEY_SEQ smallint

not NULL

The position of the named column in the foreign key sequence. The first column is number 1.

UPDATE_RULE smallint The action to be applied to the foreign key when the SQL operation is UPDATE.

The returned value will always be: 1 SQL_RESTRICT Operation is not replicated in tables associated by a PK/FK relationship.

DELETE_RULE smallint The action to be applied to the foreign key when the SQL operation is DELETE.

The returned value will always be: 1 SQL_RESTRICT Operation is not replicated in tables associated by a PK/FK relationship.

FK_NAME varchar(128) The name of a table (primary key table) whose primary key is related to the foreign key of the table named in FKTABLE_NAME.

PK_NAME varchar(128) The name of a table (foreign key table) whose primary key is related to the primary key of the table named in PKTABLE_NAME.


8-28 sp_pkeys UniAccess for OS 2200 Client Guide


sp_pkeys

Function

Returns the column names that make up the primary key for a table.

Syntax

sp_keys table_name, [table_owner], [table_qualifier]

Parameters

table_name [varchar30)](I) The name of the table whose information is requested. This value names a single RDMS 2200 table.


table_owner [varchar12)](I) The owner of the table as defined to RDMS 2200. If you omit this value, information on objects(s) owned by all users is returned.




Comments

• You can use sp_pkeys to find out which column(s) constitute the primary key for a single RDMS 2200 object and, if the key is multi-column, in what sequence.


RDMS Catalog RPCs sp_pkeys 8-29

Results

sp_pkeys returns a row for each column in the primary key. Results are ordered by:

• TABLE_QUALIFIER• TABLE_OWNER• TABLE_NAME• KEY_SEQ

Table 8-9: Result Set for sp_pkeys

See Also

sp_fkeys, sp_statistics


TABLE_QUALIFIER varchar(30) The qualifier of the table.

TABLE_OWNER varchar(12) The authorization ID of the table’s owner.

Always NULL

TABLE_NAME varchar(30)

not NULL

The name of the table whose primary key information is returned.

COLUMN_NAME varchar(30)

not NULL

The name of a column that is part of the primary key.

KEY_SEQ smallint

not NULL

The position of the named column in the primary key sequence.

PK_NAME varchar(128) Always NULL

8-30 sp_server_info UniAccess for OS 2200 Client Guide


sp_server_info

Function

Returns general information about RDMS 2200 and UniAccess Relational Service.

Syntax

sp_server_info [attribute_id]

Parameters

attribute_id [int](I) The type of information desired. One of the Attribute ID’s listed in Table 8-10. This information is stored in a customer-maintained table on the OS 2200. If this value is omitted, all information in the table is returned.

— This parameter is optional.

Comments

• You can use sp_server_info to retrieve information about RDMS 2200 and/or UniAccess Relational Service. Each call returns a single piece of information. The caller specifies the type of information desired (attribute ID). sp_server_info returns the current value of that attribute.

• If no attribute ID is specified, information about all attributes is returned.

• The information queried by sp_server_info is stored in the Server Info Table, which is provided as part of UniAccess Relational Service and maintained by the RDMS 2200 database administrator (DBA).

NoteThe table queried by this RPC is maintained by the database administrator and is not an RDMS 2200 system table. Information about user-written UASL transactions must be entered manually by the DBA. Errors and inconsistencies can be corrected by updating the RDMS 2200 table.


RDMS Catalog RPCs sp_server_info 8-31

Table 8-10 shows the contents of the SPT_SERVER_INFO table as shipped. This list shows the default values provided with this product. Since this table is maintained locally, the values at your site may be different.

Table 8-10: Information Retrievable by sp_server_info

Attribute ID

Attribute Name Description and Default Attribute Value

1 DBMS_NAME The name of the RDMS 2200 database.

Default value: RDMS 2200

2 DBMS_VER The level of RDMS 2200 currently accessed.

The default string represents RDMS version 6R3.

Default Value: 6-27-2

10 OWNER_TERM The RDMS 2200 term for the user’s Authorization ID.

Default Value: NULL

11 TABLE_TERM The RDMS 2200 term for a table.

Default Value: table

12 MAX_OWNER_NAME_LENGTH The maximum number of characters allowed for an RDMS 2200 owner name. This is the maximum length for the OWNER_NAME parameter.

Default Value: 12

13 TABLE_LENGTH The maximum number of characters allowed for an RDMS 2200 table name. This is the maximum length for the TABLE_NAME parameter.

Default Value: 30

14 MAX_QUAL_LENGTH The maximum number of characters allowed for an RDMS 2200 qualifier name. This is the maximum length for the TABLE_QUALIFIER parameter.

Default Value: 30



15 COLUMN_LENGTH The maximum number of characters allowed for an RDMS 2200 column name. This is the maximum length for the COLUMN_NAME parameter.

Default Value: 30

16 IDENTIFIER_CASE The case requirements and sensitivity for identifiers, table names, column names, etc.

One of the following values: 1 Names must be uppercase. 2 Names must be lowercase. 3 Names are case-sensitive and can be mixed. 4 Names are not case-sensitive.

Default Value: 4

17 TX_ISOLATION The initial transaction level the server assumes, corresponding to an isolation level defined in ANSI SQL2.

Default Value: 0

20 MULTI_RESULT_SETS The indicator for multiple result set support.

One of the following values: Y RDMS 2200 supports multiple results sets.

N RDMS 2200 does not support multiple results sets.

Default Value: Y

22 ACCESSIBLE_TABLES The range of tables returned by sp_tables. Determines whether or not sp_tables returns tables for which the caller does not have privileges.

One of the following values: Y sp_tables only returns information about those tables on which the caller has privileges. N sp_tables returns information about all tables.

Default Value: N

Attribute ID



RDMS Catalog RPCs sp_server_info 8-33

100 USERID_LENGTH The maximum number of characters for a userid.

Default Value: 30

101 QUALIFIER_TERM The name used as a qualifier by RDMS 2200.

Default Value: schema

102 NAMED_TRANSACTIONS Indicates whether or not RDMS 2200 supports named transactions.

Default Value: N

103 SPROC_AS_LANGUAGE Indicates whether or not stored procedures can be executed as language events.

Default Value: N

104 ACCESSIBLE_SPROC The caller’s access to procedures. Determines whether or not the caller has permission to execute all procedures returned by sp_stored_procedures.

One of the following values: Y The caller can execute all listed procedures.

N The caller may not have permission to execute some of the listed procedures.

Note: Currently, this attribute always returns N.

105 MAX_INDEX_COLS The maximum number of columns in an index for RDMS 2200.

Default Value: 25

106 RENAME_TABLE Determines whether or not tables can be renamed.

Default Value: N

107 RENAME_COLUMN Determines whether or not columns can be renamed.

Default Value: Y

108 DROP_COLUMN Determines whether or not columns can be dropped.

Default Value: Y

Attribute ID




Results

sp_server_info returns a list of the requested attributes and their values. The result set consists of the columns described below.

Table 8-11: Result Set for sp_server_info

See Also

sp_datatype_info

109 INCREASE_COLUMN_LENGTH Determines whether or not column size can be increased.

Default Value: Y

110 DDL_IN_TRANSACTION Indicates whether or not DDL statements can appear in transactions.

Default Value: N

111 DESCENDING_INDEXES Determines whether or not descending indexes are supported.

Default Value: Y

500 SYS_SPROC_VERSION The version of the Catalog RPCs that is installed.

Default Value: 06.010000

Column Name Datatype (Length) Notes

ATTRIBUTE_ID int The numeric representation of the attribute whose value is returned in this row. This is one of the attributes listed in Table 8-10.

ATTRIBUTE_NAME varchar(60) The name of the attribute.

ATTRIBUTE_VALUE varchar(255) The current value of the attribute.

Attribute ID



RDMS Catalog RPCs sp_special_columns 8-35

sp_special_columns

Function

Returns information about the columns that make up a unique index of a single table.

Syntax

sp_special_columns table_name, [table_owner], [table_qualifier], [column_type], [scope], [nullable]

Parameters

table_name [varchar(30)](I) The name of the RDMS 2200 object whose index information is requested.


table_owner [varchar(12)](I) The owner of the named object as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.




column_type [int](I) The type of column whose information is requested. sp_special_columns returns information on only one column type: the unique index for a table. If the table has more than one unique index, sp_special_columns returns information about the primary key only.

1 SQL_BEST_ROWID Returns information on columns that make up the first unique index for the named table.

8-36 sp_special_columns UniAccess for OS 2200 Client Guide


If you omit this parameter, the behavior of sp_special_column is the same as if you assigned it a 1.


scope [int](I) The minimum required scope. Currently, only one scope option can be specified:

If you omit this parameter, the behavior of sp_special_columns is the same as if you assigned it a 0. If you specify a number other than 0, no rows are returned.


nullable [int](I) Indicates whether or not columns that allow NULLs are allowed in the index information returned. Currently only one nullable option can be specified:

1 SQL_NULLABLE Columns that are nullable are permitted in the index information returned.

If you specify any value other than 1, no rows are returned.— This parameter is optional.

Comments

• sp_special_columns returns information about the columns that make up the primary key on the specified table.

• Unlike sp_statistics, sp_special_columns does not return information about all unique indexes in a table; it returns information about the primary key only.

0 SQL_SCOPE_CURROW The row is guaranteed to be current only while positioned on that row.


RDMS Catalog RPCs sp_special_columns 8-37

Results

sp_special_columns returns information about the first unique index.

Table 8-12: Result Set for sp_special_columns


SCOPE smallint

not NULL

The actual scope of the row.

The following value: 0 SCOPE_CURROW


not NULL

The name of the input parameter or result set column whose information is returned in this row.

DATA_TYPE smallint

not NULL

The ODBC datatype.1 The integer code for the ODBC SQL equivalent of this procedure column’s RDMS datatype.


not NULL

The name of the RDMS 2200 datatype that corresponds to the ODBC datatype in DATA_TYPE. 1

PRECISION int The number of significant digits. For non-numeric datatypes, this column contains the length in bytes.2


SCALE smallint The number of digits to the right of the decimal point, if the RDMS 2200 datatype is DECIMAL. For INTEGER and SMALLINT data, this value is 0. For all other datatypes, this column contains NULL values.2

PSEUDO_COLUMN smallint Indicates whether or not the column is a pseudo-column.

The following value: 1 SQL_PC_NOT_PSEUDO



8-38 sp_sproc_columns UniAccess for OS 2200 Client Guide


sp_sproc_columns

Function

Lists descriptive information for the input parameters and result set columns for one or more stored procedures.

Syntax

sp_sproc_columns [sp_name], [sp_owner], [sp_qualifier] [column_name]

Parameters

sp_name [varchar(30)](I) The name of the procedure(s) whose information is returned.


sp_owner [varchar(12)]For RDMS level 8 or less:

(I) Leave blank— This parameter is ignored.

For RDMS level 9 or greater:(I) The owner of the named object(s) as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.


sp_qualifier [varchar(30)]For RDMS level 8 or less:


For RDMS level 9 or greater:(I) The schema of the named object(s) as defined to RDMS 2200. If you omit this value, information on object(s) in the user’s default schema is returned.



RDMS Catalog RPCs sp_sproc_columns 8-39

column_name [varchar(30)](I) The set of columns to be included in the result set. If you omit this value, information on all columns is returned.


Comments

• sp_sproc_columns describes input parameters and result set columns for the specified procedure(s).

• Use sp_sproc_columns before executing an RPC to retrieve column information about the procedure input parameters and result set columns.

• The requested RPC information is stored in an AIS-defined RDMS 2200 table. This is not an RDMS system table, but a table maintained by the RDMS 2200 database administrator. The DBA decides whether the table contains information about catalog RPCs only, or lists some or all customer-written remote procedures available to the UniAccess Transaction Server.

• For RDMS level 9 or greater, the result set generated by this procedure includes information from both the AIS-defined RDMS 2200 table and the RDMS 2200 system tables. The AIS-defined RDMS 2200 table defines UniAccess Server-Library transaction definition. The RDMS 2200 system tables define RDMS 2200 stored procedure definitions. The sp_owner and sp_qualifier parameters are only applied to the RDMS 2200 stored procedure information. These parameters cannot be used to limit the scope of the information returned from the AIS-defined tables.

When duplicate RDMS and Server-Library procedure definitions are encountered (qualifier, owner, and procedure names are all duplicate), the information returned in the result set is determined as follows:

— If an RPCMAP statement exists for this procedure, the TRANCODE value determines which procedure definition to return. If the TRANCODE is “%%UARS”, the RDMS procedure information is returned. Otherwise, the Server-Library procedure information is returned.



— If an RPCMAP statement doesn’t exist; the OSPARM DFLTPROCENV statement determines which procedure definition to return. If the OSPARM DFLTPROCENV value is RDMS, the RDMS procedure information is returned. If the OSPARM DFLTPROCENV value is UARS, the Server-Library procedure information is returned.

• One row is returned for each input parameter or result set column associated with a particular stored procedure.

• Table 6-3 shows how ODBC datatypes correspond with supported RDMS 2200, DB-Library, and Client-Library datatypes.

• Some ODBC applications require the information returned by sp_sproc_columns to function properly. This means that the AIS-defined RDMS 2200 table must be populated with procedure definition information for these applications to work.

• The UniAccess Transaction Server must be used to support the creation and execution of ODBC procedures (UASL transactions). UniAccess Relational Service does not provide this functionality.

NoteThe table queried by sp_sproc_columns for information about UASL transactions is maintained by the database administrator and is not an RDMS system table. Information about user-written UASL transactions must be entered manually by the DBA. Errors and inconsistencies can be corrected by updating the RDMS table.

Results

sp_sproc_columns returns a list of available procedures. Results are ordered by the columns PROCEDURE_NAME and COLUMN_TYPE.



RDMS Catalog RPCs sp_sproc_columns 8-41

Table 8-13: Result Set for sp_sproc_columns


PROCEDURE_QUALIFIER varchar(30) The qualifier of the procedure.1

PROCEDURE_OWNER varchar(12) The owner of the procedure.1

PROCEDURE_NAME varchar(30)

not NULL

The name of the procedure whose column information is returned in this row.


not NULL


COLUMN_TYPE smallint

not NULL

Defines the procedure column as a parameter or result set column:

One of the following values: 0 The procedure column is a parameter whose type is unknown.

1 The procedure column is an input parameter.

2 The procedure column is an input / output parameter.

3 The procedure column is a result set column.

5 The procedure column is the return value of the procedure.

DATA_TYPE smallint

not NULL

The ODBC SQL datatype. The integer code for the ODBC SQL equivalent of this procedure column’s RDMS datatype.2


not NULL

The RDMS 2200 datatype. A string representation of this procedure column’s RDMS datatype.

1 See Appendix E of the UniAccess for OS 2200 System Administration Guide for details about defining these values.





See Also

sp_stored_procedures



SCALE smallint The number of digits to the right of the decimal point if the RDMS 2200 datatype is DECIMAL. For INTEGER and SMALLINT data, this value is 0. For all other datatypes, this column contains NULL values.2

RADIX smallint The numeration system (base) used for this RDMS 2200 datatype. For FLOAT data, this value is 2, indicating binary. For integer and decimal datatypes, this value is 10. For character datatypes, this column contains NULL values.

NULLABLE smallint

not NULL

One of the following values:

0 NO_NULLS The procedure column cannot contain NULL values. 1 NULLABLE The procedure column can contain NULL values.

2 NULLABLE_UNKNOWN It is not know whether or not the procedure column accepts NULL values.

REMARKS varchar(254) A description of the column.1






RDMS Catalog RPCs sp_statistics 8-43

sp_statistics

Function

Returns index information for a single RDMS 2200 table and the indexes associated with that table.

Syntax

sp_statistics table_name, [table_owner], [table_qualifier], [unique], [accuracy]

Parameters

table_name [varchar(30)](I) The name of the RDMS 2200 object whose index and statistical information is requested.


table_owner [varchar(12)](I) The owner of the object as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.




unique [int](I) The type of information to retrieve (unique/non-unique indicator). If this value is omitted, INDEX_ALL is used.


8-44 sp_statistics UniAccess for OS 2200 Client Guide


Assign unique one of the following values:

accuracy [int](I) Leave blank.

— This parameter is ignored.

Comments

• You can use sp_statistics to get index information about a single RDMS 2200 table.

• You can request information for all indexes associated with the named object, or information for unique indexes only.

Results

sp_statistics returns information abut the named table. Results are ordered by the following columns:

• NON_UNIQUE• TYPE• INDEX_QUALIFIER• INDEX_NAME• SEQ_IN_INDEX

The result set consists of the following columns described in Table 8-14.

0 INDEX_UNIQUE Return information on unique indexes only.

1 INDEX_ALL Return information on all indexes. This is the default value.


RDMS Catalog RPCs sp_statistics 8-45

Table 8-14: Result Set for sp_statistics



TABLE_OWNER varchar(12) The authorization ID of the table’s owner. This value is provided by the caller. If left blank, the value is the owner of the object in RDMS.


not NULL

The name of the table whose index or statistical information is returned.

NON_UNIQUE smallint The unique index indicator. Determines whether or not duplicate values are permitted in the index.

One of the following values: 0 (FALSE) Index prohibits duplicate values.

1 (TRUE) Index allows duplicate values.

INDEX_QUALIFIER varchar(30) The qualifier for this index. This is the INDEX_QUALIFIER for the DROP INDEX SQL statement. The INDEX_QUALIFIER is the RDMS 2200 table name on which this index was created.

INDEX_NAME varchar(30) The name of the index described in this row.

If this row contains statistics on a table (TYPE is TABLE_STAT), NULL is returned in this column.

TYPE smallint

not NULL

One of the following values: 0 TABLE_STAT The row contains statistical information about a table.

1 INDEX_CLUSTERED The row describes a clustered index.

NOTE: This column is always returned as 1.

SEQ_IN_INDEX smallint The relative position of the named column in the key sequence. The first column is 1.



COLUMN_NAME varchar(30) The name of a column in an index key.

COLLATION char(1) One of the following values: A The sequence of the key columns is ascending.

D The sequence of the key columns is descending.

CARDINALITY int Cardinality of the table or index.

Note: This information is not readily available from RDMS 2200. These columns are always returned as NULL.

PAGES int Number of pages used to store the index or table.


FILTER_CONDITION char(128) If the index is a filtered index, this is the filter condition.




RDMS Catalog RPCs sp_stored_procedures 8-47

sp_stored_procedures

Function

Returns a list of available procedures.

Syntax

sp_stored_procedures [proc_name], [proc_owner], [proc_qualifier]

Parameters

proc_name [varchar(30)](I) The set of procedure names to be included in the result set. If you omit this value, information is returned on all procedures in the table.


sp_owner [varchar(12)]For RDMS level 8 or less:


For RDMS level 9 or greater:(I) The owner of the named object(s) as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.


sp_qualifier [varchar(30)]For RDMS level 8 or less:


For RDMS level 9 or greater:(I) The schema of the named object(s) as defined to RDMS 2200. If you omit this value, information on object(s) in the user’s default schema is returned.


8-48 sp_stored_procedures UniAccess for OS 2200 Client Guide


Comments

• sp_stored_procedures lists and describes remote procedures that a UniAccess client can call on the OS 2200. For each remote procedure, sp_stored_procedures returns the RPC name and the number of input parameters, return parameters, and result sets.

• The requested RPC information is stored in an AIS-defined RDMS 2200 table. This is not a RDMS system table, but a table created and maintained by the RDMS database administrator. The DBA decides whether the table contains information about catalog RPCs only, or lists some or all customer-written remote procedures available to the UniAccess Transaction Server.

• For RDMS level 9 or greater, the result set generated by this procedure includes information from both the AIS-defined RDMS 2200 table and the RDMS 2200 system tables. The AIS-defined RDMS 2200 table defines UniAccess Server-Library transaction definition. The RDMS 2200 system tables define RDMS 2200 stored procedure definitions. The sp_owner and sp_qualifier parameters are only applied to the RDMS 2200 stored procedure information. These parameters cannot be used to limit the scope of the information returned from the AIS-defined tables.

When duplicate RDMS and Server-Library procedure definitions are encountered (qualifier, owner, and procedure names are all duplicate), the information returned in the result set is determined as follows:

— If an RPCMAP statement exists for this procedure, the TRANCODE value determines which procedure definition to return. If the TRANCODE is “%%UARS”, the RDMS procedure information is returned. Otherwise, the Server-Library procedure information is returned.

— If an RPCMAP statement doesn’t exist; the OSPARM DFLTPROCENV statement determines which procedure definition to return. If the OSPARM DFLTPROCENV value is RDMS, the RDMS procedure information is returned. If the OSPARM DFLTPROCENV value is UARS, the Server-Library procedure information is returned.


RDMS Catalog RPCs sp_stored_procedures 8-49

• The system administrator maintains a map record of all RPCs used by the UARS transaction. The map record is stored in UADT (UniAccess Data Manager) and also used for UARS and user-defined mappings. This record contains the RPC names and the VALTAB transaction codes to which they are mapped. It does not contain information about parameters and result sets. (For information on the configuration of the RPC map record, see Chapter 16 of the UniAccess for OS 2200 System Administration Guide.)

• All RPC names in the table will be returned, regardless of whether or not the caller has privileges on those procedures.

• Some ODBC applications require the information returned by sp_stored_procedures to function properly. This means that the AIS-defined RDMS 2200 table must be populated with procedure definition information for these applications to work.

• The UniAccess Transaction Server must be used to support the creation and execution of ODBC procedures (UASL transactions). UniAccess Relational Service does not provide this functionality.

NoteThe RDMS 2200 table queried by sp_stored_procedures for information about UASL transactions is maintained by the database administrator and is not a RDMS 2200 table. Information about user-written UASL transactions must be entered manually by the DBA. Errors and inconsistencies can be corrected by updating the RDMS table.

Results

sp_stored_procedures returns a list or RPCs from the RDMS 2200 table. Results are ordered by the PROCEDURE_NAME column.


8-50 sp_stored_procedures UniAccess for OS 2200 Client Guide


Table 8-15: Result Set for sp_stored_procedures

See Also

sp_sproc_columns, sp_server_info


PROCEDURE_QUALIFIER varchar(30) The qualifier of the procedure.1

PROCEDURE_OWNER varchar(12) The owner of the procedure.1

PROCEDURE_NAME varchar(30)

not NULL

The name of the remote procedure described in this row.

NUM_INPUT_PARAMS int

not NULL

The number of input parameters in the RPC.

-1 in this column indicates that the number of input parameters is unknown.

NUM_OUTPUT_PARAMS int

not NULL

The number of return parameters in the RPC.

-1 in this column indicates that the number of return parameters is unknown.

NUM_RESULT_SETS int

not NULL

The number of result sets returned by the RPC.

-1 in this column indicates that the number of result sets is unknown.

REMARKS varchar(254) A description of the column.1

PROCEDURE_TYPE smallint

not NULL

Defines the procedure type. One of the following values:

0 It cannot be determined whether or not the procedure returns a value.

1 The returned object is a procedure; that is, it does not have a return value.

2 The returned object is a function; that is, it has a return value.



RDMS Catalog RPCs sp_table_privileges 8-51

sp_table_privileges

Function

Returns permission information for one or more RDMS 2200 tables.

Syntax

sp_table_privileges [table_name], [table_owner], [table_qualifier]

Parameters

table_name [varchar(30)](I) The name of the RDMS object(s) whose privilege information is requested.


table_owner [varchar(12)](I) The owner of the name object(s) as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.




Comments

• You can use sp_table_privileges to find out what privileges the current user has on one or more RDMS 2200 objects.

• This procedure returns one row for each privilege/grantee/table combination. For example, if a user has INSERT and SELECT privileges and PUBLIC has

8-52 sp_table_privileges UniAccess for OS 2200 Client Guide


SELECT privileges on a table, three rows are returned for the table: one row for SELECT/user, one row for INSERT/user, and one row for SELECT/PUBLIC.

This procedure also determines whether or not the grantee is authorized to grant that privilege to others (IS_GRANTABLE).

• Two catalog RPCs return information about user privileges. sp_table_privileges lists privileges granted for all columns in an object; sp_column_privileges lists privileges granted for individual columns in an object.

• The only privilege granted at the column level for RDMS 2200 objects is UPDATE authority.

If sp_table_privileges returns SELECT, DELETE, and/or INSERT in the PRIVILEGE column for an RDMS object, the user has that privilege on all columns in the object. If UPDATE is returned, the user has update privileges on at least one column in that object. Update privileges can be granted on a column-by-column basis. To find out which columns have update privileges, use sp_column_privileges.

NotePrivilege information is returned only for those tables whose names are specified. (Wild cards are allowed.) No rows are returned for other objects, even if the user has been granted privileges on those objects.

Results

sp_table_privileges returns a list of one or more tables with privilege information about each. Results are ordered by the following columns:

• TABLE_OWNER• TABLE_NAME• PRIVILEGE


RDMS Catalog RPCs sp_table_privileges 8-53


Table 8-16: Result Set for sp_table_privileges



TABLE_OWNER varchar(12) The object’s RDMS 2200 owner.



not NULL

The name of the object whose privilege information is returned.

This value is provided by the caller and is never NULL.

GRANTOR varchar(12) The RDMS authorization ID of the user who granted this privilege.

GRANTEE varchar(12)

not NULL

The RDMS authorization ID of the user to whom this privilege was granted.

This value is the user’s RDMS ID or PUBLIC.

PRIVILEGE varchar(128)

not NULL

The privilege granted to the grantee on this table.

One of the following values: SELECT The grantee has permission to select rows in the table.

INSERT The grantee has permission to insert rows into the table.

UPDATE The grantee has permission to update at least one column in rows in the table. (UPDATE permission is granted on a column-by-column basis.)

DELETE The grantee has permission to delete rows in the table.

8-54 sp_table_privileges UniAccess for OS 2200 Client Guide


See Also

sp_column_privileges, sp_tables

IS_GRANTABLE varchar(3) Determines whether or not the grantee has permission to grant this privilege on this column to others.

One of the following values: YES Grantee can grant this privilege to others.

NO Grantee cannot grant this privilege to others.



RDMS Catalog RPCs sp_tables 8-55

sp_tables

Function

Lists the objects stored on RDMS 2200.

Syntax

sp_tables [table_name], [table_owner], [table_qualifier], [table_type]

Parameters

table_name [varchar(30)](I) The names of one or more RDMS 2200 objects about which information is requested. If you omit this value, information is returned about all objects.


table_owner [varchar(12)](I) The owner(s) of the named object(s) as defined to RDMS 2200. If you omit this value, information on object(s) owned by all users is returned.




table_type [varchar(128)](I) Specifies the type(s) of objects to be returned. Enter a list of table types separated by commas, with each type enclosed in single quotes and the entire specification enclosed in double quotes.

8-56 sp_tables UniAccess for OS 2200 Client Guide


Assign this parameter any or all of the following values, entering them as shown:

“‘TABLE’, ‘VIEW’”


Comments

• To support enumeration of qualifiers, owners, and table types, sp_tables defines the following special semantics for the table_name, table_owner, table_qualifier, and table_type parameters:

— If table_qualifier is a single percent character (%) and table_owner and table_name are empty strings, then the result set contains a list of valid qualifiers for the data source. (All columns except the TABLE_QUALIFIER column contain NULLs.)

— If table_owner is a single percent character (%) and table_qualifier and table_name are empty strings, then the result set contains a list of valid owners for the data source. (All columns except the TABLE_OWNER column contain NULLs.)

— If table_type is a single percent character (%) and table_qualifier, table_owner, and table_name are empty strings, then the result set contains a list of valid table types for the data source. (All columns except the TABLE_TYPE column contain NULLs.)

• You can use sp_tables to find out which RDMS 2200 objects are available.

• The result set may include all objects that match the specified table_owner and table_name, not only those for which a user has privileges.

To find out whether or not this is the case, execute sp_server_info and request the value for the attribute ACCESSIBLE_TABLES. If the value is Y, the result set contains only those objects that the current user is authorized to access. If the value is N, the result set contains all objects that satisfy the name and owner specifications.


RDMS Catalog RPCs sp_tables 8-57

Results

sp_tables lists of RDMS 2200 objects. Results are ordered by the following columns:

• TABLE_TYPE• TABLE_QUALIFIER• TABLE_OWNER• TABLE_NAME

The result set consists of the columns described in Table 8-17.

Table 8-17: Result Set for sp_tables

See Also

sp_server_info, sp_table_privileges



TABLE_OWNER varchar(12) The object’s RDMS 2200 owner.


TABLE_NAME varchar(30) The name of the object whose information is returned.

TABLE_TYPE varchar(30) One of the following values: TABLE, VIEW.


IV Accessing DMS with UAHS

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part IV

Accessing DMS 2200 with UAHS

Chapter 9: Using UniAccess Hierarchical Service for DMS 2200

Chapter 10: UAHS Commands

Chapter 11: UAHS Catalog RPCs


9 Using UAHS

9 Using UniAccess Hierarchical Service for DMS 2200

This chapter provides information and guidelines to help you write client applications that use the UniAccess Hierarchical Service (UAHS) to access DMS 2200. The information contained here is relevant to both ODBC clients and Open Clients using the UniAccess ODBC Server for DMS 2200.

Topics Page

UAHS Overview 9-2

UAHS Operational Settings 9-3

ODBC and Open Client API Support 9-4

The UAHS Repository 9-4

UAHS SQL Support 9-7

UAHS SELECT Statement Syntax 9-7

UAHS SELECT Statement Extensions 9-10

UAHS SELECT Statement Limitations 9-11

Relational Mapping Implications 9-12

Repository Contents 9-13

DMS Set Mapping 9-13

Record Retrieval Methods 9-17

Sorting 9-17

UAHS Debug Information 9-18

DMS 2200 Datatype Support 9-19

Client and DMS 2200 Datatype Correspondence 9-19

Supported DMS 2200 Datatypes 9-21

Attributes of Supported DMS Items 9-22



UAHS OverviewUAHS, the UniAccess Hierarchical Service, is a component of the UniAccess ODBC Server for DMS 2200 product package. UAHS is an AIS-written transaction that provides read-only SQL access to DMS data and an ODBC-like view of a DMS schema. UAHS supports a subset of standard SQL SELECT statement syntax and handles catalog RPC requests from the UniAccess ODBC Driver.

Note that UAHS is the default name of the transaction. While its name may be changed during installation at your site, its functions remain the same.

Although UAHS runs on the mainframe, it does not require programming there. To make DMS 2200 data available to network workstations and applications, a site needs to 1) install and configure the UniAccess ODBC Server for DMS 2200, and 2) create a relational representation of the DMS 2200 items to be made available to client tools and applications. Those mainframe procedures are covered in Chapters 4 and 14 of the UniAccess for OS 2200 System Administration Guide.

Working in conjunction with UACS and other UniAccess components, UAHS performs the following tasks:

• Parses client SELECT statements to ensure they are syntactically correct

• Translates SELECT statements to DML commands

• Processes client requests by retrieving DMS 2200 data

• Processes catalog requests by retrieving meta database information (see Chapter 11 for more information on Catalog RPCs)

• Detects error conditions and formats appropriate messages

• Returns data and messages to the client.

While performing these actions, UAHS performs significant preprocessing and postprocessing functions. Many of these functions may be governed by UAHS operational settings.


Using UniAccess Hierarchical Service for DMS 2200 9-3

UAHS Operational Settings

A UAHS user or client developer should be aware that there are several settings that govern the behavior of UAHS, including the results returned from SELECT statements. The operations affected by these settings are listed briefly below:

• The ability to perform area searches

• The maximum number of rows returned by UAHS

• The default database name for client requests

• The ability to produce UAHS debugging information

• The trimming of trailing spaces from result columns

• The removal of special characters from strings.

These settings can be specified in three different ways:

• On the client workstation in the UniAccess ODBC Driver / UAHS data source configuration (see Chapter 5)

• At run-time, in the client application by using special UAHS SET commands (particularly for Open Client applications) (see Chapter 10)

• On the host in the UniAccess Configuration File (maintained by the system administrator) (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide).

If you need more information on a setting, or suspect a setting needs to be changed, consult the appropriate documentation for details.



There are also two commands available to obtain information about your operating environment:

• UAHSINFO — returns the current operational settings (the information listed above), and other information about the UniAccess environment. The details of UAHSINFO are documented in Chapter 10.

• UAINFO — returns only environment data (a subset of UAHSINFO attributes) and is documented in Chapter 12. This command is not specific to UAHS. It returns operating system and connections data for the UniAccess environment.

ODBC and Open Client API Support

UAHS supports several APIs, most notably the ODBC API through UADriver, and also the Open Client APIs—Client-Library and DB-Library. The ODBC API defines the SQL syntax for the client. UAHS has been designed to support a subset of the syntax defined by the ODBC specification, the ODBC SQL Minimum Grammar. Open Clients must, therefore, also adhere to this syntax. Open Client programmers must ensure SQL and datatype compatibility between their client applications and UAHS and DMS 2200.

This chapter explains the functionality available to all types of clients using UAHS. It gives the SELECT statement syntax to which Open Client programs must adhere. It also discusses datatype compatibility of client applications and DMS 2200.

The UAHS Repository

UAHS operates with a relational mapping of a DMS 2200 schema, which is stored in a repository called the UAHS Meta Database. The repository resides on the UniAccess host system and is built using utilities supplied with the UniAccess product. The repository is strictly a mapping of DMS information; it contains no DMS data.

The repository contains all entities available to UAHS clients and has been constructed from a DMS schema as follows:

• Tables have been defined by mapping one or more related DMS records.

• Columns have been mapped from fields in the underlying records.



• Tables have been organized into one or more UAHS databases.

Thus, the columns returned in response to UAHS catalog requests and all column names you use in client SELECT statements are really mappings defined in the UAHS Meta Database.

In the mapping process, an administrator has made several important decisions that affect the operation of UAHS and the results it produces. These decisions include:

• The portions of a schema available through UAHS

• The records and set relationships that comprise a table

• The fields included as table columns

• How tables are grouped to form databases

• The names of mapped items

• How records are obtained from DMS.

If items you need from DMS are apparently inaccessible, or if you receive unexpected or seemingly inconsistent results from UAHS, you may need to review the mapping definitions with your administrator. Mapping procedures and issues are discussed in detail in Chapter 14 of the UniAccess for OS 2200 System Administration Guide.

UAHS Catalog RPCs

The UAHS transaction supports a set of RPCs that provide catalog information for ODBC clients. They use the UAHS Meta Database to provide an ODBC compliant view of the DMS 2200 schema’s relational representation. The predefined RPCs are necessary to allow an ODBC client to retrieve table and column information prior to issuing SELECT requests. They may also be used independently by ODBC and Open Clients and are described in Chapter 11.



Catalog RPC and SELECT Statement Processing

Figure 9-1 illustrates how the UAHS Meta Database is used to support UAHS Catalog RPC requests and SELECT requests. After issuing Catalog RPCs to obtain table and column information, the client may use this information to issue SELECT requests to the UAHS transaction. UAHS examines the UAHS Meta Database to verify all aspects of the SELECT clauses and to determine the best way to retrieve data from the DMS 2200 database to satisfy the request.

Finally, UAHS retrieves data from DMS 2200 using the DML (Data Manipulation Language) FETCH command. UAHS constructs a result set, based on the WHERE clause criteria, and returns it to the client as if it had come from a relational database.

Figure 9-1: Catalog RPC and SELECT Statement Processing

The client requests catalog information by calling a remote procedure.

UACS receives the RPC and maps it to the UAHS transaction. The transaction processes the RPC by reading the UAHS Meta Database.

Mapped table and columninformation for DMS 2200 is extracted and returned to theclient via the same path.

The client may useinformation obtainedthrough Catolog RPCs to select datafrom a DMS 2200 database.

UACS receives the request and maps it to the UAHS transaction. The transaction processes the requestby reading the UAHS MDB to verify the SELECT statement and determine the best retrieval method.

UAHS retrieves the required information from DMS 2200 using DML FETCH commands. UAHS then constructs and returnsa result set to the client.

OS 2200

Client UACS

Catalog RPC

Data Request

UAHStransaction

UAHSMeta Database (MDB)

DMS 2200 Database



UAHS SQL SupportAs a read-only service, UAHS supports only the SQL SELECT verb. As mentioned above, UAHS supports a subset of the SELECT statement syntax defined by the ODBC Minimum SQL Grammar. In supporting the Open Client APIs and some popular ODBC tools, UAHS makes minor extensions to the specification to make UAHS SQL compatible with common SQL grammar.

UAHS is designed to allow Open Client programmers to use common and familiar syntax conventions for SQL whenever possible, whether accessing a traditional relational database or UAHS and DMS 2200. Doing so also provides SQL compatibility with another AIS product, UARS—the UniAccess Relational Service for RDMS 2200. (UARS is essentially the relational forerunner of UAHS, allowing clients to access RDMS 2200 databases. UARS is described and discussed in Chapter 6.)

UAHS was also designed, however, to limit the impact of UAHS processing on production applications. Because the UAHS transaction must parse SELECT statements and dynamically generate and execute DML commands, and because DMS data structures are optimized for hierarchical rather than relational access, UAHS may significantly affect overall system performance. Therefore, there are limits placed on the functionality available with UAHS and on the SELECT statement syntax it will accept.

In terms of functionality, UAHS supports queries that are simple row extractions, with search conditions limited to relational expressions (>, <, =, etc.), pattern matching (LIKE) and NULL comparisons, and single item sorting. Aggregation is limited to the ability to select unique values of a single item. No other aggregations or computations are supported. There are also no facilities for set union operations, subqueries, or intrinsic functions.

The next section describes UAHS functionality in terms of specific SQL syntax.

UAHS SELECT Statement Syntax

Here is the SQL SELECT statement syntax given by the ODBC 2.0 specification, which defines the minimum SQL syntax that an ODBC driver is required to support. (The ODBC Minimum SQL Grammar is a subset of the entry-level syntax of SQL-92.) To the right of each element of the syntax, we indicate implementation specifics, if any, for UAHS: unsupported elements, limitations, extensions, alternate syntax, and another variations from the standard element.



Statement

SELECT [ALL | DISTINCT] select-listFROM table-reference-list[WHERE search-condition][order-by-clause]

Components

Table 9-1 defines the elements of the SELECT statement listed previously.

Table 9-1: UAHS SELECT Statement Syntax Components

Element UAHS Considerations

boolean-factor ::= [NOT] boolean-primary

boolean-primary ::= predicate

boolean-term ::= boolean-factor [AND boolean-term]

character ::= {any ASCII value from 0x20 to 0x7E}

character-string-literal ::= '{character}…'

column-identifier ::= user-defined-name

column-name ::= [table-name.]column-identifier UAHS variation:column-name ::= [table-name.|correlation-name.]column-identifier

comparison-operator ::= < | > | <= | >= | = | <> | !=

comparison-predicate ::= expression comparison-operator expression

correlation-name ::= user-defined-name UAHS variation

digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

expression ::= term | expression {+|-} term +|- not supported

factor ::= [+|-]primary +|- not supported

letter ::= lower-case-letter | upper-case-letter accepts lower-case but is case-insensitive

like-predicate ::= expression [NOT] LIKE character-string-literal(In a character-string-literal, the percent character(%) matches 0 or more of any character; theunderscore character (_) matches 1 character.)

expression must specify a column name



literal ::= character-string-literal

lower-case-letter ::= a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | y | z

null-predicate ::= column-name IS {NOT} NULL

order-by-clause ::= ORDER BY sort-specification [, sort-specification]

limited to one occurrence of sort-specification

Predicate ::= comparison-predicate | like-predicate | null-predicate

primary ::= column-name | literal | (expression) parentheses not supported in the select-list

search-condition ::= boolean-term [OR search-condition]

select-list ::= *|select-sublist [,select-sublist]… Limited to 255 occurrences of select-sublist whenALL or no modifier is usedLimited to one occurrence of select-sublist when DISTINCT modifier is used.

select-sublist ::= expression UAHS variation:select-sublist ::= expression | table-name.*

sort-specification ::= {unsigned-integer | column-name } [ASC | DESC]

table-identifier ::= user-defined-name

table-reference ::= table-name UAHS variation:table-reference ::= table-name [correlation-name]

table-reference-list ::= table-reference [,table-reference]… Limited to three occurrences of table-reference

table-name ::= table-identifier UAHS variation:table-name ::= [db-name.]table-identifier

term ::= factor | term {*|/} factor *|/ not supported

unsigned-integer ::= {digit}…

upper-case-letter ::= A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

user-defined-name ::= letter[digit | letter | _]…

Element UAHS Considerations



UAHS SELECT Statement Extensions

As stated previously, UAHS allows variations on some items in the minimum SQL grammar, so item references can follow the same conventions as are used in other popular databases. All deviations are optional; the standard elements are all still supported as specified. The supported variations are given next to each standard element in Table 9-1 (above) and the details follow.

Item Names

UAHS table names can be qualified by the database name as in the following format:

[db-name].table-name

Such qualification can also be used with columns:

[db-name.][table-name.]column-name

The most common use of qualification is to use a database that is different from the configured default. As an example, the following is legal syntax for UAHS:

SELECT SSN, EMP_FNAME, EMP_LNAME FROM PAYROLL.EMPLOYEE

Here, the table name is qualified by the database name, PAYROLL.

Correlation Names

UAHS SELECT statements allow correlation names for tables. A correlation name is an alias for a table, supplied after the actual table name in the table reference list (i.e., the FROM clause). Column names in the select list can then be prefixed by the correlation name. The most common use for correlation names is joining a table with itself.

As an example, the following statement uses correlation names to select pairs of employees with the same first name:

SELECT X.EMP_SSN, Y.EMP_SSN FROM EMPLOYEE X, EMPLOYEE Y WHERE X.EMP_FNAME = Y.EMP_FNAME AND NOT X.EMP_SSN = Y.EMP_SSN

Here, X and Y are both correlation names for the table EMPLOYEE.



Select List Shorthand

UAHS SELECT statements can use the following syntax in the select list as shorthand notation to specify all columns of the table in the order they were defined:

table-name.*

For example,

SELECT EMPLOYEE.*, DEP_FNAME, DEP_DOB FROM EMPLOYEE, DEPENDANT WHERE EMP_ID = DEP_OWNER_ID

will produce a result set comprised of all columns of the EMPLOYEE table, followed by the columns DEP_FNAME and DEP_DOB.

UAHS SELECT Statement Limitations

The following list generalizes the restrictions imposed by UAHS on SELECT syntax and functionality, with respect to popular relational systems, that support more comprehensive SQL definitions (ANSI 89/92, ODBC Core, etc.).

Client users and programmers can use this list to compare UAHS with familiar tools and languages. For example, if you already use UARS (the UniAccess Relational Server for RDMS 2200) and/or RDMS 2200 (the OS 2200 relational database system) you can see which language features of RDMS SQL are not available with UAHS. [The complete RDMS syntax is documented in the Unisys OS 2200 Relational Data Management System (RDMS 2200) SQL Programming Reference Manual.]

• SELECT is the only SQL verb supported.

• A select list is limited to 255 items, columns and literals combined.

• SELECT list items cannot be aliased using AS.

• A table reference list is limited to three items, limiting join operations to three tables.

• The arithmetic operators +, - , * and / are not supported.



• Parenthesis () are not permitted in the SELECT clause, they are allowed in the WHERE clause.

• Single quotes (apostrophes) are used to delineate literal strings; double quotes are not permitted.

• Delimited (quoted) identifiers are not supported.

• DISTINCT can be used only with a single item.

• Only the three predicates given by the ODBC Minimum SQL Grammar are supported: Comparison, LIKE, and NULL. Unsupported predicates include: BETWEEN, IN, and EXISTS

• The ESCAPE clause of the LIKE predicate is not supported.

• The GROUP BY and HAVING clauses are not supported.

• ORDER BY is limited to a single item, allowing sorting on a single column only.

• Built-in functions are not available. These include:— aggregate (MIN, MAX, etc.)— date/time (DATE, TIME, etc.)— mathematical (SQRT, RAND, etc.)— string (TRIM, SUBSTR, etc.)— system (USER, et. al.)

• Subqueries and the quantifiers ANY/SOME and ALL are not supported.

• The set UNION operation is not supported.

Relational Mapping Implications As a UAHS user, you are operating with a relational view of a hierarchical database. The way DMS items are represented in the UAHS Meta Database has several implications for the UAHS client. Mapping governs the items available to you, the results of your SELECT requests, the way DMS records will be obtained in response to your requests, and the performance of requests as well.



A user or programmer should be aware of specific aspects of the unique, mapped environment that are presented in the topics that follow.

Repository Contents

In the UAHS environment, an administrator decides which DMS items are included in the UAHS Meta Database and the presentation of those items. The process can be likened to views in traditional databases, where view definitions are made up of columns from one or more related base tables—UAHS tables are made up of items from one or more related DMS records.

The administrator responsible for DMS mapping controls:

• Records included as tables in a UAHS database

• Record fields included as table columns

• Names of the databases, tables and columns.

If you don’t see items you need in your UAHS database(s), you may need to review the DMS mappings with your administrator.

DMS Set Mapping

UAHS tables are mappings of one or more DMS records that have a set relationship. Single-record tables are straightforward – a UAHS table will contain one row for each DMS record. The subsections that follow explain behavior of tables that are defined from more than one DMS record using set relationships.

Set mapping is discussed in greater detail in Chapter 14 of the UniAccess for OS 2200 System Administration Guide. There you will also find more detailed examples that illustrate the scenarios described here, including the underlying DMS definition for the example records and set relationships.



Multi-record Tables

The majority of tables you will work with for UAHS will be multi-record. Multi-record tables are those that project DMS set hierarchies into a relational form. A UAHS table may span up to five hierarchical levels, or generations. These hierarchical levels will relate directly to each other as parent, child, grandchild.

When you select rows from tables comprised of multiple DMS records, columns that are mapped from an owner record are repeated with columns mapped from it’s member record. Repetition proceeds down each level of the hierarchy that is mapped.

Root Record Selection

The administrator selects the record type (superior or subordinate) that will be considered the root of a multi-record table. The root record designates the starting point for the DMS access path used by UAHS. For a UAHS user, the root record can have bearing on the table’s contents (rows) and performance of queries against the table.

When the most superior record is selected for the root, the table will include rows for every record in the hierarchy, including owners of empty sets, as illustrated in Figure 9-2.

Figure 9-2: Superior Record Root Selection

Row OFF_NAME EMP_NAME DEP_NAME

1 Accounting Johnson Carol

2 Accounting Johnson Stanley

3 Accounting Watson NULL

4 Engineering Graves Shirley

5 Engineering Yates Elizabeth

6 Engineering Keating NULL

7 Marketing Matthews NULL

8 Marketing Finney Mary

9 Sales Blimps NULL NULL

10 Sales Jets Rich Anne



Notice the NULL values in the EMP_NAME and DEP_NAME columns above. Because the superior OFFICE-REC is the root of this table, NULLs appear for empty instances of the OFF-EMP-SET and EMP-DEP-SET. This can be an unnecessary processing burden if a client is interested only member-based information.

When the most subordinate record is selected for the root, the table will only contain rows for each subordinate record—that is, owners of empty sets are not included—as illustrated in Figure 9-3. The exclusion proceeds up the hierarchy spanned by the table.

Figure 9-3: Subordinate Record Root Selection

Notice that several employees and the office Sales Blimps from the previous example are missing from this table. Because the subordinate DEPENDANT-REC is the root of the table, only owners of those records are included here. Effectively, any rows that contained NULL columns in the superior root version are excluded from the subordinate root version.

Nulls

In relational databases, a null value exists when a column does not have a value assigned to it. In the UAHS environment, null values are associated with empty DMS sets. This occurs in two situations.

• The first is when a UAHS table is defined with a superior root record (owner-driven, top-down) mapping, and there are no member records for an instance of the owner record. In this case, the columns mapped from the member fields will be null. (See Figure 9-3 above.)

Row OFF_NAME EMP_NAME DEP_NAME

1 Accounting Johnson Carol

2 Accounting Johnson Stanley

3 Engineering Graves Shirley

4 Engineering Yates Elizabeth

5 Marketing Finney Mary

6 Sales Jets Rich Anne



• The second is when a UAHS table is defined with a subordinate root record (member-driven, bottom-up) mapping of a manual set. (Manual sets are subordinate records that can exist without owners.) If a given instance of the member record is unowned, the columns mapped from the owner fields will be null (see Figure 9-4).

Figure 9-4: Subordinate Record Root Selection of Manual Sets

Notice that NULL is returned in the EMP-LNAME column where a task has not been assigned to an employee .

The behavior of null columns in SELECT statements is as in other relational systems, as follows:

• Nulls are considered to be less than non-nulls when sorting rows.

• Nulls are considered to be equal to each other for purposes of determining distinct rows.

• The result of a comparison between a non-null and a null is UNKNOWN. It is neither TRUE nor FALSE.

• The IS [NOT] NULL predicate should be used to test for a NULL value (condition)

Row EMP_LNAME TASK_NAME

1 Graves Analysis

2 Graves Coding

3 Finney Presentation

4 Johnson Accounting

5 NULL Clerical

6 NULL Cleaning



Record Retrieval Methods

The most efficient way to retrieve DMS data is to use record keys. In mapping records to tables, your administrator will have included columns mapped from the DMS record keys. You should take advantage of those keys to optimize data access. UAHS will use the keys whenever values for them are available. You should provide values for key data items in your queries whenever possible. If you are an ODBC user, the catalog function SQLSpecialColumns can be used to obtain the key columns for a table.

If you don’t use key values, UAHS may have to search entire DMS data areas to obtain records. With large volumes of data, this can be very slow and inefficient. Therefore, UniAccess provides methods of restricting such area searches. These are configuration settings in a UniAccess ODBC Driver data source and in the host system configuration.

You can configure your ODBC data source to allow or disallow area searches, and your system administrator can do the same at the user and/or service level. The administrator can also specify that the host configuration takes precedence over any client settings, making data source settings ineffectual.

If you attempt access and receive the following message,

Area search capability needed to access database.

either your data source doesn’t allow area searches or your UniAccess administrator has disallowed them. You should re-submit the statement and specify key values, or request the area search capability, if needed. (For more information see page 5-31, or Chapter 14 of the UniAccess for OS 2200 System Administration Guide.)

Sorting

UAHS is a transaction program, not intended for sorting large volumes of data. For large volumes, we discourage using ORDER BY and encourage that the sort be performed by the client application.

Even though the ORDER BY syntax for UAHS is limited to a single column, you should still use caution when using it, especially if your request has the potential to return a large volume of data.



Also, be aware that there are situations where an ORDER BY clause is unnecessary because the data will be retrieved from DMS in the desired order. Such is the case for the most significant portion of an index sequential record key for a single-area record.

As an example, assume a DMS record, OFFICE-REC, defined as Index Sequential using the item OFF-NAME as an ascending key. Assume UAHS mappings OFFICE_TABLE and OFF_NAME for the respective table and column names. Then the following statements will yield the same results:

SELECT * FROM OFFICE_TABLESELECT * FROM OFFICE_TABLE ORDER BY OFF_NAME

You needn’t specify ORDER BY because the records are already in the desired sequence. Although the sort routine will detect the sequencing, there is still overhead associated with invoking the routine. Eliminating the ORDER BY clause will yield better performance.

Your administrator can supply you with the default sequence of UAHS table rows when they exist.

UAHS Debug Information

UAHS provides a debug facility to assist in determining mapping problems. The debug facility compliments the Language Trace File (available to the System Administrator through UACS CONS commands). Whereas the Language Trace File contains all SQL passed to the language transaction, the UAHS debug facility provides information about how the SQL is handled. This information includes the results of parsing the SQL command and the path used to access the DMS data.

The UAHS command SET DEBUG {ON | OFF} controls the debug facility. In addition, ODBC clients may configure the UAHS debug facility from the UADriver Setup dialog. Setting the option Activate Host Debugging to YES will enable UAHS debugging by default. The UAHS debug trace output will appear in the UAHS transaction print file.

The default debug setting for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER DEBUG setting (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).



DMS 2200 Datatype SupportDMS 2200 data items (record fields) are defined with item description entries in the Record Section of the schema Data Definition Language (DDL). The entries use COBOL-style language elements to specify item attributes. The type of data that is stored in an item—that is, the item’s datatype—is governed by two clauses of an item description:

• The PICTURE clause specifies the size, type (alphabetic, numeric, alphanumeric, long character, or exact binary), and editing requirements of an item.

• The USAGE clause specifies the representation of an item in storage. The USAGE clause can also define fixed format items, making a PICTURE clause unnecessary. An example is USAGE COMP-2, which defines a double-precision floating-point binary numeric item of 72 bits.

This section describes UAHS’s support for the different datatypes in a DMS schema, as defined by PICTURE and USAGE in the schema DDL. It also gives the compatible client datatypes for the supported DMS types.

NoteUAHS reads only DMS schema information for obtaining item descriptions. No subschema attributes are available to UAHS.

Client and DMS 2200 Datatype Correspondence

Table 9-2 gives the types of data that can be defined in a DMS schema, and the DDL PICTURE and USAGE clauses that determine each type. UAHS support for each datatype is indicated. For supported datatypes, the corresponding datatypes in each of the three client APIs that can be used with UAHS are given. These are the datatypes the client application will see when the DMS item is returned to the client by UAHS.



Table 9-2: Supported DMS 2200 Datatypes and Client Correspondences

DMS 2200 Datatype

DDL Item Description Client Application Datatypes

PICTURE USAGE ODBC SQL Client-Library DB-Library


A(y)X(y)

DISPLAY SQL_CHAR CS_VARCHAR DBVARYCHAR

Numeric 9(n)9(n)V9(m)S9(n)S9(n)V9(m)1

DISPLAYCOMP2,3

SQL_DECIMAL CS_VARCHAR DBVARYCHAR


n/a COMP-1 SQL_REAL4 CS_REAL4 DBREAL4


n/a COMP-2 SQL_DOUBLE4 CS_FLOAT4 DBFLT84



DMS Date/Time n/a DATE,TIME,DATE-TIME


Exact Binary 1(b) (see note 2) unsupported

Long Character X(y) DISPLAY-2 unsupported

Alphanumeric Edited,Numeric Edited

contains editing symbols

DISPLAY unsupported

Fielddata any DISPLAY-1COMP-4

unsupported

1 UAHS does not support the PICTURE symbol P for assumed decimal scaling.2 UAHS does not support archaic notation for COMP usage, the PICTURE symbol H.3 DMS DDL applies the ASCII COBOL interpretations of the USAGE clause. The UCS equivalent for

COMP is BINARY; exact binary items have USAGE BINARY-1 in UCS COBOL. 4 When floating point numbers are converted between OS 2200 architectures and 8-bit-byte architectures, some precision will be lost (see page 4-5 for more information).

See the note following the table for a definition of symbols used in this table.



Note The symbols in Table 9-2 are defined as follows:

A = Only alphabetic (no numeric or special) characters and spaces are allowed in the field. X = Any characters are allowed in the field. 9 = Only numeric characters are allowed in the field. y = The character length of the field. n = The number of digits to the left of the decimal. m = The number of digits to the right of the decimal. V = An assumed decimal position. S = The field is signed, that is, negative values are allowed.

Supported DMS 2200 Datatypes

This section provides details on the supported DMS 2200 datatypes given in Table 9-2. Each type of item is discussed with respect to the type of data stored in the DMS database, the client datatype assigned by UAHS for the item, and the details for formatting the item for return to the client application.

Alphabetic and Alphanumeric. These are both 9-bit ASCII character representations that store characters left-justified and space-filled. The alphabetic type can contain only letters and spaces; the alphanumeric type can contain any ASCII characters. These are equivalent types for UAHS. Both are returned to the client as SQL_CHAR.

UAHS imposes a limit of 255 characters per column. Longer items will either return an error or be truncated before being returned to the client, depending on how the system administrator has configured the COMSRV CHARTRUN of the UniAccess Configuration File.

Numeric. These are numeric types, using either 9-bit ASCII digits (USAGE DISPLAY) or fixed-point binary (USAGE COMP) representations. ASCII representations are stored decimal-aligned and zero-padded. Binary representations use from 1 to 7 9-bit bytes, depending on the number of digits defined by the PIC clause. Both DISPLAY and COMP definitions can store numbers with up to 18 digit positions. (Any assumed sign or decimal position is not counted as a digit position.)



Single-precision floating-point. USAGE COMP-1 defines an approximate numeric binary field that can store values to +/- 1.70141182E+38. COMP-1 fields are returned as SQL_REAL.

Double-precision floating-point. USAGE COMP-2 defines an approximate numeric binary field that can store values to +/- 8.988465674311579549E+307. COMP-2 fields are returned as SQL_DOUBLE.

DMS Key items. DATABASE-KEY and AREA-KEY are used to allocate items for use by the DMP in a DMS record. Both allocate a one-word item, equivalent to the explicit item description, PIC 9(10) COMP. (An area key is sub-defined before it is used.) This datatype is processed by UAHS the same as the Numeric type (see above), and returned to the client as SQL_DECIMAL.

DMS DATE/TIME fields. In the schema DLL, the USAGEs DATE, TIME and DATE-TIME are used as a shortcut for allocating fields to hold date and time values. These items are equivalent to the following explicit item descriptions:

DATE PIC 9(8)TIME PIC 9(8)DATE-TIME PIC 9(16)

Since the resultant items are numeric with USAGE DISPLAY, UAHS, treats them as such, returning SQL_DECIMAL datatypes to the client for these items.

Attributes of Supported DMS Items

Attributes of each of the supported DMS datatypes are given in Table 9-3. This information can be useful to a client application for defining and allocating local variables for the returned DMS data, and for defining arguments used in data access function calls. This is the same information returned from the ODBC function SQLColumns. The attributes given in Table 9-3—length, precision, and scale—are defined below.

Length

Length is an attribute that applies to all datatypes, both numeric and non-numeric. It is the maximum number of bytes of data returned to the application. Note the following points:



• For character data, the length does not include the null termination byte.

• Length can be different than the number of bytes required to store the data in the database.

Precision

Precision specifications also apply to both numeric and non-numeric datatypes.

• For character datatypes, precision refers to either the actual or maximum number of characters in the item.

• For all other datatypes, precision refers to the maximum number of digits used by the item.

Scale

Scale indicates how many digits there are to the right of the decimal point. Scale applies only to some numeric datatypes.

For DMS items, scale is the number of digits defined to the right of the PICTURE symbol ‘V’. For example, the scale of PIC S9(8)V9(2) is 2.



Table 9-3: Precision, Scale, and Length of DMS 2200 Datatypes

DMS 2200 Datatype

DDL Item Description Attributes

PICTURE USAGE Length Precision Scale


A(y)X(y)

DISPLAY n bytes n n/a

Numeric 9(n)9(n)V9(m)S9(n)S9(n)V9(m)

DISPLAY,COMP

n bytesn + m + 1 bytesn + 1n + m + 2 bytes

nn + mnn + m

0m0m


n/a COMP-1 4 8 n/a


n/a COMP-2 8 18 n/a


10 10 0

DMS Date/Time n/a DATETIMEDATE-TIME

8816

8816

000


10 UAHS Commands

10 UAHS Commands

This chapter describes the operational commands available through the UniAccess Hierarchical Service (UAHS). The information in this chapter is most relevant to Open Client users of UAHS.

Topics Page

UAHS Commands 10-2

SET AREASEARCH 10-4

SET DEBUG 10-5

SET DISTTRAN 10-6

SET ROWLIMIT 10-7

SET SPACETRIM 10-8

SET STRIPCTRL 10-9

SET TRANSACTIVE 10-10

SET TRANSOPTION 10-11

UAHSINFO 10-12



UAHS CommandsThe following commands are available through UAHS. Also referenced as SET commands, these commands don’t operate on DMS 2200, but control the operating characteristics of the UAHS transaction. For more information, see the description of each command that follows the table.

Table 10-1: UAHS Commands

Most UAHS commands have a related UADriver Setup command (and a connection string attribute), and most are controlled by UniAccess Configuration File settings (see Table 10-2). The Configuration File settings establish default values for the user and indicate whether or not the user may override these default values by issuing UAHS commands. The result set for the UAHSINFO command indicates the current value of each attribute and whether or not the default value in the Configuration File may be overridden.

UAHS COMMAND Description

SET AREASEARCH Causes UAHS to perform searches when key data is not provided.

SET DEBUG Causes UAHS to generate debug information in its print file.

SET DISTTRAN Defines capability for the client to participate in distributed transactions.

SET ROWLIMIT Limits the number of rows that will be returned by a SELECT command.

SET SPACETRIM Causes control character columns to be returned as variable length fields with trailing spaces trimmed.

SET STRIPCTRL Causes control characters to be removed from literal strings.

SET TRANSACTIVE Defines whether or not user-supplied translation routines should be invoked by UAHS.

SET TRANSOPTION Provides a parameter that will be passed by UAHS to the user-supplied translation routines.

UAHSINFO Returns information about the UAHS operating environment.


UAHS Commands 10-3

Table 10-2: UAHS Command Relationships

UARS Command



Parameter

UARSINFO Attribute

SET AREASEARCH

Perform area search HIERSRV/UAUSER AREASEARCH

UAHS_AREASEARCH (15)

SET DEBUG Activate host debugging HIERSRV/UAUSER DEBUG

UAHS_DEBUG (16)

SET DISTTRAN Support Distributed Transactions

UAUSER DISTTRAN DISTTRAN (18)

SET ROWLIMIT Rowlimit HIERSRV/UAUSER ROWLIMIT

UAHS_ROWLIMIT (8)

SET SPACETRIM Remove trailing spaces from character columns

HIERSRV/UAUSER SPACETRIM

UAHS_SPACETRIM (7)

SET STRIPCTRL Remove control characters from literal strings

HIERSRV/UAUSER STRIPCTRL

UAHS_STRIPCTRL (17)

SET TRANSACTIVE

Activate Translation HIERSRV/UAUSER TRANSACTIVEH

UAHS_TRANSACTIVE (19)

SET TRANSOPTION

Translation Option HIERSRV/UAUSER TRANSOPTIONH

UAHS_TRANSOPTION (20)

UAHSINFO none none none


10-4 SET AREASEARCH UniAccess for OS 2200 Client Guide


SET AREASEARCH

Function

This command indicates whether or not the UAHS transaction should perform searches when key data is not provided.

Syntax

SET AREASEARCH {ON | OFF}

Comments

• Every area associated with the selected record will be scanned sequentially.

• These searches may read the entire DMS database and, as a result, host performance may suffer.

• The default value for the user and the ability to override this value are determined by the HIERSRV/UAUSER AREASEARCH setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

NoteSelecting this value may have a severe performance impact on the host environment.

Results

The SET AREASEARCH command does not return a result set.


UAHS Commands SET DEBUG 10-5

SET DEBUG

Function

This command indicates that the UAHS transaction should generate debug information in its print file.

Syntax

SET DEBUG {ON | OFF}

Comments

• This command should only be used to assist in debugging SELECT command problems.

• The debug trace output will be in the UAHS transaction print file. It provides information about the results of parsing the SQL command as well as the path used to access the DMS data.

• Debug tracing increases system overhead.

• The default value for the user and the ability to override this value are determined by the HIERSRV/UAUSER DEBUG setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET DEBUG command does not return a result set.

10-6 SET DISTRAN UniAccess for OS 2200 Client Guide


SET DISTTRAN

Function

This command defines the capability for the client to participate in distributed transactions.

Syntax

SET DISTTRAN {ON | OFF}

Comments

• If ON is specified, the client application may participate in distributed transactions.

If OFF is specified, the client application may not participate in distributed transactions.

NoteCurrently the UAHS transaction may not participate in distributed transactions.

• For more information about the use of distributed transactions, see Chapter 13.

• The default value for the user and the ability to override this value are determined by the UAUSER DISTTRAN setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Results

The SET DISTTRAN command does not return a result set.


UAHS Commands SET ROWLIMIT 10-7

SET ROWLIMIT

Function

This command limits the number of rows that will be returned by a SELECT command.

Syntax

SET ROWLIMIT {0-2147483647}

Comments

• The valid range is from 0 to 2147483647 where 0 indicates that all rows should be returned.

• If the number of rows generated by a SELECT request exceeds the ROWLIMIT defined value, UAHS stops generating rows.

• The default rowlimit for the user and the ability to override this value are determined by the HIERSRV/UAUSER ROWLIMIT setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET ROWLIMIT command does not return a result set.

10-8 SET SPACETRIM UniAccess for OS 2200 Client Guide


SET SPACETRIM

Function

This command causes character columns to be returned as variable length fields with trailing spaces trimmed.

Syntax

SET SPACETRIM {ON | OFF}

Comments

• ON indicates that trailing spaces will be truncated.

OFF indicates that UAHS will not trim trailing spaces from character fields before returning them to the user.

• The default value for the user and the ability to override this value are determined by the HIERSRV/UAUSER SPACETRIM setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The set SPACETRIM command does not return a result set.


UAHS Commands SET STRIPCTRL 10-9

SET STRIPCTRL

Function

This command causes control characters (ASCII value less than 32) to be removed from literal strings before they are submitted to DMS for processing.

Syntax

SET STRIPCTRL {ON | OFF}

Comments

• If ON is specified, UAHS will convert all control characters (values ranging from 0x01 to 0x1F) to spaces (value 0x20) regardless of whether or not those control characters are part of a character literal.

If OFF is specified, UAHS will only convert control characters that are not part of a character literal to spaces.

• The default value for the user and the ability to override this value are determined by the HIERSRV/UAUSER STRIPCTRL setting in the UniAccess Configuration File (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Results

The SET STRIPCTRL command does not return a result set.

10-10 SET TRANSACTIVE UniAccess for OS 2200 Client Guide


SET TRANSACTIVE

Function

This command defines whether or not the UAHS user-supplied translation routines should be invoked.

Syntax

SET TRANSACTIVE {ON | OFF}

Comments

• If ON is specified, UARS will call the user-supplied translation routines.

If OFF is specified, UARS will not call user-supplied translation routines.

NoteTranslation is dependent upon the site-supplied translation routine. If no translation routine is provided, this option will not provide any translation.

• See Chapter 12 in the UniAccess for OS 2200 System Administration Guide for information on creating and using the translation routines.

• The default value for the user and the ability to override this value are determined by the HIERSRV/UAUSER TRANSACTIVEH setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Results

The SET TRANSACTIVE command does not return a result set.


UAHS Commands SET TRANSOPTION 10-11

SET TRANSOPTION

Function

This command provides a parameter that will be passed by UAHS to the user-supplied translation routines if the SET TRANSACTION value is YES.

Syntax

SET TRANSOPTION { NONE | LETSJ | SJIS}

Comments

• The SET TRANSOPTION command passes the value to the user-supplied translation routine when called by UAHS.

— NONE indicates that the value ua_no_xlate should be passed to the user-supplied translation routine if SET TRANSACTIVE is YES.

— LETSJ indicates that the value ua_letsj should be passed to the user-supplied translation routine if SET TRANSACTIVE is YES.

— SJIS indicates that the value ua_sjis should be passed to the user-supplied transaction routine if SET TRANSACTIVE is YES.

• UAHS performs no special handling for the LETSJ and SJIS options and, therefore, they become effective immediately and will be passed to the user-supplied translation routines as they are changed dynamically.

• This parameter is only relevant when SET TRANSOPTION is YES.

• The default value for the user and the ability to override this value are determined by the HIERSRV/UAUSER TRANSOPTIONH setting in the UniAccess Configuration File. (See Chapter 16 in the UniAccess for OS 2200 System Administration Guide.)

Results

The SET TRANSOPTION command does not return a result set.

10-12 UAHSINFO UniAccess for OS 2200 Client Guide


UAHSINFO

Function

This command returns general information about DMS 2200, UAHS, and other UniAccess components in a row/column format.

Syntax

UAHSINFO

Comments

UAHSINFO returns the list of attributes and their values described in Table 10-3.

Table 10-3: Information Returned by UAHSINFO


1 HOST_TDS_LEVEL TDS level supported by UAHS.



4 UAHS_LEVEL UniAccess Hierarchical Service level.


6 UAHS_WAITTIME UAHS self-initializing wait time in seconds.

7 UAHS_SPACETRIM UAHS character field space trim characteristics.YES indicates that spacetrim is active. NO means that spacetrim is inactive.

8 UAHS_ROWLIMIT UAHS return row limit. Zero indicates no limit.

9 DEFAULT_SCHEMA Default DMS 2200 schema for this connection.

10 CURRENT_SCHEMA Current DMS 2200 schema for this connection.





UAHS Commands UAHSINFO 10-13

14 CHARACTER_TRUNCATION Character string truncation indicator. YES indicates that character strings longer than 255

characters should be truncated. NO indicates that character strings longer than 255

will generate an error.

15 UAHS_AREASEARCH Area search indicator. YES indicates that when key DMS information is not

provided in the SELECT WHERE clause, every area associated with the selected record will be read sequentially.

NO indicates that when DMS key information is not provided in the SELECT WHERE clause, an error will be returned.

16 UAHS_DEBUG Debug indicator. Assists in debugging SELECT command problems.

YES indicates that the UAHS transaction will generate debug information in its print file.

NO indicates that UAHS will not generate debug information.

17 UAHS_STRIPCTRL Control character pre-processing indicator.YES indicates that all control characters will be

converted to spaces.NO indicates that only control characters that are not

part of a literal string will be converted.

18 DISTTRAN UAHS distributed transaction capability indicator.YES indicates that distributed transactions are

allowed.NO indicates that distributed transactions are not

allowed.NOTE: Currently the UAHS transaction may not

participate in distributed transactions.

19 UAHS_TRANSACTIVE UAHS user translation capability indicator.YES indicates that user-supplied translation routines

should be called.NO indicates that user-supplied translation routines

should not be called.


10-14 UAHSINFO UniAccess for OS 2200 Client Guide


Results

The Table 10-4 describes the result set generated by the UAHSINFO command.

Table 10-4: Result Set for UAHSINFO

20 UAHS_TRANSOPTION UAHS translation option. This value is passed to the user-supplied translation routine when UAHS_TRANSACTIVE is YES.

NONE indicates that the value ua_no_xlate should be passed to the user-supplied translation routine if UAHS_TRANSACTIVE is YES.

LETSJ indicates that the value ua_letsj should be passed to the user-supplied translation routine if UAHS_TRANSACTIVE is YES.

SJIS indicates that the value ua_sjis should be passed to the user-supplied transaction routine if UAHS_TRANSACTIVE is YES.

21 UAMM_BLOCKSIZE The size in bytes of the configured UACS UAMM fixed memory blocks. UACS is capable of setting the value of the UAMM BLOCKSIZE configuration parameter to 512, 1024, 2048, or 4096 bytes. The CS_PACKETSIZE should normally match this value.


attribute_id int Numeric representation of the attribute whose value is returned in this row. This is one of the attributes listed in Table 10-3.

attribute_name varchar(30) Name of the attribute.

attribute_value varchar(80) Current value of the attribute.




UAHS Commands UAHSINFO 10-15

Example

The following is an example of the UAHSINFO result set.

1, "HOST_TDS_LEVEL", "4.2", 02, "HOST_MACHINE_TYPE", "2200/500", 03, "HOST_EXEC_LEVEL", "44R4B", 04, "UAHS_LEVEL", "10R3-0", 05, "UAFG_LEVEL", "10R3-0", 06, "UAHS_WAITTIME", "30", 07, "UAHS_SPACETRIM", "NO", 18, "UAHS_ROWLIMIT", "0", 19, "DEFAULT_SCHEMA", "ECOMPE", 010, "CURRENT_SCHEMA", "ECOMPE", 111, "CONNECTION_PID", "1000", 012, "CLIENT_INTR_ADDR", "192.168.1.128", 013, "CLIENT_INTR_PORT", "2714", 014, "CHARACTER_TRUNCATION", "YES", 015, "UAHS_AREASEARCH", "NO", 116, "UAHS_DEBUG", "NO", 117, "UAHS_STRIPCTRL", "NO", 118, "DISTTRAN", "YES", 119, "UAHS_TRANSACTIVE", "YES", 120, "UAHS_TRANSOPTION", "NONE", 121, "UAMM_BLOCKSIZE", "4096", 0


11 UAHS Catalog RPCs

11 UAHS Catalog RPCs

This chapter explains the function and use of Catalog RPCs for the UniAccess Hierarchical Service (UAHS). The reference section describes each supported Catalog RPC. The reference section describes each supported Catalog RPC. The information in this chapter is most relevant to Open Client users who make SQL requests against DMS 2200 data using UAHS.

Topics Page

Overview of UAHS Catalog RPCs 11-2

Using Catalog RPCs 11-2

Coding Instructions 11-2

Datatypes 11-4

UAHS Catalog RPC Descriptions 11-5

sp_columns 11-6

sp_databases 11-10

sp_datatype_info 11-11

sp_special_columns 11-15

sp_statistics 11-18

sp_tables 11-22



Overview of UAHS Catalog RPCsCatalog Remote Procedure Calls (RPCs) are the component of the UniAccess Hierarchical Service (UAHS) that retrieve meta information regarding the DMS 2200 schema. This information enables the UniAccess ODBC Driver to present an ODBC compliant view of DMS 2200 to the client, even though DMS is not an ODBC-compliant database. The UAHS Catalog RPCs are compatible with the catalog interface for the Open Database Connectivity (ODBC) Application Programming Interface (API).

From a client perspective, the Catalog RPCs are simply a set of remote procedure calls that access DMS 2200 meta database information. Actually, UAHS uses the Catalog RPCs to extract information from the UAHS Meta Database. The UAHS Meta Database is a TIP file created and maintained by the system administrator using UniAccess System utilities. The UAHS Meta Database contains a mapping of DMS schema entities to relational entities such as UAHS tables and databases. (For information on the UAHS Meta Database, see page 9-4; for information on UAHS Catalog RPC processing, see page 9-6.)

Using Catalog RPCsCatalog RPCs are often used implicitly by client applications on behalf of the user, but these requests can also be coded explicitly.

Coding Instructions

General coding information for all RPCs is included in this section. For the syntax of a particular RPC, see the UAHS Catalog RPC Descriptions section that begins on page 11-5. For compatibility reasons, UAHS Catalog request parameters are identical to the UARS Catalog request parameters.

Parameters

Catalog RPCs have both optional and required parameters. Required parameters must have values supplied; optional parameters default to predefined values.

ODBC applications. Parameters for Catalog RPCs are positional. All Catalog RPC parameters must be unnamed and passed in the order that corresponds to the Catalog RPC definition.


UAHS Catalog RPCs 11-3

Open Client applications. Parameters for Catalog RPCs are positional or named. The following rules apply:


• If named parameters are used, all parameters must be named parameters.


Coding Example

The example below shows the syntax for the sp_tables Catalog RPC followed by a coded sample of the RPC. The coded example uses ODBC syntax. This syntax would be used if the request was sent through UADriver.


{call sp_tables ('BUDGET1','%','%','"TABLE"')}

The sample request could use named parameters as follows:

{call sp_tables (@table_name='BUDGET1', @table_owner='%', @table_qualifier='%',

@table_type='"TABLE"')}

Note that the name for each parameter begins with the “@” symbol. This is a convention used on all parameters used by the Catalog RPCs.

Table Owner and Qualifier Parameters

In the UAHS Catalog RPCs, the terms table_owner and table_qualifier are used as follows:

• table_owner. Neither UAHS or DMS 2200 support the concept of table_owner. Unless otherwise noted, the table_owner parameter, if present, is ignored. Whenever table_owner is returned as part of a result set, it is always a NULL value.

• table_qualifier. Many UAHS Catalog RPCs have a table_qualifier parameter. The catalog support feature uses this parameter to identify the particular schema about which to return catalog information. If this parameter is omitted, the



catalog procedures return catalog information using the user’s default schema defined in the UniAccess Configuration File. The TABLEDEF utility is used to create table_qualifiers through the CREATE DATABASE command. UAHS databases and table_qualifiers are synonymous.

Wild Cards

The following wild cards can be used in parameters that allow wild cards:

• percent ( % ) — any string of zero or more characters

• underscore ( _ ) — any single character.

To use a wild card as its corresponding character, use the backslash (\) as an escape character. If these characters are used in parameters that do not allow wild cards, they are treated as literals. Table 11-1 shows some examples of wild cards and their use.

Table 11-1: Wild Card Examples

Datatypes

Two UAHS Catalog RPCs return datatype information: sp_columns and sp_special_columns. The datatype descriptions returned in the result sets of these RPCs include information about precision, scale, length, and radix. For information about ODBC datatype correspondences, see Table 9-2. For information about the precision, length, and scale of supported datatypes, see Table 9-3.

Sample String Matches

%A% All names that contain the letter “A“For example: A AT CAT

B__

(“B” followed by two underscores)

All names that are three characters long and begin with the letter “B”For example: BAL BCD

% All names

Total% All names beginning with “Total”


UAHS Catalog RPCs 11-5

UAHS Catalog RPC DescriptionsThe Catalog RPCs supported by the UniAccess Hierarchical Service are described in this section. The discussion of each RPC includes its function, syntax, and a description of result set formats. Table 11-2 provides a brief description of the Catalog RPCs and a quick reference to the syntax and basic coding of each.

Table 11-2: Quick Reference for Catalog RPCs


sp_columns @table_name, [@table_owner], [@table_qualifier], [@column_name]

YYNY


Column descriptions for a table

sp_databases no parameters

List of available databases

sp_datatype_info @data_type n/a int

Datatype descriptions

sp_special_columns @table_name, [@table_owner], [@table_qualifier], [@column_type], [@scope], [@nullable]

NNNn/an/an/a

varchar(30)varchar(12)varchar(30)intintint

Additional column information

sp_statistics @table_name, [@table_owner], [@table_qualifier}, [@unique], [@accuracy]

NNNn/an/a

varchar(30)varchar(12)varchar(30)intint

Statistics and/or indexes of one table


YYNN


List of tables



sp_columns

Function

Returns column descriptions for one or more columns in a relational table mapped to DMS 2200 data.

Syntax

sp_columns [table_name], [table_owner], [table_qualifier], [column_name]

Parameters

table_name [varchar(30)](I) The name(s) of one or more tables in a relational mapping whose column information is requested.


table_owner [varchar(12)]— This parameter is ignored.

table_qualifier [varchar(30)](I) The schema name of the object(s) as defined in the relational mapping. If you omit this value, information on object(s) in the user’s default schema is returned.


column_name [varchar(30)](I) The set of columns for which information is requested. This value represents the name of one or more columns in the named object(s). If you omit this value, information about all columns in the named object(s) is returned.



UAHS Catalog RPCs sp_columns 11-7

Comments

• You can use sp_columns to get descriptive information about one or more columns in one or more tables in the relational mapping.

This procedure does not return the contents of a column; it returns descriptive information about the column’s contents.

• The descriptive information includes:

— The name of the column and its associated datatype

— The integer code for the equivalent ODBC SQL datatype

— The precision, length, scale, and radix for the column

— Whether or not the column can be NULL.

• Table 9-2 lists supported datatypes and gives their ODBC SQL equivalents.

• You will be returned information for an object regardless of your authorization to access that object.

• If you request columns that do not exist, no rows are returned.

• For a discussion of precision, length, and scale, see page 6-24.

Results

sp_columns returns one row containing a description of each column in a table. Results are ordered by the following columns:

• TABLE_QUALIFIER• TABLE_OWNER• TABLE_NAME.



The columns contained in the sp_columns result set are described in Table 11-3.

Table 11-3: Result Set for sp_columns



TABLE_OWNER varchar (12) Always null.


not NULL




not NULL

The name of the column whose information is returned in this row.


DATA_TYPE smallint

not NULL

ODBC SQL datatype. Integer code for the ODBC SQL equivalent of this column’s datatype.1

TYPE_NAME varchar (32)

not NULL.

String representation of this column’s UAHS datatype.

PRECISION int The number of significant digits. For non- numeric datatypes, this column contains the length in bytes. 2


SCALE smallint For DECIMAL datatypes, the number of digits to the right of the decimal point. Otherwise, NULL 2

RADIX smallint The numeration system (base) used for this datatype. For NUMERIC, this value is 10. Otherwise, NULL.

1 Table 9-2 shows how ODBC datatypes correspond with supported DMS 2200, DB-Library, and Client-Library datatypes.



UAHS Catalog RPCs sp_columns 11-9

NULLABLE smallint The NULL value indicator. One of the following values:

0 (FALSE) Column cannot contain NULL values.

1 (TRUE) Column can contain NULL values.

REMARKS varchar (254) Always NULL.




11-10 sp_databases UniAccess for OS 2200 Client Guide


sp_databases

Function

Lists the relationally mapped databases available.

Syntax

sp_databases

Comments

You can use sp_databases to find out the names of the relational databases that are available.

Results

A list of the relationally mapped databases available to the client. The databases have been created by exercising the TABLEDEF utility and the CREATE DATABASE command. Results are ordered by DATABASE_NAME.


Table 11-4: Result Set for sp_databases


DATABASE_NAME varchar(30)

not NULL

Name of an available database.

DATABASE_SIZE int Size of the named database in kilobytes.

Always NULL.



UAHS Catalog RPCs sp_datatype_info 11-11

sp_datatype_info

Function

Returns information about the datatypes supported by UAHS.

Syntax

sp_datatype_info data_type

Parameters

data_type [int](I) The ODBC datatype about which information is requested. To get information about all datatypes, give this parameter a value of ALL_TYPES.

— This parameter is required.

Assign this parameter one of the following values.

Comments

• You can use sp_datatype_info to get descriptive information about one or more UAHS datatypes.

• Table 9-1 lists supported datatypes and their ODBC SQL equivalents.

ODBC Datatype UAHS Datatype Name

0 ALL_TYPES1

1 CHAR

3 DECIMAL

8 DOUBLE PRECISION

7 REAL

1 Not a UAHS datatype; this value returns information about all UAHS datatypes.



Results

sp_datatype_info returns a list of datatypes with information about each. Results are ordered by the columns DATA_TYPE and TYPE_NAME. The result set consists of the columns described in Table 11-5.

Table 11-5: Result Set for sp_datatype_info



not NULL

The name of the UAHS datatype that corresponds to the ODBC datatype in DATA_TYPE column.

DATA_TYPE smallint

not NULL

The ODBC datatype. This value is specified by the caller.

PRECISION int The maximum length allowed for this datatype. Table 9-2 gives the precision of each supported datatype.

LITERAL_PREFIX varchar(32) The character(s) used to mark the beginning of a literal. If a prefix is not used with this datatype, this column contains NULL values.

LITERAL_SUFFIX varchar(32) The character(s) used to mark the end of a literal. If a suffix is not used with this datatype, this column contains NULL values.

CREATE_PARAMS varchar(32) A description of the creation parameters required for this type.

For example, the creation parameters for UAHS DECIMAL type are “precision, scale”; for CHAR, “length”. If the datatype has no creation parameters, this column contains NULL values.

NULLABLE smallint

not NULL

The NULL value indicator. One of the following values: 0 SQL_NO_NULLS Datatype does not allow NULL values.

1 SQL_NULLABLE Datatype allows NULL values.


UAHS Catalog RPCs sp_datatype_info 11-13

CASE_SENSITIVE smallint

not NULL

Uppercase or lowercase sensitivity. Indicates whether or not this datatype distinguishes between uppercase and lowercase characters.

One of the following values: 0 (FALSE) Columns of this datatype are not case-sensitive.

1 (TRUE) Columns of this datatype are case-sensitive.

SEARCHABLE smallint

not NULL

The rule for using this datatype in WHERE clauses.

One of the following values: 0 SQL_UNSEARCHABLE Datatype cannot be used in a WHERE clause.

1 SQL_LIKE_ONLY Datatype can be used in a WHERE clause only with LIKE.

2 SQL_ALL_EXCEPT_LIKE Datatype can be used in a WHERE clause with any comparison operator except LIKE.

3 SQL_SEARCHABLE Datatype can be used in a WHERE clause with any comparison operator.

Defaults 2 (for all numeric datatypes) 3 (for all non-numeric datatypes)

UNSIGNED_ATTRIBUTE smallint Indicates whether or not this attribute is unsigned (that is, it does not accept signed numeric values).

One of the following values: 0 (FALSE) Columns of this datatype are signed.

1 (TRUE) Columns of this datatype are unsigned.

NULL This column is not numeric and has no sign.




MONEY smallint

not NULL

Indicates whether or not this is a money datatype.

One of the following values: 0 (FALSE) This is not a money datatype.

1 (TRUE) This is a money datatype.

NOTE: This field will always be 0.

AUTO_INCREMENT smallint Determines whether or not this datatype automatically increments. (Applies to numeric datatypes only).

One of the following values: 0 (FALSE) Columns of this datatype do not automatically increment. This is the case for all UAHS datatypes.

1 (TRUE) Columns of this datatype do increment automatically.

NULL This column is not numeric.

LOCAL_TYPE_NAME varchar(128) The localized version of the UAHS name of the datatype.

If localization is not supported, this field returns NULL values.

Currently, this field always returns NULL.

MINIMUM_SCALE smallint The minimum scale of the datatype in UAHS. If the datatype has a fixed scale, this value is the same as the MAXIMUM_SCALE value.


MAXIMUM_SCALE smallint The maximum scale of the datatype in UAHS.




UAHS Catalog RPCs sp_special_columns 11-15

sp_special_columns

Function

Returns information about the columns that make up a unique index of a single table.

Syntax

sp_special_columns table_name, [table_owner], [table_qualifier], [column_type], [scope], [nullable]

Parameters

table_name [varchar(30)](I) The name of the relationally mapped table whose index information is requested.



table_qualifier [varchar(30)](I) The schema name of the object(s) as defined to UAHS. If you omit this value, information on object(s) in the user’s default schema is returned.


column_type [int](I) The type of column whose information is requested. sp_special_columns returns information on only one column type: the unique index for a table. If the table has more than one unique index, sp_special_columns returns information about the primary key only.

1 SQL_BEST_ROWID Returns information on the columns that make up the first unique index for the named table.

11-16 sp_special_columns UniAccess for OS 2200 Client Guide


If you omit this parameter, the behavior of sp_special_column is the same as if you assigned it a 1.


scope [int](I) The minimum required scope. Currently, only one scope option can be specified:

If you omit this parameter, the behavior of sp_special_columns is the same as if you assigned it a 0. If you specify a number other than 0, no rows are returned.


nullable [int](I) Indicates whether or not columns that allow NULLs are allowed in the index information returned. Currently only one nullable option can be specified:

1 SQL_NULLABLE Columns that are nullable are permitted in the index information returned.

If you specify any value other than 1, no rows are returned.— This parameter is optional.

Comments

• sp_special_columns returns information about the columns that make up the primary key on the specified table.

• sp_special_columns does not return information about all unique indexes in a table; it returns information about the primary key only.

0 SQL_SCOPE_CURROW The row is guaranteed to be current only while positioned on that row.


UAHS Catalog RPCs sp_special_columns 11-17

Results

sp_special_columns returns information about the first unique index.

Table 11-6: Result Set for sp_special_columns


SCOPE smallint

not NULL

The actual scope of the row.

The following value: 0 SCOPE_CURROW


not NULL


DATA_TYPE smallint

not NULL

The ODBC datatype.1 The integer code for the ODBC SQL equivalent of this procedure column’s UAHS datatype.


not NULL

The name of the UAHS datatype that corresponds to the ODBC datatype in DATA_TYPE. 1



SCALE smallint For DECIMAL datatypes, the number of digits to the right of the decimal point. Otherwise, NULL2

PSEUDO_COLUMN smallint Indicates whether or not the column is a pseudo-column.

The following value: 1 SQL_PC_NOT_PSEUDO





sp_statistics

Function

Returns index information for a single relationally mapped table and the indexes associated with that table.

Syntax

sp_statistics table_name, [table_owner], [table_qualifier], [unique], [accuracy]

Parameters

table_name [varchar(30)](I) The name of the relationally mapped table whose index and statistical information is requested.





unique [int](I) The type of information to retrieve (unique/non-unique indicator). If this value is omitted, INDEX_ALL is used.



UAHS Catalog RPCs sp_statistics 11-19

Assign unique one of the following values:

accuracy [int](I) Leave blank.

— This parameter is ignored.

Comments

• sp_statistics returns index information about a single relationally mapped table.

• DMS 2200 does not support the concept of statistics. Therefore, UAHS processes the sp_statistics request by returning an empty result set (that is, only the header columns are returned).

Results

sp_statistics returns information abut the named table. Results are ordered by the following columns:

• NON_UNIQUE• TYPE• INDEX_QUALIFIER• INDEX_NAME• SEQ_IN_INDEX

The result set consists of the following columns described in Table 11-7.

0 INDEX_UNIQUE Return information on unique indexes only.

1 INDEX_ALL Return information on all indexes. This is the default value.



Table 11-7: Result Set for sp_statistics



TABLE_OWNER varchar(12) The owner of the table.


not NULL

The name of the table whose index or statistical information is returned.

NON_UNIQUE smallint The unique index indicator. Determines whether or not duplicate values are permitted in the index.

One of the following values: 0 (FALSE) Index prohibits duplicate values.

1 (TRUE) Index allows duplicate values.

INDEX_QUALIFIER varchar(30) The qualifier for this index. This is the INDEX_QUALIFIER for the DROP INDEX SQL statement.

INDEX_NAME varchar(30) The name of the index described in this row.

If this row contains statistics on a table (TYPE is TABLE_STAT), NULL is returned in this column.

TYPE smallint

not NULL

One of the following values: 0 TABLE_STAT The row contains statistical information about a table.

1 INDEX_CLUSTERED The row describes a clustered index.

NOTE: This column is always returned as 1.

SEQ_IN_INDEX smallint The relative position of the named column in the key sequence. The first column is 1.

COLUMN_NAME varchar(30) The name of a column in an index key.


UAHS Catalog RPCs sp_statistics 11-21

COLLATION char(1) One of the following values: A The sequence of the key columns is ascending.

D The sequence of the key columns is descending.

CARDINALITY int Cardinality of the table or index.

Note: This information is not readily available from DMS 2200. These columns are always returned as NULL.

PAGES int Number of pages used to store the index or table.


FILTER_CONDITION char(128) If the index is a filtered index, this is the filter condition.





sp_tables

Function

Lists the relationally mapped tables.

Syntax

sp_tables [table_name], [table_owner], [table_qualifier], [table_type]

Parameters

table_name [varchar(30)](I) The names of one or more relationally mapped tables about which information is requested. If you omit this value, information is returned about all objects.





table_type [varchar(128)](I) Specifies the type(s) of objects to be returned. Enter either a list of table types separated by commas, with each type enclosed in single quotes and the entire specification enclosed in double quotes.


UAHS Catalog RPCs sp_tables 11-23

Assign this parameter any or all of the following values, entering them as shown:

“‘TABLE’, ‘VIEW’”


Comments

• To support enumeration of qualifiers, owners, and table types, sp_tables defines the following special semantics for the table_name, table_owner, table_qualifier, and table_type parameters:

— If table_qualifier is a single percent character (%) and table_owner and table_name are empty strings, then the result set contains a list of valid qualifiers for the data source. (All columns except the TABLE_QUALIFIER column contain NULLs.)

— If table_owner is a single percent character (%) and table_qualifier and table_name are empty strings, then the result set contains NULLs.

— If table_type is a single percent character (%) and table_qualifier, table_owner, and table_name are empty strings, then the result set contains a list of valid table types for the data source. (All columns except the TABLE_TYPE column contain NULLs.)

• You can use sp_tables to find out which relationally mapped tables are available.

• The result set may include all objects that match the specified table_owner and table_name, not only those for which a user has privileges.

To find out whether or not this is the case, execute sp_server_info and request the value for the attribute ACCESSIBLE_TABLES. If the value is Y, the result set contains only those objects that the current user is authorized to access. If the value is N, the result set contains all objects that satisfy the name and owner specifications.



Results

sp_tables lists relationally mapped tables. Results are ordered by the following columns:

• TABLE_TYPE• TABLE_QUALIFIER• TABLE_OWNER• TABLE_NAME

The result set consists of the columns described in Table 11-8.

Table 11-8: Result Set for sp_tables



TABLE_OWNER varchar(12) Always NULL.

TABLE_NAME varchar(30) The name of the object whose information is returned.

TABLE_TYPE varchar(30) One of the following values: TABLE, VIEW.


V Advanced Data Access

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part V

Advanced Data Access through UniAccess

Chapter 12: Using UniAccess Transaction Server for OS 2200

Chapter 13: Using UniAccess Distributed Transaction Coordinator


12 Using UATS

12 Using UniAccess Transaction Server for OS 2200

This chapter provides information that allows client applications to communicate successfully with user-written transactions, that is, transactions created with the UniAccess Transaction Server. The chapter is relevant to ODBC and Open Client applications issuing either RPCs or language requests.

Topics Page

Transaction Server Support 12-2

Server-Library Datatypes 12-2

ODBC Catalog RPCs 12-3

UAINFO Command 12-4

User Datatypes 12-7

RPC Processing 12-7

Parameters 12-7

Naming RPCs 12-8

Routing RPCs 12-9

Language Request Processing 12-9

Default Language Transaction 12-9



Transaction Server SupportUsing UniAccess Transaction Server, OS 2200 programmers can create transactions to access a variety of OS 2200 data. These transactions have been referred to in this manual as user-written (or site-written) transactions. They are also referred to in the UniAccess documentation as Server-Library transactions because they are created using UniAccess Server-Library, a set of functions that allow OS 2200 programmers to created TIP transactions that retrieve requests from and format responses to client applications.

User-written transactions may be accessed by both ODBC and Open Client applications. They are designed primarily to process client RPC requests, although they may also be designed as general-purpose transactions to process client language requests. This section provides information about client-level support features of the UniAccess Transaction Server that are common to clients issuing both RPCs and language requests.

Server-Library Datatypes

UniAccess Server-Library (UASL) supports a wide range of datatypes that can be returned to an Open Client application (including ODBC applications). These datatypes, named TDSxxx, are equivalent to the Client-Library and DB-Library datatypes used in Open Client applications.

Table 12-1 details the full set of datatypes supported by the UniAccess Server-Library. A cross-reference of Client-Library and DB-Library datatype names is included.

Table 12-1: Datatypes Supported by UASL

UASL Datatype Client-Library Datatype DB-Library Datatype

TDSBINARY CS_BINARY DBBINARY

TDSBIT CS_BIT DBBIT

TDSCHAR CS_CHAR DBCHAR

TDSDATETIME CS_DATETIME DBDATETIME

TDSDATETIME4 CS_DATETIME4 DBDATETIME4

TDSFLT4 CS_REAL DBREAL

TDSFLT8 CS_FLOAT DBFLT8


Using UniAccess Transaction Server for OS 2200 12-3

NoteRefer to Table 5-4 and Table 5-5 (page 5-8 and page 5-9) for a description of how ODBC datatypes are processed by the UniAccess ODBC Driver when ODBC procedure calls are translated into RPC requests.

ODBC Catalog RPCs

Clients using the UniAccess ODBC Driver to access user-written transactions may obtain catalog information about available transactions if the site also uses the UniAccess Relational Service (UARS). The SQLProcedures function returns information about the user-written transactions that may process ODBC client applications. The SQLProcedureColumns function returns information about the input and output parameters of a transaction. This information will only be available if the RDMS 2200 tables that support these functions have been updated by the system administrator (see Appendix E of the UniAccess for OS 2200 System Administration Guide). Since these are RDMS tables, they are accessed through UARS.

TDSINT1 CS_TINYINT DBTINYINT

TDSINT2 CS_SMALLINT DBSMALLINT

TDSINT4 CS_INT DBINT

TDSMONEY CS_MONEY DBMONEY

TDSMONEY4 CS_MONEY4 DBMONEY4

TDSVARBINARY CS_VARBINARY DBVARYBIN

TDSVARCHAR CS_VARCHAR DBVARYCHAR

UASL Datatype Client-Library Datatype DB-Library Datatype



UAINFO Command

The UAINFO command provides connection and version information about user-written transactions to ODBC and Open Client applications operating in a UniAccess Transaction Server environment. (UAINFO is also available to applications in UARS and UAHS environments.) It can be executed both as a language request and an RPC request.

Function

This command returns information about the UniAccess environment in a row/column format.

Syntax

UAINFO

Comments • When Server-Library transactions are being used with UADriver, the UAINFO

transaction must be installed and configured for UADriver to function. (See Chapter 4 and Chapter 5 respectively in the UniAccess for OS 2200 System Administration Guide.)

• When the UADriver is configured with a language type of UARS, UARS supports the UAINFO command.

• When the UADriver is configured with a language type of UAHS, UAHS supports the UAINFO command.

• For Open Client applications, the language type and support of the UAINFO command is determined by the COMSRV DFLTTRAN parameter on the host.

• UAINFO returns the list of attributes and their values described in Table 12-2.



Table 12-2: Information Returned by UAINFO


1 HOST_TDS_LEVEL TDS level supported by UARS.







8 UAINFO_LEVEL Level of the UAINFO transaction.

9 CHARACTER_TRUNCATION Character string truncation indicator. YES indicates that character strings longer

than 255 characters should be truncated.

NO indicates that character strings longer than 255 will generate an error.

10 DISTTRAN Distributed transaction capability indicator.YES indicates that distributed transactions

are allowed.NO indicates that distributed transactions

are not allowed.

11 UAMM_BLOCKSIZE The size in bytes of the configured UACS UAMM fixed memory blocks. UACS is capable of setting the value of the UAMM BLOCKSIZE configuration parameter to 512, 1024, 2048, or 4096 bytes. The CS_PACKETSIZE should normally match this value.



Results

The Table 12-3 describes the result set generated by the UAINFO command.

Table 12-3: Result Set for UAINFO

Example

The following is an example of the UAINFO result set.

1, "HOST_TDS_LEVEL", "4.2", 02, "HOST_MACHINE_TYPE", "2200/500", 03, "HOST_EXEC_LEVEL", "44R4B", 04, "UAFG_LEVEL", "10R3-0", 05, "CONNECTION_PID", "1000", 06, "CLIENT_INTR_ADDR", "192.168.1.128", 07, "CLIENT_INTR_PORT", "2707", 08, "UAINFO_LEVEL", "10R3-0", 09, "CHARACTER_TRUNCATION", "YES", 010, "DISTTRAN", "YES", 111, "UAMM_BLOCKSIZE", "4096", 0


attribute_id int The numeric representation of the attribute whose value is returned in this row. This is one of the attributes listed in Table 12-2.

attribute_name varchar(30) The name of the attribute.

attribute_value varchar(80) The current value of the attribute.




User Datatypes

UAINFO allows Open Client applications to obtain information about datatypes from a user datatype that returns column descriptor information. (This information is available to ODBC client applications from the Catalog RPCs.) For more information about user datatypes, see page 4-5.

RPC ProcessingRemote procedures calls (RPCs) are requests issued by client applications and directed to a particular procedure on a server. (Note that ODBC applications make procedure calls that are converted to RPCs by UADriver.) Each RPC must be associated with and mapped to a specific procedure on the server. Thus, to access OS 2200 resources using an RPC, there must an OS 2200 procedure to act as server and satisfy the request.

The client and server applications that process RPCs are specifically written to correspond to one another. For example, the format of the request created by the client application must be understood by the server application and the results returned by the server must be understood by the client. Programmers must ensure that each RPC is mapped to a corresponding procedure on the server that will receive it.

In the UniAccess System, RPCs are processed by Server-Library transactions or by RDMS 2200 stored procedures. This section concerns those RPCs processed by Server-Library transactions. Information on RDMS stored procedures is found in Chapter 6, as these are processed by the UniAccess Relational Service.

Parameters

User-written transactions may have both optional and required parameters. Required parameters must have values supplied; optional parameters default to predefined values.

ODBC applications. Parameters for user-written transactions are positional. All Catalog RPC parameters must be unnamed and passed in the order that corresponds to the Catalog RPC definition.

Open Client applications. Parameters for user-written transactions are positional or named. The following rules apply:




• If named parameters are used, all parameters must be named.


Naming RPCs

For a Server-Library transaction to be executed by an RPC, the name of the RPC must be associated with the appropriate transaction code. While an RPC name may be up to 30 characters, the VALTAB transaction code may only be six characters. The system administrator can choose to handle the association of an RPC name with a transaction code in one of two ways.

• The UniAccess Transaction Server’s optional RPC mapping facility may be employed to map RPC names up to 30 characters to their appropriate VALTAB transaction codes. To do so, the system administrator creates an RPC Map Record using the RPCMAP configuration statement (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide). The RPCMAP configuration statement allows the administrator to configure a single RPC name that can schedule different transactions based on application groups or UACSs.

• The UniAccess Transaction Server uses the first six characters of an RPC name as the VALTAB. This option will take place unless RPC mapping has been specified. In this case, the user must be certain that the first six characters of each RPC are unique to that RPC and match the VALTAB of the transaction. For example:

RPC name = UPDCUSTOMERRECORD

VALTAB = UPDCUS



Routing RPCs

Client RPCs are routed to Server-Library transactions by UACS, the UniAccess Communication Server. Since UACS may also receive RPCs directed to RDMS 2200 stored procedures, it must have a method of determining how to route procedure requests and replies.

RPCs may be mapped individually by the system administrator as described in the previous section. Alternatively, the administrator may chose to send all RPCs to the UniAccess Transaction Server for processing by Server-Library transactions. In this case, all RPCs are routed to Server-Library transactions automatically, using the 1st 6 characters of the RPC name as the VALTAB. (This choice, however, eliminates the option of mapping RPC names of up to 30 characters to their appropriate VALTAB transaction codes.)

When ODBC SQLProcedures and SQLProcedureColumns catalog information is returned to the for a client RPC it is possible that UACS will encounter duplicate Server-Library and RDMS stored procedure names. Page 6-28 explains the protocol UACS uses to determine which catalog information to return.

Language Request ProcessingIn the UniAccess System, language requests are generally processed by the UniAccess Relational Service for RDMS 2200 or the UniAccess Hierarchical Service for DMS 2200. However, a site may create its own language transaction using UniAccess Server-Library. The features of and rules governing the use of such a transaction would be unique to that transaction, and therefore, will not be discussed here.

Default Language Transaction

The system administrator may specify a user-written language transaction as the default transaction for processing client language requests. This is done using the COMSRV DFLTTRAN configuration parameter. When this occurs, all language requests submitted by Open Client applications and applications using a pre-6R2 UniAccess ODBC Driver will be forwarded automatically to this default transaction. For applications using a 6R2 or greater UniAccess ODBC Driver, the user-written language transaction is set by selecting User Language Transaction in the ODBC data source configuration (see page 5-13).


13 Using UADTC

13 Using UniAccess Distributed Transaction Coordinator

This chapter provides background and procedural information for the UniAccess Distributed Transaction Coordinator (UADTC).

Topics Page

Distributed Transaction Processing 13-2

Transactions 13-2

Distributed Transactions 13-3

Distributed Transaction Processing 13-5

UniAccess / Microsoft Implementation 13-6

UADTC Setup 13-9

System Requirements 13-9

Network Topology 13-9

Installation 13-11

Transaction Coordinator Connectivity Test 13-11

UADTC Management 13-12

Starting and Stopping UADTC 13-12

Configuring UADTC Settings 13-13

Distributed Transaction Management 13-15

Monitoring Distributed Transactions 13-17

Distributed Transaction States 13-20

Resolving Distributed Transactions 13-22



Distributed Transaction ProcessingThis section presents an overview of transactions and distributed transactions, and of the UniAccess/Microsoft implementation of distributed transaction processing.

Transactions

A transaction is a module of execution—that is, an action or series of actions—that transforms a system from one consistent state to another. Transactions are characterized by their ACID (atomic, consistent, isolated, and durable) properties:

• Atomicity—A transaction will either commit or abort. If a transaction commits, all of its effects remain; if it aborts, all of its effects are undone. For example, when you rename an object, the new name is created and the old name is deleted (commit), or the object is not renamed (abort).

• Consistency—A transaction is a correct transformation of the system state; it preserves the state invariants. For example, when you add an element to a double-linked list, all four forward and backward pointers are updated.

• Isolation—Concurrent transactions are isolated from the updates of other incomplete transactions; these updates do not constitute a consistent state. This property is often called serializability. For example, a second transaction traversing the double-linked list mentioned in the previous consistency example will see the list before or after the insert, but will only see complete changes.

• Durability—Once a transaction commits, its effects will persist even if there are system failures. For example, after the object in the previous atomicity example is renamed, it will have the new name even if the system fails and reboots right after the commit completes.

Because transactions provide modular execution, they simplify and automate fault handling. They provide a simple conceptual execution framework for both users and implementers. The user thinks of a transaction as a single change event that either happens or doesn’t happen. Implementers think of a transaction as a programming style that allows them to write reusable modules that may execute individually or participate in distributed computations.


Using UniAccess Distributed Transaction Coordinator 13-3

Distributed Transactions

Distributed transactions extend the benefits of transactions to applications which must update distributed data. A distributed transaction updates data across two or more computer systems. For instance, suppose a travel agency wishes to set a travel itinerary that includes an airline reservation and a hotel reservation, but the airline and hotel data reside on two different data systems. The travel agent wants to make sure that either both reservations are made or neither is made. The implementer wants to ensure the integrity of the two databases. It is mandatory that both databases be either committed or rolled-back as one atomic unit. The distributed transaction model ensures that this condition is met.

Distributed transactions involve the following (see Figure 13-1):

• Transaction manager—a system service responsible for coordinating the outcome of distributed transactions in order to achieve atomicity. Transaction managers can be considered the directors of distributed transaction activities. They coordinate with each resource manager to ensure that all the local transactions making up the distributed transaction are committed or rolled back together. Multiple transaction managers may cooperate to manage a single distributed transaction, with one acting as the primary transaction manager.

• Resource managers—a generic term for a transactional data management service such as a database management system or a queue management system. Resource managers are the participants in a distributed transaction that manage durable data. A distributed transaction is made up of local transactions in each individual resource manager. Each resource manager must be able to commit or roll back its local transaction in coordination with all the other resource managers in the distributed transaction.

• Two-phase commit (2PC) protocol—Special commit processing is required to prevent problems in managing transactions that span multiple resource managers. Following this protocol, a transaction manager first asks every resource manager involved in the transaction if it is prepared to commit. If every resource manager says yes, that is, if every database the application would change is willing to go ahead, then the transaction coordinator tells each one to commit. If, on the other hand, one or more of the resource managers is unable or unwilling to commit, the transaction manager tells all of them to roll back the transaction. The first phase requires polling all resource managers to see if they are prepared to commit; the second phase tells each one what to do—commit or abort.



Figure 13-1: Distributed Transaction Processing

When a transaction does work at multiple computers, each computer has a local transaction manager that tracks incoming and outgoing transactions. Each transaction manager performs all the enlistment, prepare, commit, and abort calls for local resource managers (ones on that computer). The local transaction manager for the caller serves as the primary transaction manager for this distributed transaction.

client workstation / network server

source 1 source 2

application

PrimaryTransaction Manager

SecondaryTransaction Manager

ResourceManager

data data

ResourceManager

data data



To commit a transaction that is distributed among several computers, the primary transaction manager sends prepare, commit, and abort messages to all its outgoing (secondary) transaction managers. When a secondary transaction manager is in doubt about a distributed transaction, it queries the incoming (primary) transaction manager. The primary transaction manager is never in doubt. If an in-doubt transaction persists for too long, the system operator can force the transaction to commit or abort.

Distributed Transaction Processing

There are five general steps involved in processing a distributed transaction:

1. Establish a primary transaction manager. The local transaction manager for the caller serves as the primary transaction manager for this distributed transaction.

2. Initiate the distributed transaction. The caller may or may not have a transaction in place. The primary transaction manager may be used to create transaction objects and perform operations on them.

3. Enlist resource managers. Once a resource manager is enlisted, it remains in an extended session with its attention focused on this transaction, until the transaction is either committed or aborted.

4. Indicate whether or not a resource is prepared to commit. While the resource manager is in a prepared state, it is in doubt about whether the transaction’s resolution until it receives the commit or abort command from the primary transaction manager. Resources modified by the transaction remain locked and unavailable to others.

5. Commit or abort the transaction. The commit or abort command ends the extended session with the resource manager and places the system in a consistent state.

Distributed transaction processing is transparent to the end user; even the client application need not be aware that any kind of transaction protocol is in use.



UniAccess / Microsoft Implementation

While distributed transactions extend the benefits of transactions to applications which must update distributed data, implementing robust distributed applications is difficult. These applications are subject to multiple failures, including failure of the client, the server, and the network connection between the client and server. In the absence of distributed transactions, on the other hand, the application program itself must detect and recover from these failures. Microsoft’s Distributed Transaction Coordinator (MS DTC), presents a solution to the difficulties of distributed transactions by handling all relevant coordination issues, thus enabling simpler and easier-to-implement applications.

UniAccess distributed transaction support extends Microsoft’s Windows distributed transaction capabilities to the Unisys OS 2200 environment. UniAccess’ distributed transaction support uses proven transaction processing technology: it is robust despite system failures, process failures, and communication failures; it exploits loosely coupled systems to provide scalable performance.

System Components

The following components are involved in supporting distributed transaction processing (see Figure 13-2):

Microsoft Distributed Transaction Coordinator (MS DTC) is a distributed transaction facility for Windows. When used with UniAccess, MS DTC is the primary or root transaction manager, which means it has responsible for creating transaction objects and managing their atomicity and durability.

UniAccess Distributed Transaction Coordinator (UADTC) is the interface between MS DTC and the OS 2200-based resource manager components. UADTC is a child or secondary transaction manager to MS DTC, which means it is subservient to MS DTC and acts as a gateway, forwarding 2PC commands between MS DTC and UniAccess on the OS 2200.

Component Object Model+ (COM+) is a runtime environment for components that encapsulate business logic. Because COM+ relies on MS DTC to act as the transaction manager responsible for coordinating transactions across participating databases, UniAccess can participate in COM+-controlled distributed transactions.

COM+ Component is the user-written component that implements business logic and updates OS 2200 UDS/TIP FCSS data using UADriver.



Transaction Internet Protocol is an industry-standard network format and protocol through which two or more transaction managers can perform two-phase commit and recovery.

UniAccess ODBC Driver (UADriver) is the mechanism through which database connections are enlisted in distributed transactions and OS 2200 UDS/TIP FCSS data is modified.

UniAccess Communication Server (UACS) in conjunction with other UniAccess components, performs resource manager functions.

UniAccess Server-Library (UASL) is a set of standard routines (functions) thatallow programmers to create TIP transactions that will operate in the OS 2200 environment.

UniAccess distributed transactions are UASL transactions that are participating in MSDTC-initiated distributed transactions co-managed by UADTC. UniAccess distributed transactions automatically initiate 2PC processing with the underlying resource manager via step control.

TIP is the UASL runtime environment.

UDS/TIP FCSS Data is the resource manager-controlled transactional data.

Processing Distributed Transactions with UADTC

Figure 13-2 illustrates how UniAccess fits into the Microsoft distributed transaction processing architecture. MS DTC serves as the primary transaction manager and UADTC as a secondary transaction manager. UADTC enlists participating UniAccess distributed transactions, thus allowing OS 2200-based resources to participate in a distributed transaction.

Transaction Internet Protocol is used to communicate between MS DTC and UADTC. UADTC in turn uses TDS protocol to forward the messages to UACS. In that sense, UADTC acts as a gateway between MSDTC and UACS.

The COM+ component uses the UniAccess ODBC Driver to perform DML against the OS 2200 data source. UniAccess ODBC Driver, in turn, uses the TDS and DCOM protocols to communicate with UACS and UADTC respectively.



Figure 13-2: UniAccess / Microsoft Implementation ofDistributed Transaction Processing

NoteThe three components shown in the Windows 2000 (or later) environment can be partitioned into up to three separate systems.

Windows 2000 (or later)

OS 2200

COM+Component

usingUADriver

MS DTC UADTC

UDS/TIP FCSS

Data

COM+ Environment

Transaction Internet Protocol

TDS

ODBC/TDS

UACS

UASLTransaction

MS SQL Server

SQL Data

ResourceManager

OLE

TX

(or other datasource)

UniAccess(data source)

TIP Environment

OLE TX DCOM



UADTC SetupThis section explains the PC and network requirements for UADTC, as well as UADTC installation and verification. (See Appendix D for Troubleshooting assistance.)

System Requirements

PC Client software requirements are driven by the operating system required to support the desired functionality. For UADriver to support distributed transaction processing, the driver must be installed on a system running Windows 2000 (or later) and MS DTC. UADTC can be installed on a system running Windows NT 4.0 (or later).

For a list of software requirements, see Chapter 3.

Network Topology

MS DTC, UADTC, and the COM+ component(s) can be located on physically separate machines (see Figure 13-3). There must be network connectivity between MS DTC and UADTC, the COM+ component and MS DTC, the COM+ component and UADTC, and UADTC and the OS 2200 host. An enterprise can have one or more instances of UADTC running on different machines. Additionally, one instance of UADTC can access multiple OS 2200 hosts concurrently.

Security and Communication Between COM+ Components and UADTC

As described earlier, UADriver communicates with UADTC via DCOM. This means that the DCOM security settings on UADTC should be configured in such a manner that UADriver can access it. Note that UADriver runs under the identity of the COM+ component that invoked it. This means that the account under which the COM+ component is configured to run should have access permissions to UADTC.

For more information about DCOM security, see the DCOM security topics in the Windows 2000 (or later) Platform SDK.



Figure 13-3: UADTC Network Topology

Simple Implementation


Windows 2000(or later)

OS 2200

Windows NT4.0 (or later)

Windows NT4.0 (or later)

UADriver

UADriver

MSDTC

MSDTC

UA DTC

UA DTC

UA DTC

Complex Implementation

NOTE: To clarify the possible distribution of UADTC, resource managers other than UniAccess have not been included in thefigure.

OS 2200UniAccess

OS 2200UniAccess

OS 2200UniAccess

OS 2200UniAccess

UniAccess



Installation

The UADTC service is automatically installed when the UADriver and UADTC setup type option is selected during the installation under Windows NT (or later) or Windows 2000 (or later).

When the UADTC service is installed, a shortcut, UniAccess DTC Manager, is automatically placed in the installation directory. This shortcut can be used to load the UADTC Snap-in. For more information on manually configuring another Snap-in, see the Microsoft Management Console topic in the Windows 2000 (or later) Platform SDK.


The UADriver setup dialog includes a Test tab with an option that allows users to verify connectivity to UADTC. To make this option available, the Support Distributed Transaction option of the UADriver Setup / Advanced Setup dialog must be checked. The test option, called the Transaction Coordinator Connectivity Test, provides a means to test the following connectivity paths:

• UADriver machine to UADTC machine

• UADTC machine to MS DTC machine

• UADTC machine to OS 2200 host.

If UADTC is running remotely, the location of UADTC must also be configured in the UADriver Setup / Advanced Setup dialog. For more information about the Transaction Coordinator Connectivity Test and its results, see Appendix D.



UADTC ManagementThis section explains how to start and stop the UniAccess Distributed Transaction Coordinator (UADTC) and how to configure UADTC settings.

Starting and Stopping UADTC

UADTC must be started (either manually or automatically) before you can begin managing transactions. To start UADTC manually, use the UADTC Management Console or (if you do not have the Management Console installed) the Windows Control Panel.

By default, UADTC is not configured to start automatically when Windows starts. It can be configured to do so using the Control Panel.

From the UADTC Management Console

To start or stop UADTC manually using the UADTC Management Console:

1. In the left pane of the UADTC Management Console, select the computer on which you are managing UADTC.

2. Open the Action menu and select Start UADTC or Stop UADTC. You can also right-click and select Start UADTC or Stop UADTC in the right-click menu.

From the Windows NT Control Panel

To start or stop UADTC manually using the Windows NT Control Panel:

1. Open the Start menu, and select Settings/Control Panel.

2. Click the Services icon.

3. In the Services list, select UADTC and click the Start button.

4. Close the Services window.



From the Windows 2000/XP Control Panel

To start or stop UADTC manually using the Windows 2000 Control Panel:

1. Open the Start menu, select Settings/Control Panel/Administrative Tools/Computer Management.

2. Expand System Tools (Services and Applications for Windows XP) in the left pane, and click the Services icon.

3. In the Services list, select UADTC and click the Start button.

4. Close the Computer Management window.

Configuring UADTC Settings

You can configure UADTC settings, such as the location of the UADTC log file, using the Computer property dialog. To configure UADTC settings:

1. In the left pane of the UADTC Management Console, select the computer on which you are managing UADTC.

2. Open the Action menu and select Properties. (You can also right-click and select the Properties option from the menu.)

3. You can adjust the logging options, service options, host connection options, and the display refresh rate.

The following is a description of configurable UADTC Settings (see Figure 13-4).

Logging Options

Log File DirectoryThis optional value specifies the location of the UADTC log file. A new log file will be created every day with the following format: uadtcyyyyddd.log. If no directory is specified, the default directory of %WinDir%\System32\LogFiles\UADTC\ is used.

Log File LevelThis value specifies the threshold for the log information to be traced. Options are Low, Medium and High. The default value is Low.



Service Options

Listen PortThis value specifies the port upon which UADTC will communicate with MS DTC. The default value is 2767 as assigned by the Internet Assigned Number Authority (IANA). Zero tells UADTC to use any available port. When zero is selected, UADTC will update this value with the operating system assigned port value. For recovery scenarios, UADTC must maintain the same port. The valid range is from 0 to 65535. This value is required.

Worker ThreadsThis value specifies the number of worker threads to be started. The default value is 2. The valid range is from 1 to 16. This value is required.

Host Connection Options

Max Host ConnectionsThis value specifies the maximum number of connections that UADTC can establish to different UACSs. The default value is 2. The valid range is from 1 to 16. This value is required.

Idle Host ConnectionsThis value specifies the maximum number of idle connections to maintain for a single UACS. The default value is 2. The valid range is 0 to the value configured for Max Host Connections. This value is required.

Connection TimeoutThis value specifies the number of seconds a connection to UACS will remain idle before being terminated. The default value is 60. The valid range is from 0 to 999999999 where 0 means never time out the connection. This value is required.

Display Refresh Rate

This value specifies the frequency that the UADTC management console snap-in will refresh transaction detail and summary information. A high frequency refresh rate will refresh the display approximately every five seconds. A low frequency refresh rate will refresh the display approximately every sixty seconds.



Figure 13-4: UADTC Configuration Options Dialog

Distributed Transaction ManagementThe UADTC Snap-in is the visual tool used to manage UniAccess distributed transactions (hereafter referred to as distributed transactions). In the UniAccess environment, distributed transactions are UniAccess Server-Library transactions that are participating in MSDTC-initiated distributed transactions. You use the UADTC Snap-in to monitor the status of transactions and to manually resolve transactions that have entered an unresolved state.



The UADTC Snap-in is a snap-in hosted by the Microsoft Management Console (MMC) on Windows NT (or later) and Windows 2000 (or later). The Snap-in contains the following folders in the left tree view hierarchy (see Figure 13-5):

• Computers. Contains the computers managed from this server, including the local computer. The properties for each computer can be configured.

• My Computer. By default, the name of the local computer on which UADTC is installed.

• Transaction List. Appears in the folder of each computer in the Computers folder. It displays the active distributed transactions on that computer.

• Transaction Statistics. Appears in the folder of each computer in the Computers folder. It displays statistics on active distributed transactions on that computer.

Figure 13-5: UADTC Snap-in Hierarchy



Monitoring Distributed Transactions

You can monitor distributed transactions by using the transaction windows in the UADTC Snap-in described above. The Transaction List and Transaction Statistics windows provide valuable information about the status of transactions managed by UADTC.

Using the Computers Folder

The computers folder contains My Computer and other computers that you have added to your Computers folder. By default, My Computer corresponds to the local computer on which UADTC is installed. You can add a computer to the Computers folder by doing one of the following:

1. Right-click the Computers folder and choose New/Computer, or

2. Select the Computers folder, open the Action menu. In the left pane of the Snap-in choose New.

3. In the Add Computer dialog box, type the name of the server you would like to administer from your computer. The new server is added to the Computers folder below the My Computer icon in the UADTC hierarchy.

Using the Transaction List

The Transaction List window displays the current distributed transactions in which a computer participates and an icon that represents the transaction’s current state. The list includes the following information that is essential for transaction monitoring:

• Transactions that have entered an unresolved state.

• Transactions that have remained in the same state for the period of time specified by the Display Refresh Rate on the Computer property dialog.

(See Table 13-1: Distributed Transaction States for a description of unresolved states and of the icons which correspond to all the transaction states that may be displayed.)

To monitor transactions using the Transaction List:

1. In the left pane of the UADTC Snap-in, double-click the folder of the computer that is hosting the transactions. The folder’s contents, including the Transaction List for that computer, will be displayed.



2. In the left pane, click on the Transaction List icon under the host computer. The Transaction List is displayed in the right pane.

3. Right-click anywhere in the right pane, and point to the View command on the shortcut menu. The View sub-menu will open.

4. On the View sub-menu, click one of the following display mode options.

NoteThe Small Icon and List commands display the most transactions at any one time. Detail provides the most information about the transactions, and Large Icon displays transactions in the most readable format.

Viewing Transaction Statistics

The Transaction Statistics window displays statistics for the distributed transactions in which a computer participates. Some of the statistics are cumulative; others reflect current performance.

To view transaction statistics:

1. In the left pane of the UADTC Snap-in, select the folder of the computer on which you want to view transaction statistics.

Views Description

Large Icon Displays transactions as large icons.

Small Icon Displays transactions as small icons.

List Displays transactions sequentially in a column.

Detail Lists transactions in rows with columns for the MS DTC transaction id and the UDS transaction id.

The MS DTC transaction id is the transaction's global unique identifier, and is generated by MS DTC when the distributed transaction begins. The UDS transaction id is the UDS step control identifier associated with the distributed transaction.



2. Click the Transaction Statistics icon in the left pane. The UADTC Transaction Statistics window is displayed in the right pane. The following statistics may be displayed.

Viewing Transaction Properties

You can view transaction properties by right-clicking a transaction icon and then selecting the Properties command. The Properties command lists the network addresses of the parent MS DTC and UACS that are involved in the transaction.

The transaction’s statistics counters will be incremented by the number of local transactions participating in one distributed transaction. For example, consider a case when as part of one MS DTC transaction, a COM+ component opened two ODBC connections to OS 2200. Two ODBC connections will cause two local transactions to participate in the distributed transaction. Later, when the distributed transaction is completed, based on the outcome, one of the aggregate counters will be incremented by two.

Statistic Description

Current

Active The current number of distributed transactions that have not yet completed the two-phase commit protocol.

Max. Active The highest number of active distributed transactions at any time during the current UADTC session.

Unresolved The current number of distributed transactions that are unable to commit because of a communication failure between two nodes.

Aggregate

Committed The number of committed distributed transactions. This number does not include forced (manually resolved) commits.

Aborted The number of aborted distributed transactions. This number does not included forced aborts.

Forced Commit The number of manually committed distributed transactions.

Forced Abort The number of manually aborted distributed transactions.

Total The total number of all distributed transactions.

UADTC Started The date and time the current UADTC session started. The date and time started will not appear unless UADTC is started.



Distributed Transaction States

In order to manage distributed transactions you must understand the different transaction states and their implications for the COM+ components that you are administering. Transaction states are represented by the following icons in the Large Icon view of the UADTC Transaction List window:

Table 13-1: Distributed Transaction States

Icon Transaction State Description

Active This is the initial distributed transaction state. The transaction has been successfully enlisted with MS DTC and the OS 2200 host.

Preparing A PREPARE request has been received from MS DTC for this transaction.

Prepared A distributed transaction has responded yes to a PREPARE request and the PREPARE result has been sent to MS DTC.

Committing A distributed transaction is prepared and a COMMIT request has been received from MS DTC for this transaction.

Committed The transaction has committed. A COMMIT response has been received from a distributed transaction, but the COMMIT response has not been sent to MS DTC yet.

Aborting An ABORT request has been received from MS DTC for this transaction.

Aborted The transaction has aborted. An ABORT response has been received from a distributed transaction, but the ABORT response has not been sent to MS DTC yet.



In Doubt A distributed transaction has responded yes to a PREPARE request and the coordinating MS DTC is inaccessible. The system administrator can force the transaction to COMMIT or ABORT by right-clicking in the Transactions window and choosing the Resolve/Commit or Resolve/Abort command. Once an outcome is forced, the transaction is designated as Forced Commit or Forced Abort.

Caution Do not force an In Doubt transaction manually until you have read the Resolving Distributed Transactions section.

Forced Commit The administrator forced an unresolved transaction to commit (see Resolving Distributed Transactions).

Cannot Notify Committed UADTC has received a COMMIT request from MS DTC but is unable to forward the request to a distributed transaction because the connection to the OS 2200 system is down.

The system administrator can force UADTC to forget the transaction by right-clicking in the Transactions window and choosing the Resolve/Forget command.

Caution Do not forget a transaction manually until you have read the Resolving Distributed Transactions section.

Forced Abort The administrator forced an unresolved transaction to abort (see Resolving Distributed Transactions).

Cannot Notify Aborted UADTC has received an ABORT request from MS DTC but is unable to forward the request to a distributed transaction because the connection to the OS 2200 system is down.

The system administrator can force UADTC to forget the transaction by right-clicking in the Transactions window and choosing the Resolve/Forget command.

Caution Do not forget a transaction manually until you have read the Resolving Distributed Transactions section.

Icon Transaction State Description



Resolving Distributed Transactions

Occasionally, you may need to force a distributed transaction to either commit or abort to release locks and make database resources available to other network users and applications. This can be necessary, for example, when a communication line fails between two computers on the network. Once a transaction has been committed or aborted manually, often it is necessary also to force a computer to forget the transaction manually, which deletes the transaction from the local UADTC.

You can use the Transaction List window in the UADTC Snap-in to resolve a distributed transaction by choosing one of the following commands:

• Commit — forces the transaction to commit.

• Abort — forces the transaction to abort and roll back to its original state.

• Forget — deletes a committed or aborted transaction from UADTC’s list of active transactions. You should always force an outcome for a transaction before using this command.

When a distributed transaction enters an unresolved state (In Doubt, Cannot Notify Committed, and Cannot Notify Aborted), the first phase of the two-phase commit protocol has been completed so that the transaction is in the PREPARED state. At this stage, the communication between MS DTC and UADTC or UADTC and UACS has failed. Hence, the transaction is left in an unresolved state. Different types of communications failures result in different unresolved transaction states. A description of these states and the procedures to resolve them are presented in this section.

It is important to understand that MS DTC is always the primary transaction manager, and the primary transaction manager is never in doubt. This means that to resolve transactions in an unresolved state, the administrator must refer to the primary MS DTC for more information.

WarningPlease make sure you have read the chapter Resolving MTS Transactions in the COM+ administrator’s guide before you force MS DTC to forget a transaction.



Resolving the In Doubt State

The In Doubt state indicates that the distributed transaction is prepared, and that the primary MS DTC is inaccessible (see Figure 13-6).

Figure 13-6: Communications Break Resulting in an In Doubt State


OS 2200

COM+Component

usingUADriver

MS DTC UADTC

UDS/TIP FCSS

Data

UACS

UASLTransactionData

ResourceManager

data source (data source)other



To resolve the In Doubt transaction, follow these steps:

1. Use the Transaction List window to locate the In Doubt transaction's immediate parent. To do this, right-click the transaction and select the Properties command. This displays the parent MS DTC computer for the transaction.

2. Locate the parent MS DTC and use the Transaction List window on the parent computer to determine the outcome of the In Doubt transaction.

— If the transaction does not appear in the Transaction List window, then the transaction has been aborted, and you can abort the transaction on the child computer manually.

— If the transaction appears on the parent computer as Cannot Notify Committed, then the transaction has committed, and you can commit the transaction manually.

— If the transaction appears on the parent computer as Cannot Notify Aborted, then the transaction has aborted, and you can abort the transaction manually.

3. If the transaction is shown as In Doubt on the parent computer, use the Transaction List window on the parent computer to locate the transaction's next immediate parent. Continue to follow the transaction up the commit tree until you locate the parent on which the transaction is either not shown (indicating that it aborted), in the Cannot Notify Aborted (indicating that it aborted) state, or in the Cannot Notify Committed (indicating that it committed) state. If the transaction is aborted on the parent computer, force the transaction to abort manually on that computer's immediate child. If the transaction is committed on the parent computer, force the transaction to commit manually on the child computer.

4. Once you have either committed or aborted the transaction manually on the UADTC computer, force the parent MS DTC to forget the transaction manually.



Resolving the Cannot Notify Committed State

The Cannot Notify Committed state indicates that the distributed transaction has committed, but UADTC is unable to notify the waiting distributed transaction (see Figure 13-7).

Figure 13-7: Communications Break Resulting in a Cannot Notify State


OS 2200

COM+Component

usingUADriver

MS DTC UADTC

UDS/TIP FCSS

Data

UACS

UASLTransactionData

ResourceManager

data source (data source)other



You can manually resolve the transaction in a Cannot Notify Committed state as follows.

1. Right-click on the transaction. This displays the address of machine on which the waiting distributed transaction is located.

2. Manually force the transaction to commit using UniAccess Integrated Recovery

processor (UAIR). (See Chapter 15 in the UniAccess for OS 2200 System Administration Guide for information on using UAIR in interactive mode for this purpose.)

3. Return to the UADTC that shows the transaction in the Cannot Notify Committed state, and force that UADTC to forget the transaction.

4. Return to the parent MS DTC and force it to forget transaction.

Resolving the Cannot Notify Aborted State

The Cannot Notify Aborted state indicates that the transaction has aborted, but UADTC is unable to notify the waiting distributed transaction (see Figure 13-7). You can resolve the transaction manually as follows.

1. Right-click on the transaction that is in the Cannot Notify Committed state. This displays the address of machine on which the waiting distributed transaction is located.

2. Manually force the transaction to abort using UniAccess Integrated Recovery processor (UAIR). (See Chapter 15 in the UniAccess for OS 2200 System Administration Guide for information on using UAIR in interactive mode for this purpose.)

3. Return to the UADTC that shows the transaction in the Cannot Notify Aborted state, and force that UADTC to forget the transaction.

4. Return to the parent MS DTC and force it to forget the transaction.

Appendixes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendixes

Appendix A: Client Examples

Appendix B: Server Program Messages

Appendix C: UAMM Error Messages

Appendix D: Troubleshooting

Appendix E: References


A Client Examples

A Client Examples

This chapter provides examples designed to work with the sample system that is included with UniAccess. Complete example applications can be installed as part of the UniAccess 10R3 SDK found on the UniAccess 10R3 PC Client CD provided with your UniAccess package.

Interactive SQL ExamplesUsing Interactive SQL, any RDMS 2200 command listed in Table 6-1 (page 6-4) can be sent to the UniAccess Relational Service. Commands can be sent one at a time or they can be batched by separating multiple commands with a semi-colon. The following are several examples of RDMS 2200 and non-RDMS 2200 commands that can be sent using Interactive SQL.

Example 1

select * from uasample.employee

Topics Page

Interactive SQL Examples A-1

Microsoft Transact-SQL Examples A-2

From SQL Query Analyzer A-2

From a Stored Procedure A-3

Visual Basic Example A-3

A-2 UniAccess for OS 2200 Client Guide


Example 2

uarsinfo

Example 3

uainfo

Example 4

select first_name, last_name, job_description.description job_description, job_category.description category_description from employee, job_description, job_category

Example 5

select * from uasample.employee;uarsinfo

Microsoft Transact-SQL ExamplesThis section provides Transact-SQL examples of initiating an indirect request through a Microsoft SQL Server. Requests sent from a SQL Server to the UniAccess Transaction Server are always in the form of an RPC.

From SQL Query Analyzer

The following Transact-SQL statement calls the remote procedure get_employee.

declare @row_count intexec uacs...get_employee '%', '%', @row_count outputprint 'number of rows = ' + (cast (@row-count as char (4) ) )

where:

UACS is the name of the Microsoft SQL Server linked server. The linked server is a UACS on an OS 2200 host.


Client Examples A-3

get_employee is the name of the RPC and/or TIP transaction. (Note that the name get_employee is not a valid TIP transaction name. See page 12-8 for information on mapping RPC names to TIP transaction names.)

When this statement is executed using SQL Query Analyzer on a Microsoft SQL Server, the Microsoft SQL Server sends an RPC named get_employee to a UACS named UACS. The Transaction Server forwards the call to the TIP transaction associated with the get_employee RPC.

From a Stored Procedure

The following Microsoft Transact-SQL statement creates a stored procedure on a Microsoft SQL Server that calls the remote procedure get_employee:

create procedure empfetch @first_name char(30), @last_name char(30), @row_count int outputas exec UACS...get_employee @first_name,

@last_name, @row_count output

When the empfetch stored procedure is executed on the Microsoft SQL Server on which it was created, the stored procedure sends an RPC named get_employee to UACS. UACS forwards the call to the TIP transaction associated with the get_employee RPC. The following Microsoft Transact-SQL statement will execute the empfetch stored procedure.

declare @row_count intexec empfetch '%', '%', @row_count outputprint 'number of rows = ' + (cast (@row-count as char (4) ) )

Visual Basic ExampleRefer to the Samples program folder item contained in the UniAccess 10R3 PC Client/UniAccess Sample program folder for details on the Visual Basic example. This program folder item and the associated samples are installed when the UniAccess 10R3 SDK Samples option is selected.

A-4 UniAccess for OS 2200 Client Guide



B Server Program Messages

B Server Program Messages

Server program messages those are generated by a UniAccess System server component or by a Server-Library transaction and returned to a client application. (UniAccess System servers include the UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess Relational Server for DMS 2200). The server program messages are presented in two sections: UniAccess System Server Messages, which may be tailored by the system administrator, and UAHS Error Messages, which are not modifidable by the system administrator.

Sections Page

UniAccess System Server Messages B-2

UAHS Error Messages B-21

B-2 UniAccess for OS 2200 Client Guide


UniAccess System Server Messages

This section lists in numeric order the modifiable messages returned by UniAccess System servers. UniAccess System servers include Server-Library transactions, the UniAccess Relational Server (UARS) transaction, the UniAccess Hierarchical Server (UAHS), and the UAINFO transaction. These messages may be tailored by the system administrator. Information on how the system administrator can change the text of these messages, add messages, or modify the UADT mapping record can be found in Chapter 10 of the UniAccess for OS 2200 System Administration Guide.

103 String is too long (RDMS: %s)Reason: A string literal passed to RDMS 2200 is too long. The %s is the detailed

RDMS 2200 error message.Action: Reduce the length of the string literal and re-submit the SQL command.Applies: UARS only.

105 Unclosed quote (RDMS: %s)Reason: A string constant in an SQL command is missing a quote. The %s is the

detailed RDMS 2200 error message.Action: Refer to the Unisys OS 2200 Relational Data Management System

(RDMS 2200) SQL Programming Reference Manual for valid RDMS 2200 SQL syntax and resubmit the SQL command.

Applies: UARS only.

138 Illegal correlation clause in subquery (RDMS: %s)Reason: An invalid correlation name was used in a subquery. The %s is the detailed

RDMS 2200 error message.Action: Refer to the Unisys OS 2200 Relational Data Management System

The variables listed below are used in message text:

%s string%d decimal number%o octal number


Server Program Messages B-3


Applies: UARS only.

169 Columns specified in an ORDER BY list must be unique (RDMS: %s)Reason: An ORDER BY clause in an SQL command is incorrectly formatted. The

%s is the detailed RDMS 2200 error message.Action: Refer to the Unisys OS 2200 Relational Data Management System


Applies: UARS only.

207 Invalid column name (RDMS: %s)Reason: An invalid column name is specified in an SQL command. The %s is the

detailed RDMS 2200 error message.Action: Refer to the Unisys OS 2200 Relational Data Management System


Applies: UARS only.

208 Invalid object name (RDMS: %s)Reason: An invalid identifier was specified in an SQL command. The %s is the

detailed RDMS 2200 error message.Action: Specify a valid RDMS 2200 identifier and resubmit the SQL command.Applies: UARS only.

220 Arithmetic integer overflow (RDMS: %s)Reason: An arithmetic operation caused an integer overflow error in RDMS 2200.

The %s is the detailed RDMS 2200 error message.Action: Modify the arithmetic operation to eliminate the overflow condition.Applies: UARS only.

232 Arithmetic floating point overflow (RDMS: %s)Reason: An arithmetic operation caused a floating point overflow error in

RDMS 2200. The %s is the detailed RDMS 2200 error message.Action: Modify the arithmetic operation to eliminate the overflow condition.Applies: UARS only.



262 Execute permission denied to transaction %s.Reason: The VAR security system has rejected a request by a user to execute the

transaction. The first %s is the name of the transaction the user attempted to execute. The second %s is the userid for which the result was received. The %d is the PID allocated to the connection on which the result was received.

Action: Contact the security system administrator to coordinate transaction security for the indicated transaction and userid.

Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.

515 Attempt to insert NULL into column that does not allow nulls (RDMS: %s)Reason: An attempt was made to insert a null value into a column that is defined in

RDMS 2200 not to allow nulls. The %s is the detailed RDMS 2200 error message.

Action: Either insert valid data into the RDMS 2200 table or modify the table definition to allow nulls.

Applies: UARS only.

1909 Duplicate column name in index definition list (RDMS: %s)Reason: A duplicate column name was detected in an index definition list of a

create index command. The %s is the detailed RDMS 2200 error message.Action: Modify the create index command to specify unique column names and

resubmit the SQL command.Applies: UARS only.

1913 Duplicate index name found (RDMS: %s)Reason: An attempt was made to create an index using a name that was already in

use. The %s is the detailed RDMS 2200 error message.Action: Modify the SQL command to rectify the indicated problem and re-submit

the command.Applies: UARS only.

2601 Attempt to insert duplicate key (RDMS: %s)Reason: An attempt was made to insert a duplicate key into a column that is defined

as unique. The %s is the detailed RDMS 2200 error message.Action: Resolve the data problem and resubmit the SQL command.Applies: UARS only.



2714 Object already exists (RDMS: %s)Reason: An attempt was made to create an object using a name that was already in

use. The %s is the detailed RDMS 2200 error message.Action: Modify the SQL command to rectify the indicated problem and re-submit


2717 Column length specification is too large (RDMS: %s)Reason: A column length specification was larger than RDMS 2200 supports. The

%s is the detailed RDMS 2200 error message.Action: Modify your SQL command to specify a valid column length specification.Applies: UARS only.

3607 Divide by zero occurred (RDMS: %s)Reason: A divide by zero operation occurred. The %s is the detailed RDMS 2200

error message.Action: Modify your SQL command to eliminate the divide by zero operation.Applies: UARS only.

4002 Login attempt failed.Reason: Login validation failed in one or more OS 2200 security systems. The

reasons for failure include: 1) UniAccess user validation is configured and the userid specified is not configured in UniAccess. 2) TIP Session control is active and the userid/password specified is not a valid OS 2200 userid. 3) Local or third-party security is configured and the userid/password specified is not valid in the third-party security system (see Chapter 11 of the UniAccess for OS 2200 System Administration Guide).

Action: Specify a userid/password combination that is properly configured on the OS 2200 host, or have the OS 2200 system administrator configure a new userid in UniAccess, OS 2200, and/or the third-party security system.


4022 Password has expired -- You must change your password before you can continue.Reason: The password specified has expired. This occurs for the following reasons:

1) TIP Session control is active and the OS 2200 password has expired. 2) Local or third-party security is configured and the specified password has expired (see Chapter 11 of the UniAccess for OS 2200 System Administration Guide).



Action: OS 2200 and/or third-party security system password can be changed using standard OS 2200 security procedures. If the OS 2200 password has expired, the password can be changed directly from an Open Client application. Refer to page 4-4 for details.


4505 CREATE VIEW failed because number of columns exceeds maximum (RDMS: %s)Reason: Maximum number of columns in a view have been exceeded in a CREATE

VIEW command. The %s is the detailed RDMS 2200 error message.Action: Refer to the Unisys OS 2200 Relational Data Management System

(RDMS 2200) Administration Guide for RDMS 2200 limits.Applies: UARS only.

4506 Column names in view must be unique (RDMS: %s)Reason: A duplicate column name was used when attempting to create a view. The

%s is the detailed RDMS 2200 error message.Action: Modify the SQL command to rectify the indicated problem and re-submit


30000 UA service RDMS error (%s)Reason: Request failed. The cause is indicated by the RDMS 2200 message text in

the %s variable.Action: Refer to the RDMS 2200 documentation.Applies: UARS only.

30001 UA service RDMS warning (%s)Reason: The cause is indicated by the RDMS 2200 message text in the %s variable.Action: No action required. This is only a warning. For further information refer

to the RDMS 2200 documentation.Applies: UARS only.

30002 UA service DMS error (%d - %s)Reason: Request failed. The cause is indicated by the message text in the %s

variable.Action: Refer to the UAHS Error Message Section for further details. The %d

variable is the error message number in this section.Applies: UAHS only.



30004 UA service DMS error (DMS schema is not configured)Reason: A schema has not been defined for the current user.Action: Use the HIERSRV SCHEMA and/or UAUSER SCHEMAH Configuration

File parameters to define a default schema for the user (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Applies: UAHS only.

32000 UA service error (Library function [%s] returned [%d]: %.132s)Reason: The first %s is the UASL function that failed and the second %s is the

internal Server-Library error message. The %d is the internal Server-Library error number and is not defined in the UniAccess documentation set.

Action: The error message text will indicate the reason for the error. Resolve the problem and re-execute the request.


33218 UA service error (Rollback error - %s)Reason: UARS received an error while attempting to rollback. The %s contains

RDMS 2200 error information.Action: Refer to the RDMS 2200 documentation.Applies: UARS only.

33225 UA service error (SQL statement too long: length %d)Reason: The SQL request received from the client exceeds the maximum number of

characters allowed. The %d is the length of the request.Action: The client must limit requests to fewer than 16384 characters.Applies: UARS and UAHS only.

33227 UA service error (No SQL passed)Reason: No SQL was received from the client.Action: Resolve the problem and re-execute the request.Applies: UARS and UAHS only.

33228 UA service error (Character column data truncated when truncation not allowed in column %s)Reason: UARS retrieved a character column from RDMS 2200 with a length

greater than 255 bytes when UACS was set to prevent truncation of character columns. The application developer should be aware that



columns of type NCHARACTER require twice as many bytes of storage as their defined precision. The %s is the name of the column.

Action: Reset the truncation option when starting UACS, permit long character columns using the RELSRV/UAUSER LONGCHAR configuration parameter, or avoid fetching columns that exceed 255 bytes.

Applies: UARS only.

33229 UA service error (Internal error)Reason: UAHS, UAINFO, or UARS internal error.Action: Contact AIS Technical Support.Applies: UARS, UAHS, and UAINFO only.

33234 UA service error (Transactions cannot be labeled)Reason: A transaction statement included a label. UARS does not support labels

such as BEGIN TRAN mytran where mytran is a label for the transaction.Action: Modify the SQL command to rectify the indicated problem and re-submit

the command. If a transaction was in progress when UARS received the offending statement, it was ignored and the transaction continued. If a transaction was not in progress, then UARS issued a rollback and no transaction was begun.

Applies: UARS only.

33235 UA service error (Transaction must be ended before another transaction is begun)Reason: A BEGIN TRAN statement was sent to UARS before the current

transaction was terminated by COMMIT or ROLLBACK.Action: Modify the SQL command to rectify the indicated problem. This may

indicated a logic error in the client application. The transaction remains alive, waiting for the next SQL text to be sent.

Applies: UARS only.

33237 UA service error (Transaction cannot include batched SQL (semicolon delimited) statements.Reason: Batch SQL statements (multiple, semicolon delimited SQL statements)

were mixed with BEGIN TRAN or BEGIN TRANSACTION statements, or they were entered while a transaction was in progress.

Action: Modify the SQL command to rectify the indicated problem and re-submit the command. UARS issued a rollback and the current transaction was terminated.

Applies: UARS only.



33238 UA service error (Transaction cannot be initiated via RPC)Reason: An attempt was made to issue a BEGIN TRAN command via an RPC call.Action: Modify the SQL command to rectify the indicated problem and re-submit

the command. UARS issued a rollback and did not begin a transaction.Applies: UARS only.

33239 UA service error (User not allowed to initiate transaction)Reason: An attempt was made to initiate a transaction by a user who was not

configured to do so. The user’s UAUSER USERTRAN option was set to NO (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).

Action: Modify the SQL command to rectify the indicated problem or update the user’s UAUSER USERTRAN configuration parameter setting to YES and re-submit the command. UARS issued a rollback and did not begin a transaction.

Applies: UARS only.

33300 UA service error (Could not access system table)Reason: UAHS, UAINFO, or UARS could not access UADT.Action: The OS 2200 system administrator should load the UniAccess Fixed-gate

shared subsystem.Applies: UARS, UAHS, and UAINFO only.

33301 UA service error (User %s not configured in the user table)Reason: The userid specified by the client was not defined in UADT. The %s is

the userid specified by the client.Action: Use a userid that is defined in UADT, add a new userid to UADT or define

a default userid. See the UAUSER configuration statement in Chapter 16 of the UniAccess for OS 2200 System Administration Guide for details.

Applies: UARS, UAHS, and UAINFO only.

33302 UA service error (Too many columns specified: %d)Reason: The SQL request retrieved more than 255 columns of data. The %d is the

number of columns generated by the SQL request.Action: Modify the SQL request to retrieve 255 or fewer columns of data.Applies: UARS and UAHS only.



33303 UA service error (Memory allocation failed)Reason: UAHS, UAINFO, or UARS failed to dynamically allocate OS 2200

memory.Action: Contact AIS Technical Support.Applies: UARS, UAHS, and UAINFO only.

33304 UA service error (Unsupported verb specified: %s)Reason: An unsupported SQL verb was received by UARS or UAHS. The %s is

the invalid verb.Action: For a list of UARS supported command verbs, refer to Chapters 6 and 7.

For UAHS supported commands, refer to Chapters 9 and 10.Applies: UARS and UAHS only.

33305 UA service error (Procedure request [%s] treated as language request. Parameter [%d] is invalid)Reason: UARS or UAHS was called as an RPC and there were no parameters

specified, or non-character parameters were specified. The %s is the RPC name used to call UARS or UAHS. The %d is the number of the non-character parameter, or 0 if no parameters were specified.

Action: Pass one or more character parameters to UARS or UAHS when calling it via an RPC.

Applies: UARS and UAHS only.

33306 UA service error (Application %d not configured in UADT)Reason: UARS or UAHS attempted to retrieve application group information from

UADT at runtime and no information existed.Action: Refer to Chapters 5 and 6 in the UniAccess for OS 2200 System

Administration Guide for information about configuring application group information and loading it into UADT.


33307 UA service error (Invalid fixed-gate level: %x, %x)Reason: The level of UAHS, UAINFO, or UARS and the UniAccess Fixed-gate are

incompatible. The first %x is the Fixed-gate level that the UA Service transaction requires. The second %x is the actual level of the Fixed-gate.

Action: Install matching levels of the UniAccess Fixed-gate and UAHS, UAINFO, or UARS. Ensure that the UA Service transaction you wish to use has been installed in each applicable application group after an upgrade installation.

Applies: UARS, UAHS, and UAINFO only.



33308 UA service error (User translation routine returned error)Reason: One of the UARS or UAHS user translation routines returned a fatal error. Action: Review the user translation source code to determine the reason for the

error condition.Applies: UARS and UAHS only.

33309 UA service error (Invalid or missing product key)Reason: An attempt was made to initiate UAHS or UARS when the current product

key does not support this feature.Action: Verify that you have purchased the appropriate product version to use the

UAHS or UARS service. Verify your product key in the UniAccess Configuration File.


33310 UA service error (Invalid SET command option)Reason: A SET command was submitted to UARS or UAHS with an invalid option. Action: For a list of valid UARS and UAHS SET commands and their

options,UniAccess for OS 2200 Client Guide refer to Chapter 7 and Chapter 10 respectively.


33311 UA service error (Procedure request [%s] treated as language request. Unsupported verb [%s] found)Reason: UARS or UAHS was called as an RPC and the assembled character

parameters did not contain a supported verb. The %s is the RPC name used to call UARS or UAHS. The %s is the verb that was detected.

Action: For a list of UARS supported command verbs, refer to Chapters 6 and 7. For UAHS supported commands, refer to Chapters 9 and 10.


33400 UA service error (Maximum number of RDMS SP parameters exceeded [%d])Reason: An attempt has been made to execute an RDMS stored procedure with

more than 255 parameters. UARS only supports RDMS stored procedure with 255 or fewer parameters. The %d indicates the number of parameters used by the RDMS stored procedure.

Action: Modify the stored procedure to use 255 or less parameters.Applies: UARS only.



33401 UA service error (RDMS SP parameter mismatch, expected = [%d], received = [%d])Reason: The number of parameters received for an RDMS stored procedure does

not match the number of parameters required by an RDMS stored procedure. The first %d is the number of parameters required by the RDMS stored procedure. The second %d is the number of parameters received in the RPC request.

Action: Make the RPC request with the appropriate number of parameters.Applies: UARS only.

33402 UA service error (Bad RDMS SP parameter name received [%s])Reason: A named parameter was received for an RDMS stored procedure, but the

RDMS procedure did not include that parameter. The %s is the name of the parameter.

Action: Verify the names of the parameters for the procedure being executed.Applies: UARS only.

33403 UA service error (RDMS SP parameters must either all be named or unnamed)Reason: A combination of named and unnamed parameters was received.Action: Either name all parameters or none.Applies: UARS only.

33404 UA service error (RDMS SP [%s] parameter is [%s], received as [%s])Reason: The input/output characteristics of an RDMS stored procedure parameter

do not match the input/output characteristics of the parameter received from the client application. The first %s is the input/output characteristics of the RDMS stored procedure parameter. The second %s is the name of the RDMS stored procedure parameter. The third %s is the input/output characteristics of the parameter received from the client application.

Action: Send parameters with appropriate input/output characteristics.Applies: UARS only.

33405 UA service error (RDMS SP parameter conversion from [%s] to [%s] not supported)Reason: The incoming TDS RPC parameter type cannot be converted into the

corresponding RDMS stored procedure parameter type. The first %s is the TDS parameter data type. The second %s is the RDMS parameter data type.

Action: Refer to Chapter 6 for a list of supported RDMS stored procedure datatype conversions.

Applies: UARS only.



33406 UA service error (RDMS SP syntax not supported)Reason: This error occurs for two different reasons: 1) An attempt was made to call

an RDMS function that has a return value other than integer. 2) An attempt was made to call an RDMS stored procedure that contains an INOUT DATE, TIME or TIMESTAMP parameter.

Action: Modify the RDMS function to return only integer values. INOUT or OUTPUT parameters can be used to return other datatypes. Contact Unisys for information about support for INOUT DATE, TIME and TIMESTAMP parameters.

Applies: UARS only.

33407 UA service error (Null data received for RDMS SP parameter [%d] that does not support nulls)Reason: A null parameter was received from a client application for an RDMS

stored procedure parameter that does not support nulls. The %d is the number of the parameter.

Action: Only send null values for parameters that support null values.Applies: UARS only.

33408 UA service error (Invalid DECIMAL/NUMERIC RDMS SP parameter [%d])Reason: An invalid parameter was received from a client application for an RDMS

stored procedure DECIMAL or NUMERIC parameter. The parameter contained invalid DECIMAL/NUMERIC data. The %d is the number of the incorrectly formatted parameter.

Action: Refer to Chapter 6 for a list of supported RDMS stored procedure datatype conversions.

Applies: UARS only.

33409 UA service error (BLOB column [%s] precision [%d] exceeds user limit [%d])Reason: A SELECT command has included an RDMS BLOB column whose

precision exceeds the MAXBLOBSIZE parameter for the client. The %s is the BLOB column name, the first %d is the precision of the BLOB column and the second %d is the current MAXBLOBSIZE value for the client.

Action: The System Administrator may change the MAXBLOBSIZE value for the client (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide). Or, if user override for the MAXBLOBSIZE parameter is on (USERROVERRIDEON), the client may override the maximum BLOB size by using the SET BLOBSIZE command.

Applies: UARS only.



33410 UA service error ( [%s] exceeds maximum size of 30 characters for RPC name component)Reason: An RDMS stored procedure has been called using a name component

which exceeds the legal length of 30 characters. The %s identifies the invalid name component.

Action: Modify the RDMS stored procedure call to use a legal name component of 30 characters or less.

Applies: UARS only.

33702 UA service error (Invalid RPC parameter received)Reason: UARS or UAHS received an RPC parameter of an invalid datatype or

incorrect format on a catalog request.Action: For UARS, refer to Chapter 8 for a list of valid UARS RPC requests

(Catalog RPCs) and thier correct calling sequence. For UAHS, refer to Chapter 11. If the request was initiated by the UniAccess ODBC Driver, please report the problem to AIS.


33800 UACS error: Transaction (%s) schedule failed (cmstor failed %o)Reason: UACS failed in attempting to schedule a transaction. The %s is the name

of the transaction that failed to schedule and the %o is the return code from the CMS CMSTOR call.

Action: Refer to the Unisys OS 2200 Message Control Bank (MCB) Programming Reference Manual for information about the returned error code.


33801 UACS error: Unknown event (%d) requested for pid = (%d)Reason: Unrecognized TDS request received from client. The first %d is the

unrecognized TDS token. The second %d is the PID upon which the error was detected.

Action: Retry the request or determine the problem with the client.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.

33803 UACS error: Received (%s) request when such a request is not validReason: Invalid TDS request received from client. The %s is the type of TDS

request received.Action: Correct the client application and resubmit the request.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.



33804 UACS error: TIP$SM call failed (%o)Reason: With TIP session control active, the TIP$SM call failed. The %o is the

return code from the TIP$SM call.Action: Refer to the Unisys OS 2200 Transaction Processing Administration and

Operations Reference Manual for information about the returned error code.


33805 UACS warning: Shutdown in progress - request refused Reason: The OS 2200 system administrator has initiated a UACS shutdown.Action: Resubmit the request when UACS has been restarted.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.

33806 UACS error: TIP session control has terminated your sessionReason: The TIP session manager has detected a time-out condition due to

inactivity.Action: Terminate the current session with UACS and establish a new session.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.

33807 UACS error: UAMM function (%s) failed for transaction (%s) (%d)Reason: A UAMM function has failed. The first %s is the name of the UAMM

function that failed. The second %s is the name of the transaction. The %d is the UAMM error number.

Action: Refer to Appendix C: UAMM Detailed Error Messages, to determine the meaning of particular UAMM error codes.


33808 UACS error: Transaction error detected (%s)Reason: A transaction terminated abnormally. The %s is the name of the

transaction.Action: Determine why the transaction abnormally terminated and re-execute the

request.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.

33810 UACS error: No longer attached to MCB - Transaction Server unavailableReason: The MCB for which this UACS is configured has terminated and UACS is

no longer able to schedule transactions.Action: The system administrator must shutdown and restart UACS when MCB

becomes available.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.



33811 UACS error: Undefined transaction (%s) (%o)Reason: UACS received a request to start an invalid transaction. The %s is the name

of the transaction code. The %o is the MCB error code returned from the CMSTOR call.

Action: Ensure that the transaction is loaded and configured properly to TIP for the application group in which the UACS you are using is operating.


33812 UACS error: Maximum number of concurrent sessions for this application group has been reachedReason: UACS failed to establish a session for a new UATS connection when TIP

session control was configured.Action: Increase the number of concurrent sessions supported by this application

group or decrease the number of activities establishing sessions in this application group.


33813 UACS error: TIPTALK call failed (%o)Reason: An error occurred while attempting to establish a session with TIP session

control. The %o is the error code returned from the TIP$TALK call.Action: Refer to the Unisys OS 2200 Transaction Processing Administration and

Operations Reference Manual for an explanation of the TIP$TALK return code and correct the problem.


33814 Execute permission denied to transaction (%s)Reason: The security API returned a response type 4 to UACS as the result of an

attempt to schedule a transaction. The %s is the name of the transaction that failed to schedule.

Action: Verify security privileges with the security administrator.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.

33815 UACS error: MCB error (%o) starting VAR security transaction (%s)Reason: UACS failed in attempting to schedule the VAR security transaction. The

%o is the return code from the CMS CMSTOR call and the %s is the name of the transaction that failed to schedule.

Action: Refer to the Unisys OS 2200 Message Control Bank (MCB) Programming Reference Manual for information about the error code.




33816 UACS error: COMSRV entry (%s) is not configuredReason: A COMSRV record entry (%s) is not configured. Action: Insert the missing entry in the COMSRV record of the Site Configuration

File. The COMSRV UARSTRAN, UAHSTRAN, USERTRAN or UAINTRAN parameter is not configured. The %s indicates the parameter that is not configured. (See the COMSRV record in Chapter 16 of the UniAccess for OS 2200 System Administration Guide for a description of these configuration parameters.)


33817 UACS error: Invalid extended session request received, active trx=[%s], requested trx = [%s]Reason: When a client is operating in extended session, it may call many RPCs, but

all the RPCs must be serviced by the same transaction. The first %s is the name of the transaction currently servicing the client in extended session mode. The second %s is the name of the transaction that would service the request RPC if the client was not in extended session mode.

Action: Review the client protocol and correct it so as to make only valid extended session RPC calls.


33818 UACS error: (%s) permission is requiredReason: A request was received by UACS for a service that is not supported by the

current product key(s). The %s indicates the service that is not supported.Action: Verify that you have purchased the appropriate product version to use the

UAHS, UARS or UASL service. Verify your product key(s) in the UniAccess Configuration File.


33819 UACS error: Transaction timeout detected (%s), connection abortedReason: UACS detected that a transaction has not returned any result data in the

number of seconds defined in the NWWTIMOUT UniAccess Configuration File value. The %s is the name of the transaction code.

Action: If the transaction is functioning properly, increase the NWWTIMOUT value (See Chapter 16 of the UniAccess for OS 2200 System Administration Guide for a description of the configuration parameter.)




33820 UACS error: Catalog requests not supported by configured language transactionReason: An RPC catalog request was received when the current user’s language

transaction was either a user-written language transaction or no language transaction.

Action: For non-ODBC clients and pre-6R2 ODBC clients, the COMSRV DFLTTRAN value indicates the default language transaction to use (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide). If this is NONE or USERTRAN, the above error will result. For 6R2 ODBC clients and above, the Language Transaction Type determines the language transaction being used with the current data source (see Chapter 5). If this is No Language Transaction or User-Written Language Transaction, the above error will result.

Applies: UARS, UAHS, and site-written language transactions only.

33821 UACS error: Language requests not supported by current configurationReason: A language request was received by UACS, but the current user does not

have a language transaction configured.Action: For non-ODBC clients and pre-6R2 ODBC clients, the COMSRV

DFLTTRAN value indicates the default language transaction to use (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide). If this is NONE, the above error will result. For 6R2 ODBC and above clients, the Language Transaction Type determines the language transaction being used with the current data source (see Chapter 5). If this is No Language Transaction, the above error will result.


33822 UACS error: Invalid distributed transaction request received, active trx=[%s], requested trx = [%s]Reason: An enlisted client has made a request that requires the activation of a

second transaction. Enlisted clients must operate with only one server transaction, and this transaction must be terminated by the UADTC PREPARE/COMMIT or ABORT sequence of commands. The first %s is the name of the transaction currently servicing the enlisted client. The second %s is the name of the transaction that would service the request RPC if the client was not enlisted.

Action: Review the client protocol and correct so as to make only valid enlisted RPC calls.




33823 Distributed transaction completed. Enlist this session in a new transaction or the NULL transactionReason: The previous client transaction was a distributed transaction. Before

continuing, the client must define the new transaction mode. — A new distributed transaction must issue an ENLIST command.— A new non-distributed transaction must be designated by issuing an

UNENLIST command.Action: Review the client protocol and correct it to issue the appropriate ENLIST/

UNENLIST command.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.

33824 UACS error: [%s] Reason: An error occurred while attempting to establish a session with TIP session

control using a new password. The %s is the error explanation returned from the TIP$TALK call. For example, an attempt to change the password to a string containing a slash character will return the following:

Msg 33824, Level 15, State 0 Server UACS, Line 0. [The new password you entered contains invalid characters.]

Action: Refer to the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual for an explanation of the TIP$TALK diagnostic, and correct the problem.


33825 Connection terminated - Configured session limit has been exceededReason: UAFG has no available process slots to accept a new connection.Action: Update the UAMM PROCCNT value to increase the number of available

process slots (see Chapter 16 of the UniAccess for OS 2200 System Administration Guide).


33826 Connection terminated - [%s] product key session limit has been exceeded Reason: UAFG has available process slots, but the maximum concurrent use of the

product keys has been reached. The %s identifies those product keys which have reached their maximum session use.

Action: Contact AIS Technical Support about upgrading product keys.Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.



33827 Trx [%s] not scheduled - [%s] product key not active for this session Reason: A connection has attempted to schedule a transaction for which the

connection has no active service. Services are identified at connection time and counted against the product key session limits. The first %s is the VALTAB of the transaction that could not be scheduled due to product key connection limitations. The second %s is the product whose product key has the limitations.

Action: Reconfigure the connection’s DSN or connection string to specify the use of the required service.




UAHS Error Messages

UAHS error messages are generated by the UAHS transaction and returned to the client application embedded within Server Program Messages. UAHS error messages concern problems with either the client input or the UAHS environment. These messages are built directly into the UAHS transaction and are not modifiable by the system administrator.

UAHS error messages have the following format:

UA service DMS error ( msgnum - msgtext)

where:

msgnum is the error message number listed below

msgtext is the message text listed below

1 Invalid command verbReason: UAHS only supports the SQL SELECT command. It also supports the

client environment-related SET, UAHSINFO, UAINFO and USE commands. The command processed was none of the above.

Action: Resubmit the request with the appropriate command.

2 Memory allocation errorReason: System memory resources on the 2200 mainframe are such that UAHS has

been forced to reject the client request due to lack of available memory.Action: Resubmit the request, if the problem persists, consult 2200 technical

support to determine why memory is unavailable.

The variables listed below are used in message text: %s fields are character string values %d fields are decimal integer values %o fields are octal integer values



3 Internal errorReason: UAHS has encountered an internal error.Action: Contact AIS technical support.

4 Select list arithmetic expressions are not supportedReason: As stated.Action: Correct the SELECT request to specify legal select list criteria and

resubmit the request.

5 Select list set function references are not supportedReason: As stated.Action: Correct the SELECT request to specify legal select list criteria and


6 Select list parenthesis are not supportedReason: As stated.Action: Correct the SELECT request to specify legal select list criteria and


7 Select list signed expressions are not supportedReason: As stated.Action: Correct the SELECT request to specify legal select list criteria and


8 Only 1 ORDER BY column is supportedReason: UAHS only supports 1 column when producing ordered rows.Action: Correct the SELECT request to specify only 1 ORDER BY column and


9 Syntax error at or before [%s]Reason: The SQL statement contains incorrect SQL syntax. The parser has

encountered an error in the SQL statement at or prior to the point specified by the token [%s]. The [%s] identifies the offending syntax token, and displays the SELECT statement with "^^" inserted at the syntax error.

Action Examine the SELECT statement, make the necessary corrections, and resubmit the request.



10 Parse stack overflowReason: The parser could not allocate memory for the state stack. The state stack is

used by the parser to maintain a history of the states that the parser has passed through while parsing the input string.

Action: Contact AIS Technical Support.

11 Invalid SQL database name [%s]Reason: The SQL database name does not exist in the MDB. The name may be

misspelled. The [%s] displays the database name that was submitted. Action: Verify that the database name is correctly spelled. If incorrect, correct the

name and resubmit the request. If correct, the database must be incorporated into the MDB using the TABLEDEF utility and the DEFINE DATABASE command

12 Invalid table name [%s]Reason: The table name does not exist in the MDB. The name may be misspelled.

The [%s] displays the table name that was submitted. Action: Verify that the table name is correctly spelled. If incorrect, correct the name

and resubmit the request. If correct, the table must be incorporated into the MDB using the TABLEDEF utility and the CREATE TABLE command.

13 Invalid column name [%s]Reason: The column name does not exist in the MDB. The name may be

misspelled. The [%s] displays the column name that was submitted. Action: Verify that the column name is correctly spelled. If incorrect, correct the

name and resubmit the request. If correct, the column must be incorporated into the MDB using the TABLEDEF utility and the CREATE TABLE command.

14 Invalid WHERE column name [%s]Reason: The column name does not exist in the MDB. The name may be

misspelled. The [%s] displays the column name that was submitted. Action: Verify that the column name is correctly spelled, If incorrect, correct the

name and resubmit the request. If correct, the column must be incorporated into the MDB using the TABLEDEF utility and the CREATE TABLE command.



15 Limit of [%d] tables exceededReason: UAHS has a maximum limit on the number of tables that may be submitted

as part of the SELECT request. This limit is currently 3. The [%d] is the maximum number of tables.

Action: Resubmit the request using no more than 3 tables.

16 Table [%s] needs qualification by correlation nameReason: The same table name has been included more than once in the table

reference list without the use of a correlation name. UAHS cannot determine which table occurrence should be used to extract column data to satisfy the SELECT clause. The [%s] is the offending column name.

Action: Use a correlation name to qualify column and table names and resubmit the request.

17 Unqualified column [%s] is not uniqueReason: UAHS has determined that an unqualified column name has been

requested. The column name exists in more than one table. The [%s] is the offending column name.

Action: Review SELECT command, qualify the offending column name with the table name, and resubmit the request.

18 SELECT DISTINCT only supports 1 database columnReason: As stated.Action: Review SELECT command, reduce select list to 1 column and resubmit the

request.

19 Invalid ORDER BY column number [%s]Reason: The ORDER BY clause has specified a column number, but this number

exceeds the number of columns in the select list. The [%s] is the offending column number.

Action: Review SELECT command, choose a legal column number, and resubmit the request.

20 Invalid numeric data WHERE column [%s], data [%s]Reason: The WHERE column is a numeric column and literal data has been

submitted for comparison. The first [%s] identifies the offending WHERE column; the second [%s] identifies its associated data.

Action: Review the SELECT command, choose legal numeric WHERE column data, and resubmit the request.



21 Invalid literal data WHERE column [%s], data [%s]Reason: The WHERE column is a character column and numeric data has been

submitted for comparison. The first [%s] identifies the offending WHERE column; the second [%s] identifies its associated data.

Action: Review SELECT command, choose legal literal WHERE column data, and resubmit the request.

22 Incompatible WHERE columns [%s], [%s]Reason: Two WHERE columns have been submitted for comparison, but 1 column

is character and the other column is numeric. The two [%s]s identify the offending where columns.

Action: Review the SELECT command, choose legal WHERE column data, and resubmit the request.

23 Incompatible WHERE datatypes [%s], [%s]Reason: A numeric and character literal have been submitted for comparison. The

two [%s]s identify the offending input data.Action: Review the SELECT command, choose legal datatypes, and resubmit the

request.

24 Invalid literal test condition [%s]Reason: Legal test conditions for literals are EQ, GT, LT, GE, LE or NE. LIKE/

NOT LIKE may only be used when comparing a CHARACTER column to a literal.

Action: Correct the syntax and resubmit the SELECT request.

40 Area search capability needed to access databaseReason: UAHS has determined that there is insufficient criteria in the WHERE

clause to construct a key to access the DMS data. This being the case, UAHS must perform an area search of the database to satisfy the SELECT request. This process may be a time consuming. The requesting client does not have the necessary privilege to force an area search.

Action: Resubmit the SELECT command with sufficient WHERE conditions to avoid error conditions. If this is not possible, the client should have the area search capability enabled.



41 DMS DML error [%s]Reason: UAHS has encountered an unexpected DMS error. The [%s] reports on the

type of DMS error and on the DMS function being performed at the time.Action: Consult with database administrator to determine the proper course of

action, based on the DMS error.

42 UAHS error [%s]Reason: UAHS has encountered an unexpected error. The [%s] reports on the type

of error.Action: Contact AIS technical support.

43 MDB internal error, record number: [%o]Reason: UAHS has encountered an unexpected MDB error. The [%o] is the octal

MDB record number that could not be read. Action: Verify the MDB with @XQT,MR SCHEMADEF. If this fails make a

copy of the bad MDB for further analysis and re-initialize MDB with @XQT,I SCHEMADEF. Note that if the MDB is re-initialized, then all tables must be recreated using the TABLEDEF utility.

44 Error opening MDB file, List File error status = [%o] Reason: An error has occurred during an attempt to retrieve the file characteristics

for the MDB file. The error code can be found in the FCSS Status Codes appendix of the Unisys OS 2200 Transaction Processing Programming Reference Manual. A probable cause is that the MDB file is not registered with TIP as an FCSS file. The [%o] is the octal FCSS error code

Action: Examine the error code. Verify that the MDB exists as an FCSS file. If it doesn’t, register it as an FCSS file.

45 MDB FCSS TIP I/O error [%o]Reason: A system I/O error has occurred. The error code can be found in the FCSS

Status Codes appendix of the Unisys OS 2200 Transaction Processing Programming Reference Manual. Possible causes are that the MDB has not been created as an FCSS file, a hardware error has occurred, or a system error has occurred. The [%o] is the FCSS error code

Action: Examine the error code. Verify that the MDB exists as an FCSS file. If it doesn’t, register it as an FCSS file. If a hardware error has occurred, recover MDB after the hardware error has been resolved. If a system error has occurred, consult with your systems group for a resolution.


C UAMM Error Messages

C UAMM Error Messages

This appendix lists the error codes returned by UniAccess Message Manager (UAMM). These error codes are embedded in UACS and UASL program messages. UAMM can return both General and Detailed error message information. The message text containing the message or the description of the message in the documentation will indicate whether the message is a General or Detailed UAMM error message.

UAMM General Error Messages

1 Close request failed — library error %d

2 Connect request failed — library error %d

3 Receive request failed — library error %d

4 Unsupported driver operation called

5 Send request failed — library error %d

6 Initialization request failed — library error %d

7 Accept request failed — library error %d

8 Exit request failed — library error %d

Sections Page

UAMM General Error Messages C-1

UAMM Detailed Error Messages C-2

C-2 UniAccess for OS 2200 Client Guide


UAMM Detailed Error Messages

1 UAMM is already initialized.

2 Error encountered attempting to create the Management Bank.

3 Error encountered attempting to create the Process Storage Bank.

4 Error encountered attempting to create the Memory Allocation Bank.

5 Error encountered attempting to create the Primary Storage Bank.

6 Error encountered attempting to reference Secondary Storage.

7 Attempted to allocate a MMPROC but none were available. This error can occur when a site has exceeded its allowable PID configuration limit or when a site has hung UAMM processes (mmprocs).

If the error is due to exceeding the PID configuration limit, increase the number of PIDs in the COMSRV parameter of the site configuration file, if permitted. If the error is due to hung mmprocs, deactivate the fixed-gate and reactivate it. If this occurs regularly, verify that the site configuration file UAMM PROCCNT is set high enough.

8 UAMM is not initialized.

9 Client has errored or been errored by another process.

10 Primary banks are full. No memory available to allocate for messages.

11 Illegal access attempted. User program rejected.

12 The maximum number of UACS processes are attached. Connect rejected.

13 Invalid UACS identifier. Client possibly corrupted.

14 Error encountered attempting to create the MMq Bank.


UAMM Error Messages C-3

15 Attempt to release the UACS MMq failed.

16 MMq is full. Attempt to write a queue item failed.

17 Client has an invalid UAMM identifier.

18 An attempt to read from or write from the network failed.

19 Client received an event to read however no message was available.

20 Attempt to read a storage block failed.

21 UACS connect failed. A UACS with this name is already attached.

22 Attempted to allocate a context but none were available. This error can occur when a site has exceeded its allowable PID configuration limit or when a site has hung UAMM processes (mmprocs).

If the error is due to exceeding the PID configuration limit, increase the number of PIDs in the COMSRV parameter of the site configuration file, if permitted. If the error is due to hung mmprocs, deactivate the fixed-gate and reactivate it. If this occurs regularly, verify that the site configuration file UAMM PROCCNT is set high enough.

23 This UACL client has already initialized. ipd_init failed.

24 The UACS this client was communicating with is no longer available.

25 Attempt to register for termination failed.

26 Attempt to deregister for termination failed.

27 The UACS name requested by this UACL client is not attached.

28 Attempted to allocate a CSPROC but none were available.

29 Attempted to mmclose a UAMM process that is not in use.

C-4 UniAccess for OS 2200 Client Guide


30 Attempted to read page zero.

31 Network error. Check UACS trace file for error information.

32 Attempted to exceed maximum allowable number of endpoints.

33 Attempted to open more client connections than allowed by the product key.


D Troubleshooting

D Troubleshooting

This appendix provides troubleshooting assistance with common errors users have encountered while setting up the PC environment.

UADriver ToolsUniAccess ODBC Driver offers several features to assist in troubleshooting in the Windows/UADriver environment. These features are described in this section.

Test Options

UADriver offers two tests to troubleshoot connectivity problems—the Host Connectivity Test and the Transaction Coordinator Connectivity Test (for UADTC).

Topics Page

UADriver Tools D-1

Test Options D-1

Tracing Options D-7

UADTC Logging D-10

Troubleshooting D-12

UADriver Issues D-12

UADTC Issues D-16

Technical Support D-18

D-2 UniAccess for OS 2200 Client Guide


To test the connectivity of a data source, open the UADriver Setup dialog box through the ODBC Data Source Administrator. On the General tab, specify a DSN, host, and port. Then click on the Test dialog. The Test tab, illustrated in Figure D-1 will open.

Figure D-1: UADriver Test Dialog

Host Connectivity Test

If you are experiencing problems connecting to the OS 2200 host from your ODBC application, you can use the Host Connectivity Test option under the Test tab of the UADriver setup dialog to help diagnose your problems. The Host Connectivity Test will perform a series of tests and provide an analysis of the results of those tests. The test analysis will assist you in solving your connectivity problems.


Troubleshooting D-3

To initiate the Host Connectivity Test, enter the values for Userid and Password:

UseridEnter your Login ID (case sensitive). If UniAccess security is active, this must be a valid UniAccess userid. If OS 2200 TIP session control is active, this must be a valid OS 2200 userid.

PasswordEnter your password for the system (case sensitive). If OS 2200 TIP session control is active, this must be a valid OS 2200 password. If the UniAccess Security API is in use, this password must be valid for the local security system.

The following is a description of the Host Connectivity Test results.

Test Parameters

DSNThe name of the DSN being tested.

UseridThe userid used to logon to UACS.

CommandThe language command issued during the test. This is generated using the ODBC.INI LanguageType parameter of the selected DSN.

IP Address/Host NameThe IP address or host name used for the test. This is determined using the ODBC.INI host parameter of the selected DSN.

PortThe port used for the test. This is determined using the ODBC.INI port parameter of the selected DSN.



Test Summary

Winsock Connection TestThis test attempts to send several bytes of data to the configured UACS using the Winsock DLL. Successful test results indicate that operating system level Winsock DLLs are properly installed on the test workstation and TCP/IP connectivity exists. Note that this test will only be performed on environments where the Windows Socket network-library DLL is being used.

Open Client DLL Load TestThe test attempts to load the two Open Client DLLs: libcs.dll and libct.dll. Successful test results indicate that these two DLLs are locatable in the search path of the test workstation.

Client-Library Connection TestThis test attempts to logon to the configured UACS and send several bytes of data using Open Client DLLs. Successful test results indicate that Open Client DLLs are properly installed, connectivity to UACS exists, and a userid is properly configured in UniAccess and/or OS 2200.

Client-Library/UA Transaction TestThis test attempts to logon to the configured UACS and send a language request to the configured language transaction (or UAINTRAN) using Open Client DLLs. Successful test results indicate that Open Client DLLs are properly installed, connectivity to UACS exists, a userid is properly configured in UACS and/or OS 2200, and the host-based language transaction is installed and functioning properly.

ODBC/UA Transaction TestThis test attempts to logon to the configured UACS and send a language request to the configured language transaction (or UAINTRAN) using UADriver. Successful test results indicate that Open Client DLLs and UADriver are properly installed, connectivity to UACS exists, a userid is properly configured in UACS and/or OS 2200, and the host-based language transaction is installed and functioning properly.


Troubleshooting D-5

Configuration Override CheckThis test verifies that all UADriver options that are set to override default UniAccess Configuration File values can actually be overridden. If an attempt is made to override any UniAccess Configuration File values that the user does not have permission to override, this test will fail and the option(s) that caused the override check to fail are listed under the Configuration Override Check Failures section.

Client Environment Variables

SYBASEThis is the value of the SYBASE environment variable that was obtained during the test. This value must be set.

LC_ALLThis is the value of the LC_ALL environment variable that was obtained during the test. This value typically only needs to be set when non-English environments are being used. If the version of Windows being used specifies a locale other than United States, this value must be set to enu, or the Sybase message matching the locale must be installed.

DLL VersionsThis section lists the versions of the ODBC and UADriver DLLs.

Host Environment Information

This section lists the information that was returned by the language transaction that was selected. Results will vary depending on the language transaction selected, but version and connection information will be included. All options that can be overridden by UADriver are indicated with a USEROVERRIDEON parameter.

Configuration Override Check Failures

This section is only displayed when an attempt is made to override UniAccess Configuration File values that the user does not have permission to override. The option(s) that caused the override check to fail are listed here.




If you are experiencing problems connecting to UADTC (the UniAccess Distributed Transaction Coordinator) from your ODBC application, you can use the Transaction Coordinator Connectivity Test option under the Test tab of the UADriver setup dialog to help diagnose your problems. The Transaction Coordinator Connectivity Test will attempt to connect to UADTC and will provide an analysis of the results. The test analysis will assist you in solving your connectivity problems.

NoteBefore performing this test, the Support Distributed Transaction option must be configured in the UADriver Setup / Advanced Setup dialog. In addition, if UADTC is running remotely, the location of UADTC must be configured in the same UADriver Setup dialog.

The following is a description of the Transaction Coordinator Connectivity Test results.

Test Summary

UADTC LocationThe UNC or DNS name of the machine on which UADTC is located. Local host is displayed if UADTC is on the same machine as UADriver.

MSDTC LocationThe IP address of the machine on which Microsoft DTC is located. If the Microsoft TIP Support test is not run, this will not be determined.

COM/DCOM SupportThis test attempts to initialize with COM. Successful test results indicate that basic COM/DCOM support is available.

Microsoft DTC SupportThis test attempts to call the Microsoft DTC application programming interfaces (APIs). Successful test results indicate that Microsoft DTC is installed and configured properly.


Troubleshooting D-7

Microsoft TIP SupportThis test attempts to call the Microsoft DTC Transaction Internet Protocol (TIP) API extensions. Successful test results indicate that Microsoft DTC TIP support is installed and configured properly.

UADTC Proxy SupportThis test attempts to create an instance of the UADTC helper class. Successful test results indicate that the UADTC proxy is installed and that the UADTC service is running and is configured properly.

UADriver to UADTC ConnectivityThis test attempts to establish a COM connection between this machine and the UADTC machine. Successful test results indicate that network connectivity exists between the UADriver machine and the UADTC machine.

UADTC to MSDTC ConnectivityThis test attempts to establish TCP/IP connectivity between the UADTC machine and the MS DTC machine. Successful test results indicate that the TCP/IP network connectivity exists between the UADTC machine and the MS DTC machine.

UADTC to Host ConnectivityThis test attempts to establish connectivity between the UADTC machine and the UniAccess host machine. Successful test results indicate that TCP/IP network connectivity exists between the UADTC machine and the Host.

Tracing Options

Two tracing options are available through UADriver—the general tracing feature and UAHS debugging. These options are described below.

UADriver Tracing

If you are experiencing problems with your ODBC application after you have established connectivity to the OS 2200 host, you can use the UADriver Tracing feature to help diagnose your problems. This tool logs the function calls and function results between an ODBC application and UADriver. It can be used to better understand the interaction



between an ODBC application and UADriver or it can be used to debug a problem.To test the use the UADriver Tracing feature, open the UADriver Setup dialog box through the ODBC Data Source Administrator. On the General tab, specify a DSN, host, and port. Then click on the Tracing tab. The Tracing dialog, illustrated in Figure D-2 will open.

Figure D-2: UADriver Tracing Dialog


Troubleshooting D-9

On the Tracing dialog, enter the values described below:

Log File PathDisplays the path and file name for the file that the tracing information will be stored in. The default path and file name (UADriver.log) is displayed initially, but a new file can be specified by either entering a new path and file name, or choosing the Browse button and selecting a directory and file. This option is shared across UADriver DSNs. Changing this setting will change the setting for all UADriver DSNs. This option is disabled if you are using Windows NT and you do not have local administrator privileges on your system.

When To TraceThe Activate tracing on next UADriver load option will cause all UADriver function calls to be traced to the file defined in the Log File Path entry. The tracing will begin the next time UADriver is loaded.

After you have reproduced your problem, turn off tracing. Then use a text editor like Notepad to examine the contents of the log file you just created. If you cannot diagnose the problem from the results contained in the log file, retain the file for use when you contact AIS technical support.

UAHS Debug Information

UAHS provides a debug facility to assist in determining mapping problems. The debug facility compliments the Language Trace File (available to the System Administrator through UACS CONS commands). Whereas the Language Trace File contains all SQL passed to the language transaction, the UAHS debug facility provides information about how the SQL is handled. This information includes the results of parsing the SQL command and the path used to access the DMS data.

The UAHS command SET DEBUG {ON | OFF} controls the debug facility. In addition, ODBC clients may configure the UAHS debug facility from the UADriver Setup dialog. Setting the option Activate Host Debugging to YES will enable UAHS debugging by default. The UAHS debug trace output will appear in the UAHS transaction print file.

The default debug setting for the user and the ability to override this option are determined by the OS 2200 UniAccess Configuration File HIERSRV/UAUSER DEBUG setting (see Chapter 16 in the UniAccess for OS 2200 System Administration Guide).



UADTC LoggingUADTC logging is enabled by starting the UniAccess DTC Manager and selecting the following UADTC settings:

1. In the left pane of the UADTC Management Console, expand UADTC. Expand Computers. Select the computer on which you are managing UADTC.

NoteIf UADTC is not running on the local computer, you will need to add the remote computer.

2. Open the Action menu and select Properties. (You can also right-click on the computer and select the Properties option from the menu.)

3. You can adjust the logging options, service options, host connection options, and the display refresh rate.

4. Select OK. A window will be displayed indicating that you must stop and start the service for the change to take place. Select OK again.

5. Stop and start the UADTC service. This can be done through the Action menu, by selecting Properties. (You can also right-click on the computer and select the Properties option from the menu.)

On the UADTC Configuration Options dialog (see Figure D-3), enter the values described below:

Log File DirectoryThis optional value specifies the location of the UADTC log file. A new log file will be created every day with the following format:uadtcyyyyddd.log. If no directory is specified, the default directory of%WinDir%\System32\LogFiles\UADTC\ is used.

Log File LevelThis value specifies the threshold for the log information to be traced.Options are Low, Medium, and High. The default value is Low.



Figure D-3: UADTC Configuration Options Dialog



TroubleshootingThe following are solutions to commonly reported problems from Windows-based PC clients using the UniAccess ODBC Driver. The section lists up-to-date troubleshooting tips for the current release. However, this list will likely continue to grow as new questions emerge on the latest release. The latest updates can be read by visiting http://www.uniaccess.com. A copy of the latest updates can also be obtained by sending an email to [email protected].

UADriver Issues

! Problem: Unable to connect to Data Source message. When you attempt to login to UACS you receive the message:

[AIS][UniAccess ODBC Driver]Unable to connect to data source[AIS][UniAccess ODBC Driver][lay=5 sev=5 org=3]ct_connect():network packet layer:internal net library error: Net-lib protocol driver call to connect two endpoints failed[AIS] [UniAccess ODBC Driver][lay=5 sev=5 org=3]Failed to connect to server - Error is 10061

or

Open Client Error: ct_ connect(): network packet layer: internal netlibrary error: Net-Lib protocoldriver call to connect two endpoints failedOperating System Error: Failed to connect to the server - Error is 2

Solution: There are several potential causes of this problem. First, verify that UACS is running. Then address the following issues.

Ensure that UADriver is to retrieve the system environment variable settings that were updated as a result of the UADriver installation. Assuming that UADriver was installed in c:\Program Files\Applied Information Sciences\Ua10r3, do the following:

• On Windows NT and above, verify that system environment variables are set as indicated below and that the system was rebooted following the installation.




SYBASE=c:\Program Files\Applied Information Sciences\Ua10r3

PATH=c:\Program Files\Applied Information Sciences\Ua10r3\dll;....

• On Windows 2000 and above, verify that the system was rebooted following installation and that the path and the Sybase environment variables have been updated with the UniAccess ODBC Driver installation directory.

Ensure that the connection address information (I.P. address/host name and port) is correct.

• Verify the UADriver Setup IP Address/Host Name and Port in the ODBC Data Source Administrator.

• Run the UniAccess ODBC Test utility. This utility is run by selecting the Test button from the UADriver Setup dialog box through the ODBC Data Source Administrator. Verify that the Test Summary output is SUCCESS and that the Client Environment Variable SYBASE is set to the UADriver installation directory (\Program Files\Applied Information Sciences\Ua10r3).

Verify that you have write privileges to the default temp directory. The UADriver creates a temporary file in the default temp directory. As a result, the user needs write privileges to this directory. The location of the temp directory can be different depending on whether the DSN is a system or user DSN. For file DSNs, the user needs to be granted write privileges to the directory that contains the file DSN.

! Problem: Unable to Allocate the ODBC Environment. When you attempt to login to UACS you receive the message: "[Microsoft][ODBC Driver Manager] Driver’s SQLAllocHandle on SQL_HANDLE_ENV failed."

Additionally, a SYBINIT.ERR log may be generated in the windows system directory containing the error: "The context allocation routine failed when it tried to load localization files!!"



Solution: This could indicate that the language being used does not match the languages installed with UADriver and is usually solved by adding the statement listed below, depending on the platform.

• On Windows NT and above, create a system environment variable with the following setting, which can be verified by issuing the SET statement from the command prompt.

LC_ALL=enu

• On Windows 2000 and above, add the following line to the AUTOEXEC.BAT file:

set LANG=enu

Reboot the system.

! Problem: A CTlib client cannot access Sybase SQL Server after accessing UniAccess. The error generated is:

SQLState - 08001[INTERSOLVE][ODBC SQL Server driver][SQL Server]ct_connect(); directory service layer; internal directory control layer error; Requested server name not found.

Solution: Beginning with the 9R1 version of the driver (2.08.000x), set the option 'Load Open Client Interfaces File' under the Advanced Tab option of the UADriver setup.

! Problem: The UADriver traces do not get captured when tracing is activated.

Solution: Verify that the user has change privileges to the directory where the trace is being captured and user priviledges to update the registry entry.

! Problem: Trouble with Catalog RPCs

Solution: When problems with the Catalog RPCs arise, contact your system administrator to verify that, for UARS, the UniAccess Relational Service



for RDMS 2200 has been installed and that the UNIACCESS1S1 RDMS 2200 schema information has been generated. For UAHS, verify that the UniAccess Hierarchical Service for DMS 2200 has been installed.

! Problem: Trouble creating tables

Solution: When tables are dropped that were created using the implicit storage area feature of RDMS 2200, the underlying storage area that is automatically created by the CREATE TABLE command is not dropped. This creates a problem if an attempt is made to recreate the table. The storage area must be manually deleted before attempting to recreate the table. (See the section Creating a Table with an Implicit Storage Area in the Unisys OS 2200 Relational Data Management System (RDMS 2200) Administration Guide for more details on implicit storage area creation.)

Implicit storage area creation can be overridden by specifying a Storage Area when a UniAccess data source is configured. This storage must be created by the OS 2200 system administrator before any table creation commands can be issued. All tables created using the UniAccess data source will be placed in the storage area specified in the Storage Area field. (See page 5-24 for a description of the UADriver StorageArea option; see page 6-8 for an explanation of how UADriver uses the StorageArea setting.)

! Problem: No catalog information available for existing objects

Solution: When UniAccess catalog procedure requests do not return information about schemas, tables, and views that are known to exist in RDMS 2200, the RDMS 2200 administrator should verify that the Unisys Repository Manager (UREP) is maintaining information for these objects. When the UniAccess Relational Service is installed, a UREP configuration is performed to force UREP to track detailed meta-database information about all objects in RDMS 2200. Information may not be available to the Relational Service about objects that were created prior to performing the UREP configuration modification.

To provide the UniAccess Relational Service with meta-database information about objects that were created prior to the Relational Service installation, the RDMS 2200 administrator should use the UREP PROCESS



command to gather detailed object information. (See the Unisys OS 2200 Repository Manager (UREP) Programming Reference Manual for further details on the UREP PROCESS command.)

UADTC Issues

! Problem: Windows Server 2003 SP1 Disables MS DTC Network Access

Solution: To enable MS DTC network access:

• Open the Component Services MMC snap-in.

• Click Component Services, click Computers, and then click My Computer.

• Right-click My Computer and click Properties.

• Click the MS DTC tab and click Security Configuration.

• Select the Network DTC Access check box and configure the settings.

! Problem: Windows XP and Windows Server 2003 do not support TIP protocol by default.

Solution: Windows XP and Windows Server 2003 disable TIP protocol by default. Prior to attempting to use UADTC, TIP protocol must be enabled. Steps to enable the TIP protocol are:

• Start, Control Panel, Administrative Tools, Component Services.

• Expand Component Services.

• Expand Computers.

• Right click on the computer on which you wish to enable TIP, select Properties, select the MSDTC tab.

• Click on Security Configuration.



• Check the box "Transaction Internet Protocol (TIP) Transactions.

• Click OK.

• Click OK.

• Click OK.

• Close the Component Services window.

! Problem: UniAccess distributed transactions may cause system hang (EXERR-410).

Solution: Install the changes associated with EXEC PLE 17674544.

! Problem: UADTC service cannot be started

Solution: Check the Event Viewer Application Log for any UADTC events. This error usually happens when the UADTC service is unable to bind to port previously assigned to it by the operating system. In other words, the port UADTC is trying to bind to has already been assigned to another application. To correct this problem, using UADTC snap-in, reset the listen port to 0. This will cause the UADTC service to request a new port at startup.

Note that changing the listen port can potentially cause the previously active transactions to remain unresolved as MSDTC may try to connect to the previously assigned UADTC port. If this is a concern, stop the application that has been assigned the UADTC listen port and restart the service.

If the service is failing to start after the initial install of the service, reboot your system and attempt to start the service again.



! Problem: Failed to register transaction with MSDTC or UDS

Solution: This error means that the participating UASL transaction was unable to register itself with MS DTC. This error usually happens if the UADTC service is currently stopped. Another reason this error may occur is when the UDSBDI parameter specified in UniAccess Configuration File is incorrect.

! Problem: The Transaction Coordinator Connectivity UADTC Proxy Support test fails in the ODBC Administrator with the following error: "Unable to create an instance of the UADTCTIPHelper class. Error code 0x80070005 Description: Access is denied".

Solution: Verify that the UADTC service is started. The UADTC service must be running in order for the UADTC Proxy Support test to be successful.

Technical SupportBefore contacting Technical Support, you should check your manual and the Help system. If you still cannot solve the problem, you can obtain product support in several ways:

E-mail Help

Ask questions and receive answers from the UniAccess Technical Support Department via the Internet. Just send email addressed to [email protected] . You will receive a reply via E-mail.

Technical Support is provided for registered users. Be sure to include your UniAccess Product Registration Key in the E-mail.

WWW Help

Review the latest product release announcements, search the knowledge base, read numerous product-related articles, view our online demos and download the latest software at our web site, http://www.uniaccess.com.

To download software or access our online demos, you must request a userid and password from our sales or technical support staff.



E References

E References

This appendix contains a list of books, manuals, and Web sites that provide further information about products discussed in the UniAccess Documentation set. The list includes references for use at both the client and the host. A publication number is given to facilitate ordering.

AIS ReferencesUniAccess for OS 2200 Client Guide. AIS Release 10R3, Document Version:

1.00.

UniAccess for OS 2200 Client-Library Programming Reference. AIS Release 10R3, Document Version 1.00.

UniAccess for OS 2200 Server-Library Programming Reference. AIS Release 10R3, Document Version: 1.00.

UniAccess for OS 2200 System Administration Guide. AIS Release 10R3, Document Version: 1.00.

Topics Page

AIS References E-1

Microsoft References E-2

Sybase References E-2

Unisys References E-2

E-2 UniAccess for OS 2200 Client Guide


Microsoft ReferencesFor Microsoft manuals and technical papers, visit the following Microsoft technology home pages on the World Wide Web:

Microsoft Management Services home page, http://www.microsoft.com/ntserver/techresources/management/default.asp.

Microsoft COM Technologies home page, http://www.microsoft.com/com/tech/complus.asp.

Microsoft Universal Data Access home page, http://www.microsoft.com/data.

Sybase ReferencesFor Sybase product manuals and technical papers, visit the appropriate section of the Sybase site of the World Wide Web at: http://www.sybase.com.

Unisys ReferencesThe following documents are included in the OS 2200 series of Unisys documentation, unless otherwise noted. References preceded by an asterisk (*) are those referred to specifically in the UniAccess Documentation. Other references are provided because we feel they may be useful to those administrating the UniAccess System on the OS 2200.

*Collector Programming Reference Manual. Unisys Document Number: 7830 9887-000.

Communications Management System (CMS 1100) Installation and Configuration Guide. Unisys Document Number: 7830 9846.

Communications Management System (CMS 1100) Operations Reference Manual. Unisys Document Number: 7831 5694.

*Communications Management System (CMS 1100) Programming Reference Manual. Unisys Document Number: 7831 5827.

Cooperative Processing Communications Platform (CPComm) Configuration and Operations Guide. Unisys Document Number 7844 8438.

http://www.microsoft.com/ntserver/techresources/management/default.asp

http://www.microsoft.com/ntserver/techresources/management/default.asp

http://www.microsoft.com/com/tech/complus.asp

http://www.microsoft.com/com/tech/complus.asp

http://www.microsoft.com/data

http://www.sybase.com


References E-3

*Cooperative Processing Communications Platform (CPComm) Programming Reference Manual. Unisys Document Number 7844- 8446.

Data Management System (DMS 2200) Schema Data Definition Language (DDL) Administration, Operations, and Programming Guide. Unisys Document Number: 7831 0745.

Data Management System (DMS 2200) Subschema Data Definition Language (SDDL) Administration, Operations, and Programming Guide. Unisys Document Number: 7831 0752.

Enterprise Relational Database Server for ClearPath OS 2200 SQL Programming Reference Manual. Document Number: 7830 8610.

*EXEC System Software Executive Requests Programming Reference. Unisys Document Number: 7830 7899.

*EXEC System Software Installation and Configuration Guide. Unisys Document Number: 7830 7915.

*HMP-IX4.0 Software, Planning and Migration Overview. Unisys Document Number: 7831 0349-019.

*Integrated Recovery Conceptual Overview. Unisys Document Number: 7830 8186.

Linking System Programming Guide. Unisys Document Number: 7831 0521.

*Linking System Programming Reference Manual. Unisys Document Number: 7831 0505.

*Linking System Subsystems Programming Guide. Unisys Document Number: 7830 7451.

*Log Operations and Support Reference Manual. Unisys Document Number: 7831 0315.

*Message Control Bank (MCB) Installation Guide. Unisys Document Number: 7430 0476.



Message Control Bank (MCB) Operations Reference Manual. Unisys Document Number: 7833 1550.

*Message Control Bank (MCB) Programming Reference Manual. Unisys Document Number: 7833 1568.

*OS 1100 LINC II Installation and Operations Guide. Unisys Document Number: 7844 7935.

Relational Data Management System (RDMS 2200) Administration Guide. Unisys Document Number: 7831 0760.

*Relational Data Management System (RDMS 2200) SQL Programming Reference Manual. Unisys Document Number: 7830 8160.

*Security Planning and Administration Reference Manual. Unisys Document Number: 7831-0307.

*Service Library (SLIB) Programming Reference Manual. Unisys Document Number: 7830 7857.

*Software Library Administrator (SOLAR) End Use Reference. Unisys Document Number: 7831 0604.

System Services Programming Reference Manual. Unisys Document Number: 7833 4455.

*Transaction Processing Administration and Operations Reference Manual. Unisys Document Number: 7830 7881.

*Transaction Processing Programming Reference Manual. Unisys Document Number: 7830 7402.

*Unisys Repository Manager (UREP) Administration Guide. Unisys Document Number: 7830 8087.

*Unisys Repository Manager (UREP) Programming Reference Manual. Unisys Document Number: 7830 8079.


References E-5

*Universal Compiling System (UCS) Application Development Programming Guide. Unisys Document Number: 7831 4077.

Universal Compiling System (UCS) Conceptual Overview. Unisys Document Number: 7831 0802.

Universal Compiling System (UCS) C Programming Reference Manual Vol 1. Unisys Document Number: 7831 0422.

*Universal Compiling System (UCS) C Programming Reference Manual Vol 2. Unisys Document Number: 7831 0430.

Universal Compiling System (UCS) COBOL Programming Reference Manual Vol 1. Unisys Document Number: 7831 0448.

*Universal Compiling System (UCS) COBOL Programming Reference Manual Vol 2. Unisys Document Number: 7831 0455.

*Universal Data System (UDS) Administration and Support Reference Manual. Unisys Document Number: 7831 0737.

*Universal Data System Control (UDS Control) Conceptual Overview. Unisys Document Number: 7831 0794.

*Universal Data System (UDS) Configuration Guide. Unisys Document Number: 7844 8362.

Universal Data System Relational Data Management System (UDS RDMS) IPF SQL Interface End Use Guide. Unisys Document Number: 7831 0778.


Glossary

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F Glossary

A

access method. The means for obtaining the target DMS record. For UAHS, the access methods are keyed access and area searches. (See also keyed access, area search.)

API (Application Programming Interface). For the UniAccess System, the API is the interface between the transaction program and OS 2200, known as UniAccess Server-Library and UniAccess Client-Library.

application. A program or group of programs that, when executed, accomplish a particular action.

application group. A group that consists of an integrated recovery database, audit trail, data dictionary (optional), and message retention files. In the UniAccess System, multiple application groups can be configured on one OS 2200 host.

area search. The ability for UAHS to traverse entire DMS areas to find the record(s) needed to satisfy a SELECT command.

array. A structure composed of multiple identical variables that can be individually addressed.

ASCII (American Standard Code for Information Interchange). An 8-bit code used to represent data and certain machine statements.

atomicity. A characteristic of a transaction indicating that it will either commit or abort. If it commits, all of its effects remain; if it aborts, all of its effects are undone.

F-2 UniAccess for OS 2200 Client Guide


automatic set. A type of DMS set relationship where a member record type will always have an owner in the given set. (Contrast with manual set.)

B

batch run. A type of data processing where processing is controlled by a predefined runstream. Once the runstream is started, little or no intervention by an operator or end user is required.

BLOB. A datatype whose contents and structure are defined by the application that uses it. BLOBs can be relatively small—a couple thousand bytes—to very large—up to 4 gigabytes. Typically, BLOBs store image data: pictures, finger prints, scanned documents, and so on.

business services. In Microsoft client/server architecture, the application service that provides generation of business information from data, determination of application flow, governance of shared business policies, and protection of business integrity. (Contrast with data services, presentation services.)

C

CALC record. A DMS record accessed by the DMR using a calculation, or hashing, routine to determine the page and chain number of the record.

Catalog RPCs. Remote procedure calls that request RDMS and DMS catalog information used by the UniAccess ODBC Driver. In the UniAccess System, these RPCs are processed by the UARS and UAHS transactions respectively.

ClearPath IX. A family of enterprise servers, or mainframes, that are object-code compatible with 2200 Series systems.

client. In client/server architecture, clients are the part of the system that send requests to servers and process the results of those requests. (Contrast with server.)

client/server architecture. A method of distributed computing that divides the work of computing between clients and servers and defines an interface between them. Client applications provide user interface and presentation logic; they make requests of server applications. Server applications provide the logic to accept client requests, process them in a host database, and return the results to the client.


Glossary F-3

client user. In the context of this manual, a person entering commands at a workstation or a Microsoft SQL Server.

CMS 1100 (Communications Management System). CMS 1100 provides a processing path through which application systems on the host can access the services of the data transport network.

COM+. A set of services based on extensions of Microsoft Transaction Server and the Component Object Model (COM) that provide improved threading and security, transaction management, object pooling, load balancing, queued components, and application administration and packaging.

configuration statement. Formatted system data format (SDF) ASCII images that define entities and operational characteristics of UniAccess System components.

connection. A network path between two systems. For TCP/IP, it connects TCP modules on separate machines.

console command. A keyin that is performed at the system console or while in console mode. These commands are used to manage and derive status information from UACS.

CT-Library. A set of C routines and macros that allow an application to interact with a SQL Server.

D

data services. In Microsoft client/server architecture, the application service that provides definition of data, storage and retrieval of persistent data, and protection of data integrity. (Contrast with business services, presentation services.)

datatype. A defining attribute that describes the values and operations that are legal for a variable.

DCOM (Distributed Component Object Model). A protocol that enables software components to communicate directly over a network in a reliable, secure, and efficient manner. DCOM is designed for use across multiple network transports, including Internet protocols such as HTTP. DCOM is based on the Open Software Foundation’s DCE-RPC spec and will work with both Java applets and ActiveX components through its use of the Component Object Model (COM).



DB-Library. A set of C routines and macros that allow an application to interact with a SQL Server.

DDL (Data Definition Language). Commands used to define (vs. access) a database. In the context of DMS 2200, DDL is the processor and language used to define a schema.

default. Describes the value, option, or behavior that UniAccess System for OS 2200 products use when none is explicitly specified.

distributed transaction. A transaction involving updates to transaction-protected resources across two or more systems. In this sense, a transaction is a module of execution (not specific to OS 2200), that is atomic, consistent, isolated, and durable. In the UniAccess environment, Server-Library transactions may participate in distributed transactions with the assistance of the UniAccess Distributed Transaction Coordinator.

distributed transaction ID. The unique identifier for a transaction participating in a distributed transaction. It is the step ID supplied by the OS 2200 operating system and is retained throughout the transaction’s existence on the system.

DML (Data Manipulation Language). Commands used by application programs to access DMS 2200 databases. UAHS translates SQL to DML.

DMS 2200 (Data Management System 2200). The software product on Unisys OS 2200 systems that is the DBMS for databases defined and structured according to a hierarchical or network data model. Conforms to the CODASYL data model.

DMS schema. A representation of the entities and hierarchy that form a DMS database; defined by DMS DDL commands.

dynamic request. In the context of this manual, a SQL language statement entered online (as in isql), incorporated in an RPC, or sent by UniAccess Client-Library and processed during execution. Dynamic refers to the language request’s flexibility and interactivity. (Contrast with static request; see language request.)


Glossary F-5

E

embedded SQL (ESQL). SQL commands that are placed in a UCS COBOL program using the special markers (or delimiters) EXEC SQL and END-EXEC. ESQL statements are compiled instead of interpreted and take two forms: static and dynamic. Static ESQL is processed more extensively at compile time than dynamic ESQL and thus executes faster. Dynamic ESQL receives more extensive run-time processing than static ESQL and provides greater flexibility.

enlisted connection. An ODBC client connection that has been marked as participating in a distributed transaction.

extended session. A series of requests and responses between a client application and a Server-Library transaction (UARS or user-written) where the Server-Library transaction services multiple RPC or language requests while remaining in memory.

F

fixed-gate. A component of a subsystem that is partitioned off from the rest of the system by a combination of hardware and software.

fixed-gate shared subsystem. The extended mode equivalent of common banks. It allows multiple applications to share the same stored information.

H

hierarchical database. A data model or database that represents entities as owner-member record structures. (Contrast with relational database.)

high speed connections. An option available to UADriver users that improves connection speed by eliminating the client’s ability to override the default host settings on the OS 2200. Instead, host settings are retrieved at configuration time and stored in the Windows registry.

HLC (Host LAN Controller). A control unit that connects an OS 2200 host to an IEEE 802.3 or Ethernet LAN. In the context of this manual, the HLC connects UniAccess System on the OS 2200 host to the LAN on which clients and SQL Servers reside.



host. The hardware system on which a software application runs. In the UniAccess documentation, the term host generally refers to the OS 2200 mainframe where the UniAccess System software is running.

I

Index Sequential. A method of record access that allows both the sequential (ordered) and random access to records. An index is constructed and ordered based on the key record items specified.

input variable. A variable that has its value specified by the program. (Contrast with output variable.)

interface components. In client/server architecture, components that connect client and server software through clearly defined, message-based protocols. Interface components (like the UACS, UAMM, and UADT components in the UniAccess System) are often incorporated within client and server systems and may be transparent to the user.

interfaces file. A Sybase system file that contains network information about all machines running Sybase SQL Servers with which a client application can communicate. The interfaces file for a particular machine contains one entry for each server installed on that machine and one entry for every remote server to which a connection can be made.

interpretive SQL. A SQL language statement that is analyzed and executed at run time.

isql. Interactive SQL parser to SQL Server.

ISQL. Applied Information Sciences’ Interactive SQL Parser for OS 2200.

I/O (Input/Output). See input variable; output variable.

K

Kanji identifiers. Identifiers constructed with Kanji characters (Japanese characters). Internal code mappings of the character set is supplied by either the Shift-JIS or LETS-J codes. User-created translation routines supported by UARS allow for the use of and the conversion between these two codes in the UniAccess environment. (See also translation routines).


Glossary F-7

keyed access. A retrieval method where UAHS uses CALC or index sequential keys to access DMS 2200 records. (See also CALC record; Index Sequential.)

L

language request (command). A language request contains character strings that represent requests in a server’s own language. Language requests are flexible and interactive. They may be entered online (as in isql) or incorporated in a client request. A language request may contain one or more language statements. (Contrast with remote procedure call.)

language transaction. A general-purpose, database-specific OS 2200 TIP transaction designed to process client language requests. The UniAccess System offers two language transactions—UniAccess Relational Service for RDMS 2200 and UniAccess Hierarchical Service for DMS 2200—and supports the creation of user-written language transactions through the UniAccess Server Library service.

literal string. A character or characters set off by single quotation marks (that is, apostrophes) as delimiters to indicate a literal value.

local. Usually refers to the system that is the topic under discussion. The system must be accessed directly, without using network access. In the UniAccess System documentation, local often refers to the OS 2200 host where the UniAccess System is installed. (Contrast with remote.)

login information. The userid and password used by a client user when logging in to the system. This information is part of the client’s login definition in UADT.

M

manual set. A type of DMS set relationship where a member record type exist without an owner in a given set. (Contrast with automatic set.)

mapping. Representing a DMS schema as relational entities, by selecting and grouping records, fields and sets to define one or more UAHS tables and databases.

member-driven table. A UAHS table defined with a subordinate root record. UAHS accesses the records from the bottom of the set hierarchy up. (Contrast with owner-driven table.)



message text. A string of characters that relay error, warning, and informational messages to the user.

meta data. Data that defines and describes other data. UREP uses meta data stored in UREP for RDMS. UAHS uses DMS schema information and relational mapping information in a user-build repository.

meta database. A database that defines and describes other databases.

MS DTC (Microsoft Distributed Transaction Coordinator). A distributed transaction facility for Microsoft Windows. When used with UniAccess, MS DTC is the primary or root transaction manager, which means it is responsible for creating transaction objects and managing their atomicity and durability. (See UniAccess Distributed Transaction Coordinator.)

N

null. Having no explicitly assigned value. Null is not equivalent to zero or to blank. A value of null is not considered to be greater than non-nulls when sorted with an ORDER BY clause. That is, if a column is sorted in ascending order rows, a null in that column will follow all rows with non-null in that column.

O

ODBC (Microsoft® Open Database Connectivity). An interface that allows applications to access data in heterogeneous database management systems (DBMS) using Structured Query Language (SQL) as a standard for accessing data.

OLE Transactions. OLE Transactions (OLE TX) the Microsoft interface standard for transaction management. OLE Transactions defines the interfaces that applications, resource managers, and transaction managers use to perform transactions. Applications use OLE Transactions interfaces to initiate, commit, abort, and inquire about transactions. Resource managers use OLE Transactions interfaces to enlist in transactions, to propagate transactions from process to process or from system to system, and to participate in the two-phase commit protocol.

Open Client. An application written using the CT-Library, DB-Library, or UniAccess Client-Library API. In this document, an Open Client generally refers to a non-ODBC client. (Contrast with server.)


Glossary F-9

OS 2200 (Operating System 2200). System software for Unisys Series 1100/90 and Series 2200 systems.

output variable. A variable that returns data to a program. (Contrast with input variable.)

owner-driven table. A UAHS table defined with a superior root record. UAHS accesses these records from the top of the set hierarchy down. (Contrast with member-driven table.)

P

padding. Characters used to fill out the unused bytes in a field whose length is longer than the length of the actual data. A variety of characters can be used for padding, but the default is usually 0 for numeric fields and blank for character fields. Numeric fields are padded to the left of the value; character fields are padded to the right of the value.

parameter. (1) A variable that is used to pass data to and retrieve data from a routine. (2) An argument to a stored procedure.

PCIOS (Processor Common Input/Output System). Software used to open a file for I/O and to read, write, backspace, and close the file when specified. It produces compatible data files for high-level processors.

PICTURE clause (PIC). A COBOL syntax component (also used in DMS DDL) that describes the general characteristics and editing requirements of an elementary data item. Together, the PICTURE and USAGE clauses completely define the datatype of an item. (See also USAGE clause.)

PID (Position Identifier). The internal number used by TIP to address a terminal.

precision. The maximum number of digits used by the numeric datatype of a column or input parameter.

presentation services. In Microsoft client/server architecture, the application service that provides interaction with the user, including presentation of information and functionality, navigation, and protection of user interface consistency and integrity. (Contrast with data services, business services.)



product key. A customer-specific string provided to each UniAccess customer. It activates the features and connection limits in UniAccess that the customer purchased.

program message. Any error that is generated by a UniAccess System component or user-written transaction that is returned to a client application.

protocol. The meaning of and sequencing rules for requests and responses used to manage a TCP/IP network, transfer data, and synchronize the states of network components.

R

RDMS 2200 (Relational Data Management System 2200). The software product on Unisys OS 2200 systems that is the DBMS for databases defined and structured according to a relational data model. RDMS 2200 has its own version of SQL that is used to access data stored in its tables.

RDMS 2200 stored procedures. A group of SQL commands that reside in RDMS 2200 and can be executed as one unit (supported by RDMS 2200 as of Level 9R1). In the UniAccess System, support for RDMS 2200 stored procedures is provided through the UniAccess Relational Service (UARS).

RDMS Access Control. An RDMS security mechanism for preventing unauthorized users from accessing a table or altering its definition.

relational database. A data model or database that represents entities as two-dimensional tables of rows and columns. (Contrast with hierarchical database.)

remote. A system, program, or device that is on the network but outside the local host. In the UniAccess System documentation, remote often refers to systems outside the OS 2200 host, such as the UniAccess ODBC Driver, SQL Servers, and Open Client software. (Contrast with local.)

remote procedure call. Specifically coded requests mapped to server software that has been designed to receive it, such as a stored procedure on a SQL Server or a UniAccess Transaction Server program. (Contrast with language request.)

request. An RPC or language request sent by a client to a server.


Glossary F-11

resource manager. A generic term for a transactional data management service such as a database management system or a queue management system. Resource managers are the participants in a distributed transaction that manage durable data. (See distributed transaction; contrast with transaction manager.)

return parameter. RPC parameters whose values can be changed at the server, then returned to the client. UniAccess Server-Library transactions send return parameters back to the client when they call TDSNDDON.

root. The DMS record named in the main clause of a UAHS CREATE TABLE command. It designates the starting point of the DMS access path for UAHS and governs the records included in a table when there are underlying empty sets.

RPC. See remote procedure call.

S

scalar function. A function built-in to a database engine that returns a value for each row selected. Scalar functions include string functions, numeric functions, time and date functions, system functions, and datatype conversion functions. In the UniAccess System, a scalar function is one of the RDMS built-in scalar functions.

scale. The number of digits to the right of the decimal point. Scale applies only to some datatypes. For exact decimal datatypes, scale is the second value specified in the datatype definition. For example, the scale of CS-NUMERIC (10,3) is 3.

schema. (See DMS schema.)

schema source. The DDL commands used to define the schema. (See also DDL.)

SCHEMADEF. The UniAccess System utility that reads DMS DDL and translates schema information into the UAHS Meta Database. (See also TABLEDEF, UAHS Meta Database.)

segments. Named subsets of the database devices available to a particular SQL Server database.

server. An application that manages data and access to that data. A server accepts and processes client requests for data, then returns results to the client. Server functions can include



enforcing integrity and security and, as in the case of SQL Servers, managing databases. (Contrast with client and Open Client.)

server-to-server connection. See indirect request.

session. In UniAccess System for OS 2200, a connection between a client application and the UniAccess System.

Site Information File. An SDF file that contains the site-specific configuration statements that define the environment in which the UniAccess System operates and specifies its operational characteristics. This file is built from a template supplied by AIS and modified by the system administrator with site-specific information. The UACF utility processes this file when it is executed. (See UniAccess Configuration Utility; contrast with UA Information File, UniAccess Configuration File.)

snap-in. Each MMC tool is built of a collection of instances of smaller tools called MMC snap-ins. One snap-in represents one unit of management behavior. A snap-in is the smallest unit of console extension. Technically, a snap-in is an OLE InProc server that executes in the process context of MMC. The snap-in may call on other supporting controls and DLLs to accomplish this task.

SQL (Structured Query Language). An industry-standard language that enables the creation, modification, and retrieval of data in a relational database.

SQL Server. A database server in the Microsoft client/server architecture that accepts RPCs or language requests written in Transact-SQL. SQL Servers manage multiple databases and multiple users, keep track of the actual location of data on disks, maintain mapping of logical data description to physical data storage, and maintain data and procedure caches in memory.

There are two implementations of SQL Server: Microsoft SQL Server and Sybase SQL Server (a.k.a. Adaptive Server Enterprise—ASE), which provide many similar features. When this manual refers to SQL Server, it is referring to features common to both SQL Servers. Features specific to an implementation will be identified as either Microsoft SQL Server or Sybase SQL Server.

static request. In the context of this manual a fixed-format request to a server using embedded SQL statements. (See remote procedure call; contrast with dynamic request.)


Glossary F-13

storage area. A UDS database file, actually stored in an Exec or TIP file. For RDMS, the data stored in one or more relational tables; for DMS, an area of records; for SFS, a file of PCIOS or SFS data.

stored procedure. A collection of SQL statements and an optional sequence of flow-of-control statements stored under a specific name on a server. In the UniAccess System, a stored procedure is one that has been created and exists (is stored) on a SQL server or in RDMS 2200.

subschema. Part of a DMS schema made available to application programs and defined with SDDL.

T

TABLEDEF. The UniAccess System utility used to define logical relational structures representing a DMS schema in the UAHS Meta Database. (See also SCHEMADEF, UAHS Meta Database.)

TCP/IP (Transmission Control Protocol/Internet Protocol). An open systems network architecture and set of communications protocols.

TDS (Tabular Data Stream). Sybase’s defined application-level protocol that defines the internal format of client/server requests and replies.

TIP. An OS 2200 software product that supports development and execution of online transaction processing applications. (See transaction).

TIP session control. An OS 2200 security feature that validates the user security identity (userid and security record) as a communications path is opened to a terminal through CMS 1100.

TIP transaction. OS 2200 transactions that are created and run in an TIP environment. UAHS, UARS, and all UASL transactions are TIP transactions. UACL applications may be TIP transactions.

trace. A function whereby a record of data traffic and events is stored in a designated file. The trace function is useful for troubleshooting problems. Trace files can be set at several levels within the UniAccess System.



Transact-SQL. An enhanced version of the database language SQL. Applications can use Transact-SQL to communicate with SQL Server.

transaction. A program that runs in a TIP environment on the OS 2200 system and is initiated by a single request. In the UniAccess System for OS 2200, TIP transactions may act as either clients or servers. Client transactions may be created with UACL functions; server transactions may be created with UASL functions. The term Server-Library transaction refers to UASL transactions as well as to the UARS and UAHS language transactions.

transaction ID. (See distributed transaction ID.)

Transaction Internet Protocol. An industry-standard network format and protocol through which two or more transaction managers can perform two-phase commit and recovery. (See MS DTC; transaction manager; two-phase commit.)

transaction manager. A system service responsible for coordinating the outcome of distributed transactions in order to achieve atomicity. Multiple transaction managers may cooperate to manage a single distributed transaction, with one acting as the primary transaction manager. (See distributed transaction; contrast with resource manager.)

translation routines. An option supported by UniAccess Relational Service and UniAccess Hierarchical Service for the creation of two user-written routines, HostToClient and ClientToHost. These routines may amend or translate the data as deemed appropriate and pass it back to the language service for further processing.

two-phase commit (2PC). A protocol that allows all transactions participating in a distributed transactions complete successfully. The first commit phase of a distributed transaction is a PREPARED state (ready to commit). The second commit phase is to either commit or rollback.

U

UA Information File. An SDF file that contains UniAccess-specific configuration statements that define mapping and message records for the UniAccess System. This file normally does not need to be modified by the system administrator. The UACF utility processes this file when it is executed. (See UniAccess Configuration Utility; contrast with Site Information File, UniAccess Configuration File.)

UADTC transactions. UniAccess Server-Library transactions that are participating in MSDTC-initiated distributed transactions co-managed by UADTC. This includes UARS and user-


Glossary F-15

written RPC-processing TIP transactions. (See UniAccess Distributed Transaction Coordinator.)

UAHS database. A logical grouping of UAHS tables that have been mapped from records and set relationships in a given DMS schema and organized to support a specific application function or purpose.

UAHS Meta Database. The repository containing schema information and relational mappings of a given DMS schema.

UAHS table. A logical tabular structure defined from one or more related DMS records. Table columns are mapped from underlying record fields; rows are occurrences of an underlying record or set.

UAINFO. An AIS-written TIP transaction that provides connection and version information to client applications operating in a non-UARS, non-UAHS environment.

UCS C interface. Two collections of C language headers, one required to interface with UniAccess Client-Library, the other required to interface with UniAccess Server-Library.

UDS (Universal Data System). An expandable, modular collection of related Unisys products used for database management.

UniAccess Client-Library (UACL). A set of standard routines (functions) that provide OS 2200 programs the ability to function as Open Clients in the Microsoft client/server architecture.

UniAccess Communication Server (UACS). The UniAccess System processor on the OS 2200 that manages network input and output for all UniAccess System clients and servers.

UniAccess Configuration File. The processed form of the two source configuration files (the UA Information File and the Site Information File) maintained by the system administrator. The UniAccess Configuration File is in a fixed-binary form that is readable by UniAccess products. The configurations in the file define the environment in which the UniAccess System operates and specify its operational characteristics. They also contain definitions of users, messages, and remote server connections. (See UniAccess Configuration Utility; contrast with Site Information File, UA Information File.)

UniAccess Configuration Utility (UACF). The processor in the UniAccess System that converts the Source Configuration File of configuration statements to the UniAccess Configuration



File that is readable by UniAccess products. UACF also initializes UAFG, the fixed-gate service within the UniAccess System.

UniAccess Data Manager (UADT). A service within the UniAccess Fixed-gate that manages user definitions, message information, remote server information, and other system definition information. This data is shared by all components of the UniAccess System. (See UniAccess Fixed-gate.)

UniAccess Distributed Transaction Coordinator (UADTC). The UniAccess distributed transaction facility for Microsoft Windows It serves as the interface between MS DTC and the OS 2200-based resource manager components; that is, it acts as a gateway forwarding two-phase commit commands between MS DTC and UniAccess on the OS 2200. (See distributed transaction; MS DTC; two-phase commit, UADTC transactions.)

UniAccess Fixed-gate (UAFG). The system-wide fixed-gate shared subsystem that contains UADT, UASL, UACL, and UAMM services.

UniAccess Hierarchical Service for DMS 2200 (UAHS). The database language transaction in the UniAccess ODBC service for DMS 2200. A TIP transaction that allows read-only SQL access to DMS data using a relational mapping of a DMS schema and provides ODBC-style catalog information in response to client requests. UAHS supports a subset of standard SQL SELECT statement syntax and catalog procedure calls.

UniAccess Integrated Recovery Utility (UAIR). The processor in the UniAccess System that provides the system administrator with the capability to resolve (COMMIT or OMIT) distributed transactions which may have been left in the PREPARED state by a system failure. (See distributed transaction.)

UniAccess Message Manager (UAMM). A service within the UniAccess Fixed-gate that manages the transport of messages between one or more UACSs and UniAccess library-based programs. (See UniAccess Fixed-gate).

UniAccess ODBC Driver (UADriver). The UniAccess implementation of Microsoft’s Open Database Connectivity (ODBC). The driver processes ODBC API function calls from a wide variety of client tools, submits SQL language and RPC requests to OS 2200 transactions, and returns results to the application.

UniAccess ODBC Server for DMS 2200. The UniAccess System server package that services client language requests to DMS 2200. The ODBC Server for DMS 2200 includes UniAccess Hierarchical Server, UniAccess Communication Server, and other components


Glossary F-17

that act together as a server on the OS 2200 host, and the UniAccess ODBC Driver for client workstations.

UniAccess ODBC Server for RDMS 2200. The UniAccess System server package that services client language requests to RDMS 2200. The ODBC Server for RDMS 2200 includes UniAccess Relational Service, UniAccess Communication Server, and other components that act together as a server on the OS 2200 host, and additionally the UniAccess ODBC Driver for client workstations.

UniAccess Relational Service (UARS) for RDMS 2200. The database language transaction in the UniAccess ODBC service for RDMS 2200. A TIP transaction that allows SQL access to RDMS data, provides ODBC-style catalog information in response to client requests, and supports RDMS stored procedures.

UniAccess Security API. A UniAccess feature that establishes communication between local or third-party security systems and the UniAccess System using a request and notification protocol.

UniAccess Server-Library (UASL). A set of standard routines (functions) that provide OS 2200 programs the ability to function as servers in the Microsoft client/server architecture. The term Server-Library transaction refers to TIP transactions created with UASL functions, including the UARS and UAHS transactions.

UniAccess System for OS 2200. The Applied Information Sciences product suite that implements the Microsoft client/server architecture on the Unisys OS 2200 system.

UniAccess System servers. The three UniAccess System product packages that provide server capabilities on the OS 2200, namely UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200.

UniAccess System tables. AIS-created RDMS 2200 tables containing information about the RDMS catalog stored procedures supported by the UniAccess System. The system administrator is responsible for maintaining information in these tables, including adding information about site-written UASL transactions.

UniAccess Transaction Client. A set of standard routines (functions) that provide OS 2200 programs the ability to function as clients in the Microsoft client/server architecture.

UniAccess Transaction Server for OS 2200. The UniAccess System server package that supports access to OS 2200 resources by site-written UASL transactions. The Transaction Server includes UniAccess Server Library, UniAccess Communication Server, and other



components that act together as a server on the OS 2200 host, and additionally the UniAccess ODBC Driver for client workstations.

UREP repository. A database containing UREP (Unisys Repository Manager) information, such as storage area definitions for an RDMS database and symbolic tables.

USAGE clause. A COBOL syntax component (also used in DMS DDL) that defines the representation of a data item in storage. Together, the USAGE and PICTURE clauses completely define the datatype of an item. (See also PICTURE clause.)

user datatype. A 4-byte field provided by Open Client and TDS protocol to return user datatype information. The UARS, UAHS, and UAINFO transactions use this field to return detailed information about OS 2200 datatypes. This information is used by UADriver and is also available to user-written Open Client applications that utilize these UniAccess transactions.

user-defined transaction. A user-defined transaction is initiated when a BEGIN TRAN is sent to UARS (either by UADriver when it is in manual commit mode or directly to an Open Client application).

user-written language transaction. A general-purpose, database-specific OS 2200 TIP transaction designed to process client language requests. The transaction would be written by a UniAccess System customer using UniAccess Server Library functions.

V

VALTAB (Program Validation Table). A TIP system file containing transaction code definitions called VALTAB entries and information on the characteristics of the associated transaction programs.

versions. An RDMS 2200 term referring to another copy of a table, which may contain different data. Many versions of a table can exist. Each version of the table is associated with the same storage area name but has a different version name attached to it within that storage area definition. Data associated with each version is stored in its own file.


Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I Index

Numerics2PC

(see two-phase commit protocol)

AAccessControl

modifications for UADriver 6-9Adaptive Server Enterprise—ASE

a.k.a. Sybase SQL Server xviiAIS (Applied Information Sciences)

product packages xivRDMS tables created by 8-2

ALTER TABLEautomatically generated for CREATE

TABLE 5-25Andyne GQL

notes on UADriver settings 5-40apostrophes

with literal strings 6-13application

definition xviiapplication development

general discussion 2-1in the UniAccess System 2-9services model 2-2types of requests 2-7

Applied Information Sciencescopyright information iireferences E-1

architectureclient/server 1-2ODBC 1-5UniAccess System 4-4

area searchesallowing for UAHS

UADriver option 5-31UAHS command 10-4

Bbatch statements

effect of SET ACCESS on 7-6effect of SET RECOVERY on 7-13effect of SET WORKSIZE on 7-24error handling 6-15not supported by user-defined transactions

6-19syntax 6-14

BEGIN TRAN (UARS command)description 7-5for user-defined transactions 6-17

BLOB sizedefined by UADriver 5-25defined by UARS command 7-8

business servicesdefinition 2-2

I-2 UniAccess for OS 2200 Client Guide


CCannot Notify Aborted state

resolving 13-26Cannot Notify Committed state

resolving 13-25Catalog RPCs

RDMScoding instructions 8-5descriptions 8-8entities accessed by 8-4general discussion 8-2quick reference 8-8support for user-written transactions

12-3troubleshooting D-14use of wild cards 8-6

UAHScoding instructions 11-2descriptions 11-5feature of UAHS 9-5general discussion 11-2quick reference 11-5use of wild cards 11-4

Centura SQL Windowsnotes on UADriver settings 5-40

CHAR (datatype)automatically converted from VARCHAR

5-26CHARACTER

returned as SQL_LONGCHARUADriver option 5-28UARS command 7-12

character columnsconverted from integers

UADriver option 5-26UARS command 7-11

removing trailing spaces fromUADriver option for UAHS 5-31

UADriver option for UARS 5-27UAHS command 10-8UARS command 7-16

character datatypes(see CHAR, NCHARACTER,

VARCHAR)client

(see also UniAccess PC Client)definition xvii

client requestscomparison 2-8language requests 2-7

Client-Library datatypescorrespondence to DMS datatypes 9-20correspondence to RDMS datatypes 6-20passed from ODBC SQL to UASL

transactions 5-8passed from UASL transactions to ODBC

SQL 5-9supported by UASL 12-2

clientsdefinition 1-2types of 1-5

client/server architectureadvantages of 1-3general discussion 1-2model 1-3types of computing configurations 2-2

three-tier 2-5two-and-a-half-tier 2-4two-tier 2-3

COM+ (Component Object Model+)description 13-6

COM+ Componentdescription 13-6

COMMITuse of 6-14


Index I-3

COMSRV (configuration statement)CHARTRUN 5-28, 6-27CONTIMOUT 4-4DFLTTRAN 4-3, 12-9LOGOFFTRAN 4-3LOGONTRAN 4-3USEUAUSER 4-2

connection stringattributes defined 5-33connecting to a data source using 5-33

connections (UADriver)maximum idle 5-19maximum number 5-16maximum statements per 5-19multiple active statements per 5-10, 5-18

connections (UniAccess System)establishing 4-2timeout interactions 4-4

control charactersremoving from literal strings

UADriver option for UAHS 5-31UADriver option for UARS 5-27UAHS command 10-9UARS command 7-17

CREATE TABLEautomatically generating an ALTER

TABLE for 5-25modifications for UADriver 6-8troubleshooting D-15

Ddata services

definition 2-2data source name (ODBC)

defined 5-12data sources

connecting totroubleshooting D-12

data sources (ODBC)configuring 5-11

general options 5-11connecting to

using a connection string 5-33using a login box 5-33

definition 1-7saving configurations 5-12verifying connectivity 5-32

database(see UAHS database, RDMS 2200

database)datatypes

(see Client-Library datatypes, DB-Library datatypes, ODBC SQL datatypes, RDMS 2200 datatypes, DMS 2200 datatypes, user datatypes, UASL datatypes, and UARS, datatypes)

DB-Library datatypescorrespondence to RDMS datatypes 6-20supported by UASL 12-2

debugging (UAHS)activating

UADriver option 5-30UAHS command 10-5

discussion 9-18, D-9DELETE TABLE

automatically prefixing to DROP TABLE 5-26

distributed transaction processingcomponents 13-3discussion 13-2steps 13-5UniAccess/Microsoft implementation 13-6

distributed transactions(see also UADTC)definition xviiigeneral



discussion 13-3processing 13-5

management 13-15manually resolving 13-22

Cannot Notify Aborted state 13-26Cannot Notify Committed state 13-25In Doubt state 13-23

monitoring 13-17support for

UADriver option 5-18UAHS command 10-6UARS command 7-9

transaction states 13-20UniAccess

definition 13-7DML commands

support of owner field 5-17translated by UAHS 9-2

DMS 2200 datatypescorrespondence to ODBC SQL datatypes

5-7length 9-22precision 9-23scale 9-23supported 9-21supported by UAHS 9-20, 9-24

driver(see also UADriver)definition for ODBC 1-7

Driver Managerdefinition 1-6

DROP INDEXmodifications for UADriver 6-9

DROP TABLEautomatically prefixing with DELETE

TABLE 5-26modifications for UADriver 6-10

DROP VIEWmodifications for UADriver 6-10

Eempty strings 6-26

conversions by UADriver 6-7error messages

server program B-1UAMM C-1UniAccess Transaction Server B-1, B-2

escape characterremoved by UADriver workaround 5-16

Ffixed-length character columns

blank-padding 5-17fixed-point values

ranges supported 4-4floating-point values

loss of precision when converted 4-5ranges supported 4-4

HHIERSRV (configuration statement)

AREASEARCH 5-31, 10-4DEBUG 5-30, 9-18, 10-5, D-9ROWLIMITH 5-18, 5-30, 10-7SCHEMAH 5-30SPACETRIMH 5-31, 10-8STRIPCTRLH 5-31, 10-9

high speed connections, UADriveractivating 5-19discussion 5-10updating settings for 5-20

hostdefinition xvii

Host Connectivity Test 5-32results D-2

host servicesconfiguring for UADriver 5-13


Index I-5

II.P. address

configuring for UADriver 5-14idle connections

setting maximum for ODBC 5-19In Doubt state

resolving 13-23installation

ODBC (UADriver) 3-4UADTC 13-11

integer columnsconverted to characters


Interactive SQLcoding examples A-1

interfacedefinition 1-2

Internetimplementation in three-tier model 2-5

Internet host nameconfiguring for UADriver 5-14

isolation levelssupported 5-9

ISQL (Interactive SQL Parser for OS 2200)a component of UniAccess Transaction

Client xiv

KKanji identifiers

designating format ofUADriver option 5-22UARS command 7-19

Llanguage requests

compared to RPCs 2-8general discussion 2-7sending 2-10

for ODBC applications 2-10for Open Client applications 2-10

language transactions(see also UAHS, UARS, user-written

transactions)configuring default for UADriver 5-13in the UniAccess environment 1-13

lengthof UAHS supported datatypes 9-22of UARS supported datatypes 6-24

LETS-Jdesignating as Kanji identifier


literal stringsremoving control characters from


localdefinition xvii

lock levelssupported 5-9

login ID (for UADriver)specifying 5-16

logon timeout (for UADriver)defining 5-16

Mmanual commit

(see also BEGIN TRAN)UADriver option 5-27UARS command 7-23

messagesmodifying B-2server program B-1UAHS errors B-21UAMM C-1



Microsoftreferences E-2

Microsoft Open Database Connectivity(see ODBC)

Microsoft SQL Serverexamples of indirect requests through A-2in the UniAccess System 1-13replication 5-28stored procedure support 2-4use with UADTC 13-8

Microsoft Systems Management Server (SMS)installation 3-6

Microsoft Transaction Server (MTS)middle-tier support 2-5

Microsoft Windows operating systemsUniAccess PC Client requirements 3-2

MS DTC (Microsoft Distributed Transaction Coordinator)

description 13-6system requirements 3-2

multiple active statements/connectionconfiguring 5-18supported 5-10

NNCHARACTER

returned as SQL_LONGCHARUADriver option 5-28UARS command 7-12

returned as SQL_UNICODEUADriver option 5-28UARS command 7-22

nested transactionsnot supported by UARS 6-19

not equal (!=) operatorconversion by UADriver 6-8

null strings 6-26

OODBC

components 1-6illustration 1-7

general discussion 1-5implementation level of UADriver 5-3

ODBC clientsprocedure calls 2-12RDMS statement considerations 6-6sending language requests 2-10

ODBC SQL datatypescorrespondence for RDMS stored

procedures 6-30correspondence to DMS datatypes 5-7,

9-20correspondence to RDMS datatypes 5-5,

6-20correspondence to UASL datatypes 5-8received from UASL transactions 5-9structure of RDMS returned user datatypes

4-7ODBC Translation

customized DLL installation 3-9UADriver options 5-22UADriver support 5-10

ODBC usersusing this manual 4-8

Open Clientdefinition xvii

Open Client usersusing this manual 4-9

Open Clientscommands for 4-9datatype considerations for 6-26RDMS statement considerations 6-10

grouping statements 6-14syntax differences 6-11user-defined transactions 6-16


Index I-7

sending language requests 2-10sending RPCs 2-12system requirements 3-2

OS 2200host xvii

OS 2200 environmentdiscussion 1-13

OSPARM (configuration statement)DFLTPROCENV 6-28

owner fieldsupported in DML commands 5-17

owner namesUARS modifications for UADriver 6-7

Ppacket size

UADriver option 5-17passwords

changing 4-4port

assigned for UADTC 13-14configuring for UADriver 5-14

precisionof UAHS supported datatypes 9-23of UARS supported datatypes 6-24

presentation servicesdefinition 2-2

procedure calls(see RPCs)

procedure columnsordering 5-26

program messages, serverdefinition B-1list B-2modifying B-2

Qqualifiers

in RDMS 2200 SQL 6-12quotes

automatically placed 5-27with identifiers 6-13with literal strings 6-13

RRDMS 2200

access controlactivating for CREATE TABLE

command 5-25qualifier

default definition through UADriver 5-22

RSA worksizedefined by UARS command 7-24defining by UADriver 5-25

thread accessdefined by UARS command 7-6defining by UADriver 5-24

thread recoverydefined by UARS command 7-13defining by UADriver 5-25

versiondefault defined 5-24

RDMS 2200 catalog informationtroubleshooting D-15use of Catalog RPCs 8-2

RDMS 2200 database(see also RDMS 2200, qualifiers)list of available 8-18

RDMS 2200 datatypesclient correspondence 6-20correspondence to ODBC SQL datatypes

5-6descriptions 6-22



information returned by Catalog RPCs 8-7length 6-24precision 6-24scale 6-24supported by UARS 6-20

RDMS 2200 scalar functionsODBC function mapping 6-35RDMS functions supported 6-39syntax 6-34

RDMS 2200 SQLapostrophes and quotes 6-13general guidelines for Open Clients 6-11naming conventions 6-12qualifiers 6-12SELECT statements 6-13syntactic differences with Transact-SQL

6-11versions 6-12

RDMS 2200 statementsgrouping 6-14notes on supported statements 6-6supported by UARS 6-4

RDMS 2200 storage areasdefining by UADriver 5-24deleting 5-24modifications for UADriver 6-8problems with RDMS tables D-15

RDMS 2200 stored proceduresdatatype correspondence

Client-Library 6-31ODBC SQL 6-30

error processing 6-29general discussion 6-28routing requests 6-28

RDMS 2200 tablesAIS defined 8-3catalog information 8-2system defined 8-3

referencesAIS (Applied Information Sciences) E-1Microsoft E-2Sybase E-2Unisys E-2

RELSRV (configuration statement)ACCESS 5-24, 7-6DOUNICODE 5-28, 7-8, 7-9, 7-18, 7-21,

7-22, 10-6, 10-11INTTOCHAR 5-26, 7-11LONGCHAR 5-28, 7-12MAXBLOBSIZE 5-25RECOVERY 5-25, 7-13ROWLIMIT 5-24, 6-6, 7-15SCHEMA 5-23, 6-6SPACETRIM 5-27, 7-16STRIPCTRL 5-27, 7-17USERTRAN 5-27, 7-5, 7-23VERSION 5-24WORKSIZE 5-25, 7-24

remotedefinition xvii

replicationMicrosoft SQL Server 5-28

resource managersdescription 13-3

REVOKEmodifications for UADriver 6-10

ROLLBACKuse of 6-14

row limitdefined

by UADriver, for UAHS 5-30by UADriver, for UARS 5-24by UAHS command 10-7by UARS command 7-15

rowsdefining maximum number returned for

UARS 6-6


Index I-9

RPCMAP (configuration statement) 12-8mapping RPCs for RDMS stored

procedures 6-28RPCs

compared to language requests 2-8definition xviiigeneral discussion 2-7mapping to transaction codes 12-8names 12-8not supported by user-defined transactions

6-19processing for UniAccess Transaction

Server 12-7routing by UACS 12-9sending

for ODBC applications 2-12for Open Client applications 2-12

RSA worksizedefined by UARS command 7-24defining by UADriver 5-25

Ssample applications A-1scalar functions

(see RDMS 2200 scalar functions)scale

of UAHS supported datatypes 9-23of UARS supported datatypes 6-24

securityTIP session control 4-3transaction-based systems 4-3UniAccess Security API 4-3validation of userids 4-2

segments 6-13SELECT statements (RDMS)

row limit 6-6syntax 6-13

SELECT statements (UAHS)extensions 9-10

general discussion 9-7limitations 9-11processing 9-6syntax 9-7

server program messageslisted B-1

Server-Library transactions(see also UniAccess Transaction Server,

user-written transactions)definition xviiiRPC processing 12-7

serversdefinition xvii, 1-2types of 1-4

SET ACCESSUARS command 7-6use in batched commands 7-6

SET AREASEARCHUAHS command 10-4

SET BLOBSIZEUARS command 7-8

SET DEBUGUAHS command 10-5

SET DISTTRANUAHS command 10-6UARS command 7-9

SET INTTOCHARUARS command 7-11

SET LONGCHARUARS command 7-12

SET RECOVERYUARS command 7-13use in batched commands 7-13

SET ROWLIMITUAHS command 10-7UARS command 7-15

SET SPACETRIMUAHS command 10-8UARS command 7-16



SET STRIPCTRLUAHS command 10-9UARS command 7-17

SET TRANSACTIVEUAHS command 10-10UARS command 7-18

SET TRANSOPTIONUAHS command 10-11UARS command 7-19

SET UNICODEUARS command 7-22

SET USERTRANUARS command 7-23

SET WORKSIZEUARS command 7-24use in batched commands 7-24

Shift-JISdesignating as Kanji identifier


SMS (Microsoft Systems Management Server)UADriver installation 3-6

sp_column_privilegesdescription 8-10result set 8-12

sp_columnsdescription

for RDMS 8-14for UAHS 11-6

result setfor RDMS 8-16for UAHS 11-8

sp_databasesdescription



sp_datatype_infodescription



values returned by data_typefor RDMS 8-19for UAHS 11-11

sp_fkeysdescription 8-24result set 8-26

sp_pkeysdescription 8-28result set 8-29

sp_server_infodescription 8-30information retrievable by 8-31result set 8-34

sp_special_columnsdescription



sp_sproc_columnsdescription 8-38result set 8-41

sp_statisticsdescription



sp_stored_proceduresdescription 8-47result set 8-50


Index I-11

sp_table_privilegesdescription 8-51result set 8-53

sp_tablesdescription



SQL commandsgrouping 6-14

SQL Query Analyzersample of Transact-SQL from A-2

SQL Server(see also Microsoft SQL Server)definition xviiin the UniAccess System 1-4

SQL_LONGCHARsupport for


SQL_UNICODEsupport for


SQLProcedureColumnsmodifying result set order for 5-26

statements (ODBC)maximum number per connection 5-19multiple active per connection

configuring 5-10, 5-18storage areas

(see RDMS 2200 storage areas)stored procedures

(see also RDMS 2200 stored procedures)discussion 2-4supported by Microsoft SQL Server 2-4

Sybasereferences E-2

Ttable names

modified by UADriver 5-16table ownership

modified by UADriver 6-9table_owner

descriptionfor RDMS 8-6for UAHS 11-3

table_qualifierdescription


tables(see RDMS 2200 tables, UAHS tables)

TDS (Tabular Data Stream)description 1-13

TDS supportrequired levels for UniAccess 10R3 4-2

thread accessdefined by UARS command 7-6defining with UADriver 5-24

thread recoverydefined by UARS command 7-13defining by UADriver 5-25

three-tier modelimplementation 2-5

timeout interactions 4-4TIP environment

discussion 1-13TIP session control

requirements 4-3TIP transactions

(see also language transactions, Server-Library transactions, UAHS, UARS, UAINFO, user-written transactions)



definition xviiidiscussion 1-13RPC processing 1-13user-defined for UARS 6-16

tracingfor UADriver D-7for UADTC D-10

trailing spacesremoving from character columns


Transaction Coordinator Connectivity Test 5-32, 13-11

results D-6Transaction Internet Protocol

description 13-7Transaction List

monitoring distributed transactions with 13-17

transaction managerdescription 13-3

Transaction Propertiesviewing for distributed transactions 13-19

Transaction Statisticsviewing for distributed transactions 13-18

transaction_namenot supported by UARS 6-19

transactions(see TIP transactions, distributed

transactions)description 13-2

Transact-SQLapostrophes and quotes 6-13coding examples

from a stored procedure A-3from SQL Query Analyzer A-2

naming conventions 6-12segments 6-13syntactic differences with RDMS 2200

SQL 6-11Translation DLL, customized

installation for UADriver 3-9translation options, UADriver

(see also ODBC Translation)host translation 5-20ODBC Translator 5-22

translation routinesparameter passed to

UADriver option 5-22UAHS command 10-11UARS command 7-19

support forUADriver option 5-20UAHS command 10-10UARS command 7-18

troubleshootingUADriver issues D-12UADriver tools D-1UADTC issues D-16UADTC logging D-10

two-and-a-half-tier modelimplementation 2-4

two-phase commit protocol (2PC)description 13-3

two-tier modelimplementation 2-3

UUACL (UniAccess Client-Library)

a component of UniAccess Transaction Client xiv

description 1-12UACS (UniAccess Communication Server)

configuring I.P. address for UADriver 5-14


Index I-13

configuring port for UADriver 5-14description 1-12

UADriverapplication notes 5-40attributes 5-34data sources

connecting to 5-33datatypes supported 5-5description 1-9features 5-2high speed connections

discussion 5-10setup options 5-19

illustration 1-10implementation level 5-3inclusion in UniAccess product packages

xivinstallation

network 3-5SMS 3-6

isolation levels supported 5-9lock levels supported 5-9number of connections supported 5-10number of statements supported 5-10ODBC translation support 5-10setup

advanced options 5-15general options 5-11test options D-1tracing options D-7translation options 5-20UAHS options 5-29UARS options 5-22

system requirements 3-2tools

test options D-1tracing options D-7

UARS modifications to SQL commands 6-6

UADTC (UniAccess Distributed Transaction Coordinator)

(see also distributed transactions)description 1-10location, UAdriver option 5-18log file D-10management

configuring settings 13-13starting and stopping 13-12

manually resolving transactions 13-22monitoring transactions 13-17port for communication with MS DTC

13-14role in distributed transaction processing

13-6setup

installation 13-11network topology 13-9

snap-in 13-17system requirements 3-2

UADTC Snap-inoverview 13-15Transaction List 13-17Transaction Properties 13-19Transaction Statistics 13-18

UAHS (UniAccess Hierarchical Service for DMS 2200)

a component of UniAccess ODBC Server for DMS 2200 xiv

area searchesUAHS command 5-31, 10-4

catalog RPC support 11-2client API support 9-4datatypes

correspondence 9-20, 9-24



debuggingdiscussion 9-18, D-9UADriver option 5-30UAHS command 10-5

description 1-11error messages B-21general discussion 9-2operating environment information 10-12operational settings 9-3relational mapping 9-12row limit

defined by UAHS command 10-7defining by UADriver 5-30

SQL support 9-7UAHS commands

list of 10-2relationships 10-3

UAHS databasedefault definition through UADriver 5-30

UAHS datatypes(see DMS 2200 datatypes)information returned by Catalog RPCs 11-4

UAHS Meta Databasediscussion 9-4SELECT statement processing 9-6support for Catalog RPCs 9-5

UAHS repository(see UAHS Meta Database)

UAHS SQL supportgeneral discussion 9-7SQL SELECT verb 9-7

UAHS tablescorrelation names 9-10item names 9-10

UAHSINFO (UAHS command)description 10-12information returned by 10-12result set 10-14

UAINFO (command)description 12-4

information returned by 12-5result set 12-6

UAINFO transactionuse with UADriver 1-9

UAMM (UniAccess Message Manager)error messages

detailed C-2general C-1

UARS (UniAccess Relational Service for RDMS 2200)

a component of UniAccess ODBC Server for RDMS 2200 xiv

catalog RPC support 8-2client API support 6-3datatypes

automatic conversions 6-26correspondence 6-20user datatypes 12-7

description 1-9general discussion 6-2operating environment information 7-26operational settings 6-3RDMS statements supported 6-4row limit

defined by UADriver 5-24defined by UARS command 7-15

user-defined transaction support 6-16UARS commands

list of 7-2relationships 7-3

UARSINFO (UARS command)description 7-26information returned by 7-26result set 7-29

UASL (UniAccess Server-Library)a component of UniAccess Transaction

Server xiv


Index I-15

datatypes supported 12-2description 1-11

UASL datatypescorrespondence to ODBC SQL datatypes

5-9received from ODBC SQL datatypes 5-8supported 12-2

UAUSER (configuration statement)ACCESS 5-24, 7-6AREASEARCH 5-31, 10-4DEBUG 5-30, 9-18, 10-5, D-9DOUNICODE 5-28, 7-8, 7-9, 7-18, 7-21,

7-22, 10-6, 10-11INTTOCHAR 5-26, 7-11LONGCHAR 5-28, 7-12MAXBLOBSIZE 5-25RECOVERY 5-25, 7-13ROWLIMIT 5-24, 7-15ROWLIMITH 5-18, 5-30, 10-7SCHEMA 5-23, 6-6SCHEMAH 5-30SPACETRIM 5-27, 7-16SPACETRIMH 5-31, 10-8STRIPCTRL 5-27, 7-17STRIPCTRLH 5-31, 10-9USERTRAN 5-27, 7-5, 7-23VERSION 5-24WORKSIZE 5-25, 7-24

UniAccess 10R3 PC Client CDcontains example applications A-1copyright information 0-iinstallation from 3-4

UniAccess ODBC Driver(see UADriver)

UniAccess ODBC Server for DMS 2200(see also UAHS)components of xivdefinition xviidiscussion 1-11

UniAccess ODBC Server for RDMS 2200(see also UARS)components of xivdefinition xviidiscussion 1-9

UniAccess PC Client(see UniAccess 10R3 PC Client CD)environment 1-14installation 3-1network requirements 3-3software requirements 3-2

UniAccess System for OS 2200architectural differences 4-5definition xvidocumentation xiv, E-1general considerations 4-2general discussion 1-8illustration 1-14levels of TDS support 4-2product suite xiii

UniAccess Transaction Client(see also UACL)components of xivdefinition xvidiscussion 1-12

UniAccess Transaction Server(see also Server-Library transactions, user-

written transactions, UASL)client support for 12-1components of xivdefinition xvidiscussion 1-11

Unisysreferences E-2

USE DEFAULTuse of 6-6

user datatypesdiscussion 4-5field descriptions 4-6



returned by UARS 4-7structure 4-6

user-defined transactions 5-27, 7-23(see also manual commit)errors 6-19initiating 7-5manual commit

UADriver option 5-27restrictions 6-18supported by UARS 6-16syntax 6-17

useridsrequiring validation 4-2

user-written transactions(see also Server-Library transactions,

UniAccess Transaction Server)catalog support for 12-3client support for 12-1language processing

discussion 12-9RPC processing 12-7use of UAINFO 12-4user datatypes for 12-7

VVARCHAR (datatype)

automatically converted to CHAR 5-26version

default defined through UADriver 5-24definition for RDMS 6-12

Visual Basiccoding example A-3

Wwild cards

use in RDMS Catalog RPCs 8-6use in UAHS Catalog RPCs 11-4

Windows operating systemstroubleshooting issues for UADTC D-16troubleshooting issues with UADTC D-16UniAccess PC Client requirements 3-2

workarounds (for UADriver)description 5-16

worksize(see RSA worksize)

uniaccess for os 2200 client guide · release 10r3: october 31, 2005 contents vii part iv:...

Documents