UniAccess for OS 2200 System Administration Guide
Title UniAccess 10R3 Product Suite
Release 10R3 Document Version: 1.00 Last Revised: October 31, 2005 Copyright 2005. All rights reserved.
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 Drive Reston, VA 20191 USA
Phone (703) 860-7808 FAX (703) 860-7820 E-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. 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. Contents Contents ......
Table of Contents Preface About This Book...... xvii Audience ...... xvii UniAccess System Product Suite ...... xvii Related Documentation...... xviii Conventions Used in this Manual...... xix Fonts and Format ...... xix Terminology ...... xx How This Manual Is Organized ...... xxii
Part I: Basics 1 Introduction to UniAccessSystem for OS 2200 1-1 Client/Server Architecture ...... 1-2 Client/Server Overview ...... 1-2 Types of Servers ...... 1-4 Types of Clients ...... 1-5 UniAccess System for OS 2200 ...... 1-6 UniAccess ODBC Server for RDMS 2200...... 1-6 UniAccess ODBC Server for DMS 2200 ...... 1-8 UniAccess Transaction Server ...... 1-8 UniAccess Transaction Client...... 1-9 The OS 2200 Environment ...... 1-9 Components of the UniAccess System Environment ...... 1-11 Remote Client/Server Components ...... 1-14 Communication Link Protocols ...... 1-15 Host Components ...... 1-16 UniAccess System for OS 2200 Components ...... 1-17
Release 10R3: October 31, 2005 iv UniAccess for OS 2200 System Administration Guide
2 Application Development Overview 2-1 Types of Requests ...... 2-2 Language Requests ...... 2-2 Remote Procedure Calls (RPCs)...... 2-2 Comparing Language Requests and RPCs ...... 2-3 Direct and Indirect Requests...... 2-4 Client Applications in the UniAccess System ...... 2-6 Remote Client Applications ...... 2-6 UniAccess Transaction Client Applications ...... 2-9 Server Applications in the UniAccess System ...... 2-11 Remote Server Applications ...... 2-11 UniAccess System Server Programs...... 2-12
Part II: Installation and Initial Configuration Procedures 3 Planning Your UniAccess Installation 3-1 Before You Begin ...... 3-1 Hardware and Software Requirements ...... 3-4 Explanation of Values in Pre-Installation Checklist ...... 3-6 4 Installing the UniAccess System 4-1 Installation Checklist ...... 4-1 Explanation of Installation Requirements...... 4-4 5 Planning Your UniAccess Configuration 5-1 Configuration Overview ...... 5-1 Configuration Requirements...... 5-3 Explanation of Configuration Requirements ...... 5-4 6 Managing the UniAccess System 6-1 Starting UniAccess Operations...... 6-2 Overview of UniAccess System Management ...... 6-3 UniAccess Configuration Management ...... 6-3 UniAccess Fixed-gate Management ...... 6-5 Steps in UniAccess System Management...... 6-8 Initial UniAccess System Execution...... 6-8 Subsequent UniAccess System Executions ...... 6-10 7 Preparing for ODBC and Open Client Users 7-1 Client Preparation Checklist ...... 7-1 Explanation of Actions in the Client Preparation Checklist ...... 7-2 Value Table for Client Users...... 7-6
Release 10R3: October 31, 2005 Contents v
Part III: Advanced UniAccess Procedures 8 Optimizing Performance 8-1 UniAccess Communication Server Optimization...... 8-2 UniAccess Message Manager Optimization...... 8-2 Database Performance ...... 8-4 Transaction Configuration and Design ...... 8-6 Registering Transactions...... 8-6 UARS Performance ...... 8-7 UAHS Performance ...... 8-9 Server-Library Program Design ...... 8-12 Host Performance ...... 8-16 Processor Utilization...... 8-16 I/O Utilization ...... 8-16 Memory Utilization — ClearPath IX, 2200/500, and 2200/900...... 8-16 9 Providing Security 9-1 Overview of UniAccess System Security...... 9-2 Component Security Responsibilities...... 9-3 Using UniAccess System Security Facilities ...... 9-4 TIP Session Control ...... 9-5 UniAccess Security API ...... 9-6 Userid and Password...... 9-6 UAUSER Definitions ...... 9-6 Co-existence With Unisys Security ...... 9-8 Security Options ...... 9-8 TIP Session Control ...... 9-8 UACS Background Security Requirement ...... 9-9 Console Privileges for UACS Commands ...... 9-10 10 Returning Server Program Messages to Client Applications 10-1 Server Program Message Overview ...... 10-1 Message Handling in the UniAccess System ...... 10-2 Messages Generated by UniAccess System Components ...... 10-3 Messages Generated by User-written Transactions ...... 10-5 Map and Message Definitions ...... 10-5 Map Definitions ...... 10-5 Message Definitions ...... 10-7 Server-Library Message Definitions...... 10-8
Release 10R3: October 31, 2005 vi UniAccess for OS 2200 System Administration Guide
Part IV: Special UniAccess Features 11 UniAccess Security API 11-1 Overview of the UniAccess Security API ...... 11-2 Security Transactions ...... 11-4 UniAccess Security API Message Formats ...... 11-5 Request Messages ...... 11-5 Notification Messages...... 11-7 UniAccess Security API Configuration ...... 11-10 UniAccess Sample Security Programs ...... 11-10 12 UniAccess Language Service Translation Routines 12-1 Overview of the Translation Routines ...... 12-2 Translation Routine Definitions ...... 12-4 UAClientToHost ...... 12-4 UAHostToClient ...... 12-5 Translation Routine Considerations ...... 12-8 Processing SQL Statements ...... 12-8 Processing Result Column Values ...... 12-9 Processing Catalog RPCs ...... 12-9 Coding the Translation Routines ...... 12-13 Modifying Data...... 12-14 Handling Errors...... 12-15 Assigning a Return Code ...... 12-16 Selecting an Error Message ...... 12-16 Compiling and Installing the Translation Routines ...... 12-17 13 Interactive SQL Parser 13-1 Overview of the Interactive SQL Parser...... 13-1 Invoking ISQL ...... 13-2 Entering ISQL Commands ...... 13-3 Viewing Data Results ...... 13-3 14 UniAccess Hierarchical Service 14-1 UAHS Overview...... 14-2 Terminology ...... 14-3 Building the UAHS Repository ...... 14-3 UAHS Meta Database Procedures ...... 14-4 DMS Schema Mapping...... 14-9 The Sample Schema ...... 14-9
Release 10R3: October 31, 2005 Contents vii
UAHS Database Definition ...... 14-15 UAHS Table Definition ...... 14-16 Retrieval Methods...... 14-30 Security ...... 14-33 UAHS Guidelines and Restrictions ...... 14-35 SCHEMADEF and TABLEDEF Reference ...... 14-38 SCHEMADEF ...... 14-38 TABLEDEF ...... 14-40 TABLEDEF Data Definition Entries ...... 14-43 15 UniAccess Distributed Transaction Coordinator 15-1 Distributed Transaction Support ...... 15-1 Recovery ...... 15-3 Standard OS 2200 Recovery...... 15-6 Application Group Recovery Procedures ...... 15-7 Executing UAIR ...... 15-10 UAIR in Interactive Mode ...... 15-11
Part V: Configuration and Operations References 16 UniAccess Source Configuration Statement Reference 16-1 Overview of UniAccess Configuration Statements ...... 16-2 Format of UniAccess Configuration Statements ...... 16-2 Syntax Rules ...... 16-2 Notation Conventions ...... 16-7 UniAccess Configuration Statements ...... 16-8 Source Configuration Files ...... 16-9 APPINF ...... 16-10 CABNUM ...... 16-13 CHARSET ...... 16-14 COMSRV ...... 16-16 HIERSRV ...... 16-36 LOCALE ...... 16-42 OSPARM ...... 16-44 RELSRV ...... 16-50 RPCMAP ...... 16-60 SERVER ...... 16-65 UAMESG ...... 16-68 UAMM ...... 16-70
Release 10R3: October 31, 2005 viii UniAccess for OS 2200 System Administration Guide
UAMMAP ...... 16-73 UASLCS ...... 16-76 UAUSER ...... 16-78 Summary of Configuration Statement Requirements...... 16-94 17 UniAccess System Processor Execution Statements 17-1 Overview of Execution Statements...... 17-1 Executing UACF...... 17-2 Executing UACS...... 17-6 Starting UACS with Default Runstreams ...... 17-7 Starting UACS with a Batch Runstream...... 17-7 18 UniAccess Reconfiguration Procedures 18-1 Modifying the Configuration File...... 18-1 Reconfigurations Relevant to UADT ...... 18-3 Reconfigurations Relevant to UACS ...... 18-3 Reconfigurations Relevant to UAMM ...... 18-4 Requirements for Specific Configurations ...... 18-5 Upgrading Product Key License...... 18-5 Adding New Users ...... 18-6 Adding Another UACS within an Application Group ...... 18-7 Adding a UACS within Another Application Group ...... 18-10 19 UACS Operations Reference 19-1 UniAccess Communication Server Management ...... 19-2 Executing UACS...... 19-2 Acknowledging Communications Server Connection Failure ...... 19-2 Acknowledging Communications Server Loss...... 19-2 Acknowledging MCB Initialization Loss ...... 19-3 Administering UACS ...... 19-3 Terminating UACS ...... 19-4 Console Commands for UACS...... 19-4 HELP ...... 19-6 LANGUAGE ...... 19-7 STATUS ...... 19-10 SYSLOG ...... 19-23 TERM ...... 19-24 TRACE ...... 19-27 UAMM ...... 19-29 UACS Security Logging...... 19-33 Security Event Log Entry Format...... 19-33
Release 10R3: October 31, 2005 Contents ix
Appendixes A UniAccess System Product Installation Files A-1 Installation Files for Production Modes A and B ...... A-2 Notes ...... A-6 Installation Files for Test Modes C and D ...... A-7 Notes ...... A-12 B Configuration Relationships B-1 Configuration Example...... B-2 OS 2200 Configuration...... B-3 Sybase SQL Server UNIX Configuration...... B-8 Microsoft SQL Server Configuration ...... B-8 Configuration Relationship Tables ...... B-9 Application Group Definition Relations...... B-9 Internationalization Relations ...... B-10 TSAM Relations ...... B-10 Activity Relations ...... B-11 Session Relations ...... B-11 UniAccess Service Relations ...... B-11 Network Address Relations ...... B-13 PID Definition Relations ...... B-14 Message Definition Relations...... B-14 User Definition Relations ...... B-15 UniAccess CPComm Configurations ...... B-16 UniAccess DCP Configurations ...... B-17 C UniAccess Sample Programs C-1 Sample System Overview...... C-2 UniAccess Sample Databases...... C-4 Functional View of the Sample Database ...... C-4 Logical View of the Sample Database ...... C-5 Physical View of the UASAMPLE RDMS 2200 Database ...... C-6 Physical View of the uasample SQL Server Database ...... C-7 Constraints, Triggers, and Views ...... C-8 SQL Server Stored Procedures ...... C-9 UniAccess Sample Programs ...... C-10 UniAccess Transaction Server Programs ...... C-10 UniAccess Transaction Client Programs ...... C-12 UniAccess PC Client Programs ...... C-16
Release 10R3: October 31, 2005 x UniAccess for OS 2200 System Administration Guide
Setting up the Sample System ...... C-16 RDMS 2200 Database Setup ...... C-17 SQL Server Database Setup ...... C-18 UniAccess Transaction Server Sample Setup...... C-19 UniAccess Transaction Client Sample Setup ...... C-22 PC Client Sample Setup ...... C-23 Additional Sample Setup Information ...... C-23 D UniAccess System Messages D-1 Overview of UniAccess System Messages...... D-2 Operational Messages ...... D-2 UACS Trace File and Console Messages ...... D-2 Security Event Log Messages ...... D-38 UACF Error Messages ...... D-40 UACF Warnings ...... D-47 UAMM Error Messages ...... D-50 UAIR Error Messages ...... D-53 SCHEMADEF Error Messages ...... D-56 TABLEDEF Error Messages ...... D-60 Server Program Messages...... D-69 UniAccess System Server Messages ...... D-69 UAHS Error Messages ...... D-88 Client Program Messages ...... D-94 Server Messages returned by Client-Library ...... D-94 Client Messages returned by Client-Library...... D-94 E UniAccess System Tables E-1 Overview of AIS-Created RDMS 2200 Tables ...... E-1 UniAccess ODBC Server for RDMS 2200 Environment...... E-2 UniAccess Transaction Server with ODBC Server for RDMS 2200 Environment ...... E-2 SPT_PROCEDURE_COLUMNS ...... E-3 SPT_PROCEDURES ...... E-6 F Troubleshooting and Problem Reporting F-1 Troubleshooting UniAccess ...... F-2 UniAccess Tools for Locating Problems ...... F-2 Post Installation Issues ...... F-3 Configuration Issues ...... F-3 Starting UACS ...... F-5
Release 10R3: October 31, 2005 Contents xi
Transaction Client Issues ...... F-6 UniAccess Server Issues...... F-7 Accessing LINC Data ...... F-13 Debugging UniAccess Programs ...... F-15 Problem Reporting ...... F-16 Diagnostic File Information ...... F-17 Problem Reporting Form ...... F-20 G References G-1 AIS References ...... G-1 Microsoft References ...... G-2 Sybase References ...... G-2 Unisys References...... G-2
Glossary
Index
Release 10R3: October 31, 2005 xii UniAccess for OS 2200 System Administration Guide
List of Figures
Figure 1-1: Client/Server Model ...... 1-3 Figure 1-2: UniAccess System for OS 2200 Implements Client/Server Architecture ...... 1-11 Figure 1-3: UniAccess System Components ...... 1-13 Figure 1-4: UACS Communications Environment ...... 1-19 Figure 1-5A: UACL and UASL Using the Same UACS...... 1-20 Figure 1-5B: UACL and UASL Using Different UACSs ...... 1-20 Figure 2-1: Examples of Direct and Indirect Requests to UniAccess System Servers ...... 2-5 Figure 2-2: Remote Client Applications ...... 2-6 Figure 2-3: OS 2200 Client Applications ...... 2-6 Figure 2-4: Remote Server Applications ...... 2-11 Figure 2-5: OS 2200 Server Applications ...... 2-11 Figure 6-1: The UniAccess Configuration Management Design ...... 6-4 Figure 6-2: UAFG Shared Subsystem Overview ...... 6-6 Figure 6-3: Steps in Initially Starting UniAccess Operations ...... 6-8 Figure 8-1: UniAccess Fixed-gate Data Banks ...... 8-18 Figure 11-1: UniAccess Security API Activities ...... 11-3 Figure 14-1: Building the UAHS Repository ...... 14-4 Figure 14-2: Office and Employee Sample Data ...... 14-13 Figure 14-3: Employee and Task Diagram Sample Data ...... 14-14 Figure 14-4: Single-Level Table — TASK ...... 14-18 Figure 14-5: Single-Level Table — DEPENDANT ...... 14-18 Figure 14-6: Allowable Combinations for UAHS Tables ...... 14-19 Figure 14-7: Two-Level Table — STAFF ...... 14-21 Figure 14-8: Root Record Selection ...... 14-22 Figure 14-9: Owner-Driven Set Mapping — INSURED_DOWN ...... 14-24 Figure 14-10: Member-Driven Set Mapping — INSURED_UP ...... 14-24 Figure 14-11: Owner-Driven Manual Set Mapping — ASSIGNMENTS_DOWN . 14-26 Figure 14-12: Member-Driven Manual Set Mapping — ASSIGNMENTS_UP . . . 14-26 Figure 14-13: Array Mapping — ACTIVITIES ...... 14-28 Figure 15-1: UniAccess Distributed Transaction Processing ...... 15-2 Figure 15-2: Situations Requiring Manual Intervention to Recover a Participating Transaction ...... 15-5 Figure 15-3: General Sequence of UAIR Prompts ...... 15-12
Release 10R3: October 31, 2005 Contents xiii
Figure 16-1: Example of Syntax Rules for UniAccess Configuration Statements ...... 16-3 Figure B-1: Sample Configuration ...... B-2 Figure B-2: Sample Configuration for DCP ...... B-18 Figure C-1: Components of the UniAccess Sample System ...... C-3
Release 10R3: October 31, 2005 xiv UniAccess for OS 2200 System Administration Guide
List of Tables Table 1: System Administration Guide Organization ...... xxiii Table 1-1: Components of the UniAccess System Environment ...... 1-12 Table 1-2: Product Groups in the UniAccess System ...... 1-17 Table 3-1: Steps in Initial UniAccess System Administration ...... 3-2 Table 3-2: Pre-Installation Checklist — Host Hardware Levels, Software Levels, and Configurations ...... 3-4 Table 4-1: UniAccess Installation Checklist ...... 4-2 Table 5-1: UniAccess Configuration Checklist ...... 5-3 Table 6-1: Steps in Starting UniAccess Operations ...... 6-2 Table 7-1: Client Preparation Checklist ...... 7-2 Table 7-2: Transaction Service Options Available to ODBC Clients ...... 7-4 Table 7-3: Required Values for ODBC and Open Client Users ...... 7-6 Table 8-1: UAMM Primary Storage Parameters ...... 8-3 Table 8-2: VALTAB Requirements ...... 8-6 Table 8-3: VALTAB Settings Affecting UARS Performance ...... 8-7 Table 8-4: VALTAB Settings Affecting UAHS Performance ...... 8-9 Table 8-5: Creation and Modification of UAFG Data Banks* ...... 8-17 Table 9-1: Privileges for UACS Console Commands ...... 9-10 Table 12-1: UAClientToHost Parameters ...... 12-4 Table 12-2: UAHostToClient Parameters ...... 12-7 Table 12-3: UARS Catalog RPC Translation ...... 12-10 Table 12-4: UAHS Catalog RPC Translation ...... 12-12 Table 14-1: Steps in Creating the UAHS Meta Database ...... 14-5 Table 14-2: Keyed Access and Area Search Criteria ...... 14-31 Table 14-3: UAHS Support for DDL/SDDL Syntax ...... 14-34 Table 14-4: UAHS Functionality ...... 14-35 Table 14-5: DMS Schema/Subschema Support ...... 14-35 Table 14-6: Restrictions on Schema Entities ...... 14-36 Table 14-7: Relational Mapping Guidelines ...... 14-37 Table 14-8: SQL Syntax Rules ...... 14-37 Table 14-9: TABLEDEF Reserved Word List ...... 14-48 Table 16-1: UniAccess Configuration Statements ...... 16-8 Table 16-2: Source Configuration File Assignments ...... 16-9 Table 16-3: HIERSRV Parameter/ Client Option Correspondences ...... 16-36 Table 16-4: RELSRV Parameter/ Client Option Correspondences ...... 16-50 Table 16-5: RPCMAP Record Usage ...... 16-60
Release 10R3: October 31, 2005 Contents xv
Table 16-6: Summary of Configuration Statement Requirements ...... 16-94 Table 18-1: Configuration Statement Information Relevant to UADT, UACS, and UAMM ...... 18-2 Table 19-1: UACS Console Commands ...... 19-5 Table A-1: UniAccess 10R3 Product Installation Files for Production Modes A and B ...... A-2 Table A-2: UniAccess 10R3 Product Installation Files for Test Modes C and D ...... A-7 Table C-1: Functional View of the Sample Database ...... C-4 Table C-2: Logical View of the Sample Database ...... C-5 Table C-3: Physical View of the UASAMPLE RDMS 2200 Database ...... C-6 Table C-4: Physical View of the uasample SQL Server Database ...... C-7 Table C-5: UniAccess Stored Procedures for SQL Server ...... C-9 Table C-6: UniAccess Server-Library Samples ...... C-10 Table C-7: UniAccess Client-Library Samples ...... C-13 Table C-8: Sample System Components for UniAccess Product Packages ...... C-16 Table D-1: Values for CLIENTMSGs CMSG-SEVERITY Field ...... D-95 Table E-1: SPT_PROCEDURE_COLUMNS Definition ...... E-3 Table E-2: SPT_PROCEDURES Definition ...... E-6
Release 10R3: October 31, 2005 xvi UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 Preface Preface ......
About This Book This manual accompanies the UniAccess System for OS 2200 product suite. It describes all installation and administrative aspects of the UniAccess System for OS 2200. The manual describes the components of the UniAccess System and how to configure them to interface with Unisys 2200 components.
Audience
The UniAccess for OS 2200 System Administration Guide is written for system administrators who must install, configure, manage, and maintain security for the UniAccess System in an OS 2200 environment.
UniAccess System Product Suite
This manual discusses configuration and management 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.
Applied Information Sciences (AIS) provides the following product packages:
UniAccess Transaction Client for OS 2200, which includes: UACL (UniAccess Client-Library) ISQL for OS 2200 (Interactive SQL Parser) UniAccess core components
Release 10R3: October 31, 2005 xviii UniAccess for OS 2200 System Administration Guide
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 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 utility Tabledef utility 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). Thus, the discussion of the configuration and management of these components in this manual is relevant to all product packages.
Related Documentation
In addition to this manual, the following documents are included in the UniAccess System for OS 2200 product suite:
UniAccess for OS 2200 Client Guide This manual describes the development and use of ODBC and Open Client applications that interface with UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200. It includes information on the UniAccess ODBC Driver, UniAccess Relational Service, and UniAccess Hierarchical Service.
Release 10R3: October 31, 2005 Preface xix
UniAccess for OS 2200 Client-Library Programming Reference This 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.
UniAccess for OS 2200 Server-Library Programming Reference This 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.
In addition to the above AIS documentation, you should have access to appropriate OS 2200 and Sybase documentation to configure, install, and manage UniAccess System products. Appendix G lists relevant manuals.
Conventions Used in this Manual As 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 Client-Library; SQL Server.
• Publication names and chapter names within publications are italicized: UniAccess for OS 2200 System Administration Guide; see Chapter 9, Providing Security.
• Bold type and italics are used for emphasis in the text.
In addition, certain fonts and conventions represent specific object types:
• The following terms are in regular typeface, all capital letters:
— Constants within configuration statements and console commands: COMSRV APPNUM; STATUS PID.
Release 10R3: October 31, 2005 xx UniAccess for OS 2200 System Administration Guide
— Host-based objects and values such as datatypes, symbolic values, and file names: DATETIME; TDS-OK; SYS$LIB$*UAUTIL.
• The following terms are italicized:
— Variables within console commands and configuration: application- number;
— PC-based file names: sql.ini.
• The following terms are in Arial bold:
— Client-Library and Server-Library function names: CTBINIT; TDINIT.
— Other commands in the text: a SELECT statement.
• In examples, information displayed on a computer screen is shown in Courier font: TRACE LEVEL CHANGED TO LOW.
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 systems, the following terms are 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.
Release 10R3: October 31, 2005 Preface xxi
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 usually 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.
Release 10R3: October 31, 2005 xxii UniAccess for OS 2200 System Administration Guide
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, TIP transactions may act as either clients or as servers. Client transactions are created with UACL (Client-Library) functions; server transactions are created with UASL (Server-Library) functions. The term Server- Library transaction refers to user-written UASL transactions as well as to the UARS and UAHS transactions (specific UASL-built transactions that process 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 Organized This manual is designed as both a guide and a reference. Section I, Basics, provides important introductory information about the UniAccess System. Section II describes procedures for installing and initially configuring the UniAccess System. These chapters should be read in the order given. Sections III and IV describe advanced procedures and selected UniAccess components. These chapters may not apply to all sites. Section V and the Appendixes provide reference material that will be valuable to both first-time and long- time users of the UniAccess System.
Table 1 shows the major sections of this manual and describes the contents of its chapters and appendixes.
Release 10R3: October 31, 2005 Preface xxiii
Table 1: System Administration Guide Organization
Manual Organization Page
Section I: Basics
1 Introduction to UniAccess System for OS 2200 1-1 Provides a general discussion of client/server architecture and an overview of the UniAccess System for OS 2200. 2 Application Development Overview 2-1 Describes the types of requests available through the UniAccess System and discusses the basics of processing client and server applications.
Section II: Installation and Initial Configuration Procedures Installation and Initial Configuration Procedures 3-1 3 Planning Your UniAccess Installation Lists the steps necessary to start the UniAccess System and provides a checklist of hardware and software requirements for use with the UniAccess 4-1 System. 4 Installing the UniAccess System Describes the procedures for installing the UniAccess System for OS 2200. Provides a checklist of required configurations, including those for the 5-1 UARS, UAHS, and UAINFO transactions. 5 Planning Your UniAccess Configuration 6-1 Provides a checklist of required configurations for UniAccess components and OS 2200 components that interface with the UniAccess System.
6 Managing the UniAccess System 7-1 Provides an overview of UniAccess System management. Explains the implementation and management of the UniAccess Fixed-gate subsystem, including the initialization of UAMM. 7 Preparing for ODBC and Open Client Users Provides a checklist of setup values for installing and configuring workstation software. The system administrator may distribute the completed checklist to client users.
Release 10R3: October 31, 2005 xxiv UniAccess for OS 2200 System Administration Guide
Manual Organization Page
Section III: Advanced UniAccess Procedures
8 Optimizing Performance 8-1 Offers suggestions for improving the performance of the UniAccess System for OS 2200. 9 Providing Security Explains how to use standard OS 2200 security facilities in conjunction with 9-1 UniAccess System features to achieve the security desired at your site.
10 Returning Server Program Messages to Client Applications 10-1 Explains how the UniAccess System for OS 2200 handles server program messages and what features are available to customize message handling.
Section IV: Special UniAccess Features 11-1 11 UniAccess Security API Explains how to configure the UniAccess Security API to allow the UniAccess System to communicate with local or third-party security systems. 12-1 12 UniAccess Language Service Translation Routines Explains how to create and use the user-written translation routines supported by the UniAccess Relational Service for RDMS 2200 and the UniAccess Hierarchical Service for DMS 2200.
13 Interactive SQL Parser 13-1 Describes how to use the Interactive SQL (ISQL) processor in the UniAccess Transaction Client environment. 14 UniAccess Hierarchical Service Provides an overview of the UniAccess Hierarchical Service (UAHS) design 14-1 and describes the function of system components. Explains how to use the SCHEMADEF and TABLEDEF utility programs to create the UAHS Meta Database. Summarizes UAHS support of DMS and SQL.
15 UniAccess Distributed Transaction Coordinator 15-1 This chapter provides an overview of UniAccess Distributed Transaction Coordinator (UADTC), defines the syntax of command lines to execute the UniAccess Integrated Recovery Utility (UAIR), and explains how to use UAIR in interactive mode.
Release 10R3: October 31, 2005 Preface xxv
Manual Organization Page
Section V: Configuration and Operations References Configuration and Operations References 16-1 16 UniAccess Source Configuration Statement Reference Describes the format and use of the configuration statements needed to configure all host components of the UniAccess System. 17-1 17 UniAccess System Processor Execution Statements Defines the syntax of command lines to execute the UniAccess System processors, UACF and UACS. 18-1 18 UniAccess Reconfiguration Procedures Outlines the procedures for modifying the UniAccess Configuration File in general and provides specific instructions for common reconfigurations. 19-1 19 UACS Operations Reference Explains UACS management and describes the UACS console commands.
Appendixes
A UniAccess System Product Installation Files A-1 Lists all of the UniAccess System files and describes their contents. B Configuration Relationships B-1 Describes in detail the relationships in the UniAccess System environment.
C UniAccess Sample Programs C-1 Describes the components of the UniAccess Sample System, including the RDMS and SQL sample databases. Explains how to set up the sample programs. D UniAccess System Messages Explains UniAccess System messages types and lists all operational and D-1 server program messages. E UniAccess System Tables Defines the AIS-Created RDMS tables SPT_PROCEDURE_COLUMNS E-1 and SPT_PROCEDURES. F Troubleshooting and Problem Reporting Provides troubleshooting assistance for commonly encountered errors within the UniAccess System. Includes a problem reporting form and F-1 outlines procedures that will assist in problem resolution. G References Lists technical references pertaining to the UniAccess System for OS 2200. G-1
Release 10R3: October 31, 2005 xxvi UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 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 UniAccess System for OS 2200 1-6 UniAccess ODBC Server for RDMS 2200 1-6 UniAccess ODBC Server for DMS 2200 1-8 UniAccess Transaction Server 1-8 UniAccess Transaction Client 1-9 The OS 2200 Environment 1-9 Components of the UniAccess System Environment 1-11 Remote Client/Server Components 1-14 Communication Link Protocols 1-15 Host Components 1-16 UniAccess System for OS 2200 Components 1-17
Release 10R3: October 31, 2005 1-2 UniAccess for OS 2200 System Administration Guide
Client/Server Architecture The 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.
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-3
client server action request for data
results
server
client request for data request for data
results results
request to take an action
Figure 1-1: Client/Server Model
Note For a discussion of types of client/server configurations, see Chapter 2 of the UniAccess for OS 2200 Client Guide.
Release 10R3: October 31, 2005 1-4 UniAccess for OS 2200 System Administration Guide
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.
• 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
— UniAccess Transaction Server for OS 2200 (UASL transactions), see page 1-8
— UniAccess ODBC Server for RDMS 2200 (UARS transaction), see page 1-6
— UniAccess ODBC Server for DMS 2200 (UAHS transaction), see page 1-8
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-5
• Non-UniAccess Servers
— SQL Servers, including stored procedures on a SQL server, see page 1-14
— SYBASE Open Server programs, see page 1-14
— RDMS 2200 stored procedures (supported by UniAccess ODBC Server for RDMS 2200), see page 1-7.
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 (see page 1-7), 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.
Release 10R3: October 31, 2005 1-6 UniAccess for OS 2200 System Administration Guide
UniAccess System for OS 2200 The 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 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.
Programmers working in the UniAccess Transaction Server environment generally write OS 2200 TIP transactions that process client requests. A TIP transaction must be associated with each client request to the UniAccess Transaction Server. Programmers working in the UniAccess Transaction Client environment write the applications that will make requests of remote servers or of local UniAccess servers. No OS 2200 programming is required of those working with UniAccess ODBC Server for RDMS 2200 nor UniAccess ODBC Server for DMS 2200, as the required TIP transaction for each is provided.
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
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-7
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 remote clients, processes the requests using the RDMS 2200 interpretive SQL interface, and returns results to clients. In addition, UARS supports RDMS 2200 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 2.)
UniAccess ODBC Driver
UADriver (UniAccess ODBC Driver) allows Microsoft ODBC-compatible client applications and tools to have ODBC access to OS 2200. This means that OS 2200 data can be accessed from a variety of PC tools. Microsoft’s ODBC, an industry standard for client-server database access, is an open, vendor-neutral programming interface for database connectivity. Using applications written in a single SQL dialect, ODBC users can access a variety of databases.
In the UniAccess System, UADriver allows access to RDMS 2200 through the UARS transaction, to DMS 2200 through the UAHS transaction, and to a variety of OS 2200 data from user-written, UASL-based transactions. The UAINFO transaction is provided to allow UADriver to operate in a non-UARS, non-UAHS environment. (The UniAccess ODBC Driver is explained in more detail in the UniAccess for OS 2200 Client Guide.)
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; it exploits loosely coupled systems to provide scalable performance.
Release 10R3: October 31, 2005 1-8 UniAccess for OS 2200 System Administration Guide
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 14.)
UniAccess Transaction Server
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.
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-9
UASL is implemented in the extended mode environment. It supports UCS COBOL and includes an interface to the UCS C language. In addition, an ASCII COBOL interface allows programmers to write Server-Library applications for the basic mode environment. The UniAccess for OS 2200 Server-Library Programming Reference documents UASL and all Server-Library functions, as well as the two programming language interfaces.
UniAccess Transaction Client
UniAccess Transaction Client is the group of UniAccess System products that provide client capabilities on the OS 2200 system. It allows Unisys mainframe-based applications remote access to Microsoft and Sybase SQL Servers, as well as any Open Server applications. In addition, Transaction Client applications can access OS 2200 TIP transactions through the UniAccess Transaction Server and ODBC Servers. UniAccess Transaction Client includes the UniAccess Client-Library and the ISQL parser; it also includes UACS—the communication server—and other core components.
UniAccess Client-Library
UACL (UniAccess Client-Library) is the library of functions that allows programmers to write client applications on the OS 2200 system. These applications may make requests of Server-Library transactions on an OS 2200 host or of other servers in the same network environment, such as SQL Servers and Open Server applications. And, like other Open Clients, UACL-written applications can issue either RPCs or language commands; they can invoke stored procedures on servers.
UACL is implemented in the extended mode environment. It supports UCS COBOL and includes an interface to the UCS C language. The UniAccess for OS 2200 Client-Library Programming Reference documents UACL and all Client-Library functions, as well as the UCS C programming language interface.
The OS 2200 Environment
The UniAccess System utilizes the OS 2200 TIP environment to allow for the development and execution of user-written programs. Those programs that are created and run in a TIP environment are called transactions. In the UniAccess System, TIP transactions may exist as either clients or servers. TIP transactions built with UACL functions are client transactions; those built with UASL functions are server transactions. UACL and UASL library functions enable the communication of transactions with UACS, the central communications processor.
Release 10R3: October 31, 2005 1-10 UniAccess for OS 2200 System Administration Guide
UASL (Server-Library) programs are almost always TIP transactions and will always be considered as such in the UniAccess documentation. UACL programs, however, are not restricted to the TIP environment; they can also be demand or batch programs. They will generally be referred to as UACL (Client-Library) applications.
Client-Library and Server-Library functions use SYBASE TDS (Tabular Data Stream) to exchange all messages between clients and servers, just as a SQL Server would. TDS is the application layer, self-describing protocol used by the Microsoft architecture for client- to-server and server-to-server interoperability. For client requests, TDS describes either language text or RPC parameters (length, datatype, and value). For server replies, TDS supplies column descriptions (length, type, name, and so on), row data values, return parameters, and error and status messages. TDS also describes client login and security information.
Figure 1-2 illustrates how the UniAccess System for OS 2200 might implement client/ server architecture on a LAN network.
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-11
Workstation
OS 2200 UADriver
UniAccess Transaction Server Workstation
Open UniAccess Client ODBC Server for RDMS 2200 Windows UniAccess MS SQL ODBC Server for Server Arrows indicate DMS 2200 the client to server requests. Responses UNIX traverse the UniAccess same path. Transaction Client SQL Server
Figure 1-2: UniAccess System for OS 2200 Implements Client/Server Architecture
Components of the UniAccess System Environment The UniAccess System environment is comprised of components from several sources. This section provides a list of these components, followed by a more detailed discussion of their functions and how they interface with one another. (For a specific list of hardware and software requirements, see Chapter 3.)
Release 10R3: October 31, 2005 1-12 UniAccess for OS 2200 System Administration Guide
Table 1-1: Components of the UniAccess System Environment
Components of the Requirement Discussion UniAccess Environment1
Remote Client/Server Components page 1-14 SQL Server optional
Open Client software optional2 SYBASE Open Server software optional
UADriver (UniAccess ODBC Driver) [#1] optional2
UADTC (UniAccess Distributed Transaction Coordinator) [#2] optional2 used in conjunction with MS DTC Connection Link Protocols page 1-15 TCP/IP (Transmission Control Protocol/Internet Protocol) required TDS (SYBASE Tabular Data Stream) required Host Components—Unisys ClearPath IX, 2200, or required page 1-16 1100/90 Series system with the following: TCP/IP access (e.g., ATMC and a router, HLC, Ethernet CA, etc.) required Unisys OS 2200 communication services — CMS 1100 or required CPComm, and MCB 3
Unisys OS 2200 transaction processing environment (TIP) required3 Unisys OS 2200 database management systems (such as optional RDMS 2200, DMS 2200, and PCIOS) UniAccess System for OS 2200 Components
UACS (UniAccess Communication Server) [#3] required2 page 1-18
UAMM (UniAccess Message Manager) [#4] required2 page 1-21
UADT (UniAccess Data Manager) [#5} required2 page 1-21 UACL (UniAccess Client-Library) [#6] optional page 1-21 UASL (UniAccess Server-LIbrary [#7] optional page 1-22 UAHS (UniAccess Hierarchical Service for DMS 2200) [#8] optional page 1-23 UARS (UniAccess Relational Service for RDMS 2200) [#9] optional page 1-23
1 The numbers [#n] next to product names correspond with the numbered components in Figure 1-3. 2 Included with UniAccess Server product packages. 3 MCB is optional for UniAccess Transaction Client.
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-13
Open (1) UADriver Open SQL (2) UADTC Server MS DTC Client Server Open Client
communication OS 2200 host link protocols communications services
(3) UniAccess Communication Server
(4) UniAccess Message Manager (5) UniAccess Data Manager (6) UniAccess Client-Library (7) UniAccess Server-Library
user-written user-written (8) UniAccess (9) UniAccess TIP TIP Hierarchical Relational transactions transactions Service Service
transaction processing (TIP) environment other host data DMS 2200 RDMS 2200
Figure 1-3: UniAccess System Components
Release 10R3: October 31, 2005 1-14 UniAccess for OS 2200 System Administration Guide
Remote Client/Server Components
The UniAccess System works in conjunction with products that operate in the Microsoft client/server model, including SYBASE Open Server and Open Client products and SQL Servers. Remote applications communicate with UACS just as they would with a SQL Server. They run on the same workstations and make the same types of requests.
SQL Servers
SQL Servers are database servers that accept remote procedure calls (RPCs) or language requests written in Transact-SQL. A SQL Server manages multiple databases and multiple users, keeps track of the actual location of data on disks, maintains a mapping of logical data descriptions to physical data storage, and maintains data and procedure caches in memory. There are two implementations of SQL Server: Microsoft SQL Server and Sybase SQL Server. While they provide many similar features, only Microsoft SQL Server can currently participate in server-to-server calls to a UniAccess server.
Open Client Software
Open Client software includes a variety of clients tools that may be used in the Microsoft client/server architecture. Remote Open Client applications include SYBASE Open Client programs and stored procedures on a SQL Server.
SYBASE Open Server Software
SYBASE Open Server allows programmers to develop server applications that can be used on a variety of platforms. An Open Server application is created independently, using the building blocks provided by SYBASE Open Server library functions. It can be programmed to accept any client request.
UniAccess ODBC Driver
The UniAccess ODBC Driver is AIS’s implementation of Microsoft’s Open Database Connectivity (ODBC). The driver processes ODBC function calls from a wide variety of client tools, submits SQL language requests and RPCs to the appropriate UniAccess transaction, and returns results to the application. It works in conjunction with the Microsoft supplied Driver Manager, the UARS and UAHS transactions with their associated catalog RPCs, the UAINFO transaction, user-written UASL transactions, and other UniAccess System components, appearing to the client application as one processing unit.
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-15
UniAccess Distributed Transaction Coordinator
The UniAccess Distributed Transaction Coordinator (UADTC) facilitates access to OS 2200-based, distributed-transaction-enabled resources. UADTC serves as a secondary transaction manager with MS DTC serving as its primary transaction manager. Two-phase commit (2PC) messages between MS DTC and UADTC are exchanged using the Transaction Internet Protocol. UADTC forwards 2PC messages to UACS using the TDS protocol. The COM+ component, supported by the UniAccess ODBC Driver, issues DML commands to the OS 2200 data source via TDS and interacts with UADTC via DCOM.
Communication Link Protocols
A connection between a remote component and UACS uses the same communication link setup as a connection between a client and a SQL Server or between SQL Servers. Communication links are established through TCP/IP and TDS protocols and are identical to those in Microsoft configurations. Likewise, communication links between one SQL Server and another remain the same.
TCP/IP
The UniAccess System for OS 2200 is designed to work in a TCP/IP-based network environment. TCP/IP (Transmission Control Protocol/Internet Protocol) is an open systems network architecture and set of protocols that provides connection establishment and data transmittal between clients and servers.
TDS
SYBASE Tabular Data Stream (TDS) is an application-level protocol used to transfer information between clients and servers. It describes the form and content of:
• Client login information
• Client requests
• Row and column information in results data
• Security information.
Release 10R3: October 31, 2005 1-16 UniAccess for OS 2200 System Administration Guide
Host Components
The UniAccess System for OS 2200 runs on Unisys 1100/90 Series, 2200 Series, and ClearPath IX systems. It takes advantage of existing Unisys products to provide communication services and to access data stored on a host. Required Unisys products are listed in Chapter 3. (For more information about Unisys products, consult the appropriate Unisys manuals listed in Appendix G.)
Communications Services
CMS 1100 (Communications Management System 1100) and CPComm (Cooperative Processing Communications Platform) are the host communications software products that provide a processing path through which application systems on the host can access the services of the data transport network.
Telcon provides wide-area network-management functions and enables DCPs (Distributed Communications Processors) to connect to hosts, other DCPs, terminals, remote concentrators, and other communication devices.
UACS uses CMS (and optionally, Telcon) or CPComm to establish network connections and to send and receive requests and results across a TCP/IP network.
MCB (Message Control Bank)
MCB is the message-handling component of the OS 2200 integrated recovery system. UACS uses MCB to initiate all Server-Library transactions.
TIP
TIP is the transaction processing environment supported on the Unisys OS 2200 system. It enables users to execute individual transactions that access host resources with a minimum of system software overhead. TIP is the transaction management environment used by the UniAccess System for OS 2200 as an online transaction processor. (See the discussion on page 1-9 for information on UniAccess System transactions within the OS 2200 TIP environment.)
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-17
Host Data Management Systems
With the UniAccess System, you can access host data stored in any OS 2200 resource, such as RDMS 2200 and DMS 2200 databases and PCIOS files. The OS 2200 programmer writes Server-Library transactions to access stored data. UniAccess Relational Service for RDMS 2200 supplies a transaction to access RDMS 2200 tables; UniAccess Hierarchical Service for DMS 2200 supplies a transaction to access DMS 2200 records.
UniAccess System for OS 2200 Components
The components of the UniAccess System are described in this section. Figure 1-3 illustrates how these components interact within the UniAccess System environment. Table 1-2 indicates which components are included in each of AIS’s four product packages.
Table 1-2: Product Groups in the UniAccess System
UniAccess System for OS 2200
UniAccess UniAccess UniAccess UniAccess Components Transaction Transaction ODBC Server ODBC Server Client Server for DMS 2200 for RDMS 2200
(1)1 UADriver * * * (2) UADTC * * (3) UACS * * * * (4) UAMM * * * * (5) UADT * * * * (6) UACL * (7) UASL * (8) UAHS * (9) UARS *
1 The above numbers correspond with the numbered components illustrated in Figure 1-3.
The functioning of UACS, UADT, and UAMM is transparent to the user. Although they might be seen primarily as interface components, for simplicity of discussion, this manual
Release 10R3: October 31, 2005 1-18 UniAccess for OS 2200 System Administration Guide
refers to them as client components (UniAccess Transaction Client) when they function with UACL as an Open Client, and as server components (UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, or UniAccess ODBC Server for DMS 2200) when they function with UASL, UARS, and UAHS as an Open Server.
The following sections explain how individual OS 2200 components of the UniAccess System interface with other components of the System.
UACS (UniAccess Communication Server)
UACS provides the central communications link between client and server applications. All requests sent from a client application to a server application and all replies returned from a server application to a client application pass through UACS. It uses the following components to transport messages between clients and servers, as depicted in Figure 1-4.
• CMS or CPComm provides TCP/IP transport support for remote client or server applications.
• UAMM passes messages between UACS and UniAccess System transactions.
• MCB schedules Server-Library transactions.
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-19
UniAccess Communication Remote Server UACL Server Applications Applications
TCP/IP UAMM
CMS/ UAMM CPComm
Remote UASL Client Transactions Applications
UAMM TCP/IP MCB MCB
Figure 1-4: UACS Communications Environment
When UACS receives a request from a local (UniAccess Transaction Client) client through UAMM, it processes the request as follows:
• Determines which remote server applications or local UniAccess Server- Library transactions to call and forwards the client request to the server application using CMS or CPComm
• Accepts results from the processing application or transaction through CMS or CPComm and returns them to the Client-Library application.
Release 10R3: October 31, 2005 1-20 UniAccess for OS 2200 System Administration Guide
When UACS receives a request from a remote client through CMS or CPComm, it processes the request as follows:
• Establishes a session with TIP (if TIP session control is active) using the userid and password received with the client request
• Determines which Server-Library transaction to call, schedules the transaction using MCB, and passes the client request to the transaction using UAMM
• Accepts results from the Server-Library transaction through UAMM and returns them to the requesting client through CMS or CPComm.
UACS must exist in each application group in which a UniAccess product will run; multiple UACSs may be configured in a single application group. Clients can access multiple hosts with a UACS running on each; they can also access multiple UACSs on the same host.
Note that when a Client-Library application sends a request to a Server-Library transaction, both client and server can use a single UACS (as illustrated in Figure 1-5A) or they may each use a different UACS residing on the same or different OS 2200 host (as illustrated in Figure 1-5B).
OS 2200 OS 2200 client application client application
UACL UACL UACS1
UACS server application
UASL UASL UACS2 server application
Figure 1-5A: UACL and UASL Figure 1-5B: UACL and UASL Using the Same UACS Using Different UACSs
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-21
UAMM (UniAccess Message Manager)
UAMM is the message-handling component of the UniAccess System. It manages the transport of messages between one or more UACSs and UniAccess library-based programs. UACS uses UAMM to send and receive information from Server-Library transactions and Client-Library applications.
UADT (UniAccess Data Manager)
UADT is a service 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. UADT performs the following tasks:
• Maintains error and informational data for all components of the UniAccess System
• Maintains a mapping of RDMS 2200 error codes to their SQL Server equivalents
• Maintains RDMS 2200 access information about each user who is configured to use the system
• Maintains UAHS access information for each user
• Maintains server definitions for all servers accessed by the UniAccess System
• Maintains UACS, UARS, and UAHS operational characteristics
• Maintains a mapping of RPC names to transaction codes.
UACL (UniAccess Client-Library)
UniAccess Client-Library provides a set of standard routines that allow OS 2200 programs to function as Open Clients in the Microsoft client/server architecture. In conjunction with UACS, these functions enable client applications to communicate with local and remote server applications. UACL functions encode and send TDS data streams from the client application through UACS; they also receive and decode TDS data streams from server applications through UACS and return them to the client application.
Release 10R3: October 31, 2005 1-22 UniAccess for OS 2200 System Administration Guide
UACL functions perform the following specific tasks in the communication between a client application and a server:
• Establish a connection with a server
• Send a request to the server
• Interpret the resultant data stream returned from the server.
UASL (UniAccess Server-Library)
UniAccess Transaction Server includes a special set of functions, known collectively as UASL. In conjunction with UACS, these functions enable clients and TIP transactions to communicate with one another. UASL functions receive and decode TDS data streams from the client through UACS; they also create and send TDS data streams from TIP transactions to UACS and back to the client.
UASL functions perform the following specific tasks in the communication between a client and the TIP transaction:
• Check for incoming client communications and determine what kind of information is being sent
• Accept incoming transaction requests and their parameters
• Return data results to the client, a row at a time
• Send return parameters with new values back to the client when appropriate
• Return a status value to the client when appropriate
• Return messages to the client when appropriate.
Release 10R3: October 31, 2005 Introduction to UniAccess System for OS 2200 1-23
UAHS (UniAccess Hierarchical Service for DMS 2200)
UAHS is an AIS-written transaction that services client language requests to DMS 2200. It provides multi-user SQL query capability to DMS databases by converting SQL commands to DMS access (DML) commands. Its tasks include the following:
• Processes retrieve-only SQL language requests (SELECT), which are converted to DMS requests for processing by DMS 2200
• Processes Catalog RPCs from the UniAccess ODBC Driver or from Open Client programs
• Returns data to the client
• Return a status value to the client when appropriate
• Returns messages to the client when appropriate.
Since the UAHS transaction is built on top of UASL functions, it may be thought of as a specific Server-Library transaction. With UAHS, the host programmer need not write any code to allow direct query to DMS 2200.
UARS (UniAccess Relational Service for RDMS 2200)
UARS is an AIS-written transaction that services client language requests to RDMS 2200. It provides multi-user SQL query capability to RDMS 2200 databases using dynamic SQL. Its tasks include the following:
• Processes client language requests by retrieving and/or modifying RDMS 2200 data
• Translates RDMS 2200 error messages to their SQL Server equivalents using UADT
• Processes Catalog RPCs from the UniAccess ODBC Driver or from Open Client programs
• Calls RDMS 2200 stored procedures
Release 10R3: October 31, 2005 1-24 UniAccess for OS 2200 System Administration Guide
• Return a status value to the client when appropriate
• Returns data and messages to the client.
Since the UARS transaction is built on top of UASL functions, it may be thought of as a specific Server-Library transaction. With UARS, the host programmer need not write any code to process SQL language requests to RDMS 2200.
Release 10R3: October 31, 2005 2 Application Development 2 Application Development Overview
Client-server architecture separates applications into two functional categories—client applications and server applications. 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 describes the various types of requests UniAccess System can send and receive and explains resources available to application programmers to ensure that client requests are effectively processed by their corresponding server applications.
Topics Page
Types of Requests 2-2 Language Requests 2-2 Remote Procedure Calls (RPCs) 2-2 Comparing Language Requests and RPCs 2-3 Direct and Indirect Requests 2-4 Client Applications in the UniAccess System 2-6 Remote Client Applications 2-6 UniAccess Transaction Client Applications 2-9 Server Applications in the UniAccess System 2-11 Remote Server Applications 2-11 UniAccess System Server Programs 2-12
Release 10R3: October 31, 2005 2-2 UniAccess for OS 2200 System Administration Guide
Types of Requests In the Microsoft client/server architecture, a client application can call 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 an ad 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 directed understands it. For example, SQL Servers understand Transact-SQL and RDMS 2200 understands 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 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.
Release 10R3: October 31, 2005 Application Development Overview 2-3
Note The 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
Release 10R3: October 31, 2005 2-4 UniAccess for OS 2200 System Administration Guide
transaction, however, that 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.
Direct and Indirect Requests
In the Microsoft client/server architecture, a client can send an RPC or a language request to a server application either directly or from a stored procedure on another server. Unlike other systems that may require a gateway between the client and enterprise server, the UniAccess System for OS 2200 allows 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).
Indirect requests are facilitated by procedures, generally stored on Microsoft SQL Servers. A stored procedure is a collection of SQL statements and optional sequence of flow-of- control statements stored under a specific name on a server. It allows developers to create precompiled, high-speed, centralized queries. A call to a stored procedure, often termed an indirect request, utilizes a multi-tier environment in which the server receiving the request becomes a client to another server. That is, an indirect request invokes a server-to-server interaction (see Figure 2-1).
For instance, a stored procedure on a Microsoft SQL Server might issue an RPC to a Server-Library transaction or a language request to UARS. After parsing and preprocessing the request, the Microsoft SQL Server sends the request and parameters to UACS for forwarding to the server transaction. When results are returned, they follow the same route in reverse. From the client application’s perspective, it called a stored procedure on a Microsoft SQL Server and received the results from the SQL Server. The rest of the process is transparent. When a Microsoft SQL Server calls UACS, it follows the same process it does for calling any other remote server.
Release 10R3: October 31, 2005 Application Development Overview 2-5
Note UniAccess does not currently support server-to-server calls from Sybase SQL Server.
Direct Requests
Workstation OS 2200 U Client A Server C S
Open Client or UniAccess System servers ODBC Application
Indirect Requests
Workstation OS 2200
Microsoft SQL Server U Client A Server C Server S
Stored Procedure ADO/OLE DB UniAccess System servers ODBC Application
Figure 2-1: Examples of Direct and Indirect Requests to UniAccess System Servers
Release 10R3: October 31, 2005 2-6 UniAccess for OS 2200 System Administration Guide
Client Applications in the UniAccess System The UniAccess System implementation of client/server architecture allows for two categories of clients:
• Clients that operate on a LAN-based network and are remote to the OS 2200 host fall into two primary categories—ODBC applications using UADriver and Open Client applications. The latter can include procedures stored on Microsoft SQL Servers and language commands entered interactively (see Figure 2-2).
• UniAccess Transaction Client (Client-Library) programs on the OS 2200 host (see Figure 2-3).
CLIENTS SERVERS CLIENTS SERVERS
UniAccess ODBC System applications Servers w/ UADriver UniAccess UniAccess System Transaction servers Client SQL Server
Open Client applications SYBASE Open Server
Figure 2-2: Remote Client Figure 2-3: OS 2200 Client Applications Applications
Remote Client Applications
For the client application outside the OS 2200 host (see Figure 2-2), sending a request to an OS 2200 host is no different than sending a request to a Microsoft SQL Server. The actions taken by a UniAccess System server to schedule a TIP transaction and retrieve transaction results are transparent to the client. The client receives the results in TDS format, just as if they had come from a SQL Server.
Release 10R3: October 31, 2005 Application Development Overview 2-7
ODBC applications using UADriver access the OS 2200 host the same as they would any other ODBC compliant data source. UADriver 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.
The UniAccess for OS 2200 Client Guide gives specific information on accessing UACS through various client methods. Sample RPCs and SQL language requests, using both ODBC and Open Client interfaces, are included in the UniAccess 10R3 PC Client CD. For information on these sample programs, see the Readme.txt file provided on the CD.
Sending Language Requests
In the UniAccess System, language requests are sent to a database-specific OS 2200 TIP transaction designed to process language requests. Unlike transactions that processes procedure calls where there must be a one-to-one correspondence (one call, one transaction), a language-processing transaction can process all language requests to a specific database. AIS provides two language-processing transactions—UARS for RDMS 2200 databases and UAHS for DMS 2200 databases. In addition, a site may design its own language-processing transaction using UniAccess Server-Library.
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 see Chapters 6 and 9, respectively, of the UniAccess for OS 2200 Client Guide.
Release 10R3: October 31, 2005 2-8 UniAccess for OS 2200 System Administration Guide
For Open Client applications, the application programmer must ensure SQL statement and datatype compatibility. For specific information about compatibility with UARS and UAHS, see Chapters 6 and 9, respectively, of the UniAccess for OS 2200 Client Guide.
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. The UASL transaction or RDMS 2200 stored procedure is called the same way as a procedure on any other ODBC data source.
An Open Client application using the UniAccess System can call a UASL transaction on OS 2200 or an RDMS stored procedure. This arrangement allows a client to use a familiar method, the RPC, to execute various server applications.
The procedure name must match a procedure on the server. The UniAccess configuration provides a method of mapping procedure names (see the RPCMAP configuration statement in Chapter 16). 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.
Note The OSPARM DFLTPROCENV configuration statement allows the system administrator to designate a default processing environment for unmapped RPCs— either UARS (for RDMS stored procedures) or the UASL transactions supported by the UniAccess Transaction Server.
Release 10R3: October 31, 2005 Application Development Overview 2-9
UniAccess Transaction Client Applications
Users can write UniAccess Client-Library (UACL) programs that generate both procedure calls and language requests.
Sending Language Requests
UniAccess Transaction Client applications can send language requests to any server by using the function calls provided in UACL. The client application must format the language request so that it is understood by the server.
UniAccess Transaction Client includes a processor, ISQL, that allows demand-mode users to send SQL language commands interactively. The user specifies the server, then enters SQL commands. This facility is described in Chapter 13, Interactive SQL Parser.
Sending RPCs
To initiate an RCP, a customer-written UACL transaction calls a pre-written procedure that will act as a server—for example, a stored procedure on a SQL Server or a UniAccess Transaction Server program running on an OS 2200 host (see Figure 2-2). If the request is to an Open Server, the client can access any data available to the Open Server application on whatever system Open Server is running. If the request is to a Server-Library transaction in another application group, the client can access any data accessible through the server’s application group.
The called procedure or transaction (the server) executes and returns results to the calling application (the client), which can use the results in its local processing. If the client has permission, the client application can update data at remote sites, such as a SQL Server, by inserting, modifying, and deleting entries in database tables or other storage systems.
UniAccess Client-Library
UniAccess Client-Library (UACL) is the set of functions that allow client applications to send requests to servers through UACS and receive the results of those requests. The programmer should use these functions when writing OS 2200 client applications to communicate with any server within the client/server network.
Release 10R3: October 31, 2005 2-10 UniAccess for OS 2200 System Administration Guide
UACL functions are designed to be symmetrically paired with those of server applications. When the client application issues a send call, the corresponding server transaction will issue a receive call, and vice versa. For instance, the UACL function CTBSEND corresponds to the UASL function TDRCVPRM, and the UACL function CTBFETCH corresponds to the UASL function TDSNDPARM.
UniAccess Client-Library is built using SYBASE Open Client and uses TDS protocol to transmit data between client and server. UACL functions, invoked by user-written client applications, call UniAccess Message Manager functions to handle data communications. The application programmer concentrates on the application and does not need to know the specific details of client/server communications.
General Processing Procedures. Whether the outgoing request is an RPC or a language request, the Client-Library application task involves the following steps:
• Prepare the programming environment
• Establish a connection with a server
• Send a command to the server
• Process the results of the command
• Close connections and terminate.
The UniAccess for OS 2200 Client-Library Programming Reference explains how to perform these tasks using UACL functions. The manual is a reference of functions available in UniAccess Client Library; it describes their arguments and gives their return values.
Sample UACL Programs. The UniAccess System includes four Client-Library programs, three that issue RPCs and one that issues a language request. The programs work in conjunction with sample server programs and demonstrate Client-Library program design. They also illustrate how UACL manages connections, requests and receives data, and defines the length and datatype of parameters. For more information about these sample programs, see Appendix C.
Release 10R3: October 31, 2005 Application Development Overview 2-11
Server Applications in the UniAccess System The UniAccess System implementation of client/server architecture allows for two categories of servers:
• Servers that operate on a LAN-based network and are remote to OS 2200 hosts, such as SQL Servers and SYBASE Open Server
• UniAccess System servers, which are UniAccess Transaction Server for OS 2200, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200.
SERVERS CLIENTS SERVERS CLIENTS
Open Client applications SQL Server
UniAccess UniAccess ODBC Transaction System applications Client servers w/ UADriver
SYBASE UniAccess Open Server Transaction Client
Figure 2-4: Remote Server Figure 2-5: OS 2200 Server Applications Applications
Remote Server Applications
SQL Servers and SYBASE Open Server may receive RPC or language requests from UniAccess Client-Library programs in the same manner they are accustomed to receiving other client requests. The network addresses of all remote servers to which the client can connect are defined in the SERVER configuration statement, discussed in Chapter 16.
Release 10R3: October 31, 2005 2-12 UniAccess for OS 2200 System Administration Guide
At sites where Sybase products have been installed, the server platforms are configured with appropriate network software to communicate with the UniAccess System. No modifications or adjustments are necessary to use the platforms. Instructions for using Sybase products can be found in their respective documentation sets (see Appendix G).
UniAccess System Server Programs
UniAccess System server products are the Transaction Server for OS 2200, the UniAccess ODBC Server for RDMS 2200, and the UniAccess ODBC Server for DMS 2200 (see Figure 2-4). Each product includes a unique transaction processing component that will be discussed in this section:
• UniAccess Relational Service—in UniAccess ODBC Server for RDMS 2200
• UniAccess Hierarchical Service—in UniAccess ODBC Server for DMS 2200
• UniAccess Server-Library—in the UniAccess Transaction Server for OS 2200.
Processing Language Requests
In the UniAccess System, language requests are processed by the TIP transaction configured in the UniAccess Configuration File to receive language requests. The user calls one of the two language transactions provided by AIS or a user-written language transaction provided by the site. 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. User-written language transactions, created with Server-Library functions, can process whatever syntax (language) the programmer designs into the transaction.
Note UACS can concurrently support three language transactions, including a user-written language transaction. See the COMSRV configuration statement in Chapter 16 for more information.
Release 10R3: October 31, 2005 Application Development Overview 2-13
Processing RPCs
Remote procedure calls are handled by user-written TIP transactions or RDMS 2200 stored procedures. Each RPC is assigned a specific name that is mapped to the name of the transaction or RDMS stored procedure.
User-written TIP transactions are the primary mechanism for RPCs in the UniAccess System. To write these transactions, the programmer employs the pre-compiled routines supplied by the UASL component. This library of high-level functions enables application programmers to write server transactions without having to know the details of the TDS or TCP/IP protocols.
The support of RDMS 2200 stored procedures is available through the UniAccess ODBC Driver and the UARS transaction. UADriver codes the procedure call properly and sends it to UARS through UACS. UARS passes the call to the appropriate RDMS 2200 stored procedure and returns the results to the client ODBC application. The RDMS stored procedures are supplied by the user.
UniAccess Relational Service for RDMS 2200
UniAccess Relational Service (UARS) for RDMS 2200 works with other components of the UniAccess System to process dynamic SQL language requests from a client, using RDMS’s Interpretive SQL facilities. UARS provides a TIP transaction, UARS, that accepts a client’s SQL statements, forwards those SQL requests to RDMS 2200, and returns results and messages to the client. No transaction programming is required by the user. (For a list of RDMS SQL commands and datatypes available to ODBC clients and Open Clients using UARS, see Chapter 6 of the UniAccess for OS 2200 Client Guide.)
Note In this manual, the TIP transaction that processes language requests to RDMS 2200 is called by its default name, UARS. You can, however, assign a different name when you define it to TIP.
Release 10R3: October 31, 2005 2-14 UniAccess for OS 2200 System Administration Guide
UARS provides three additional services to support the UniAccess ODBC Driver.
• Support of RDMS 2200 Stored Procedures. In conjunction with the UniAccess ODBC Driver, the UniAccess Relational Service supports RDMS 2200 stored procedures. RDMS stored procedures do not generate result sets the way UniAccess Server-Library transactions can generate result sets. They are only capable of returning result data in updated parameters.
• Access to RDMS 2200 Catalog Information. The UniAccess Relational Service supports a set of RPCs that are processed by the UARS transaction to access RDMS 2200 catalog information. (The predefined RPCs may be used independently by the client and are described in Chapter 8 of the UniAccess for OS 2200 Client Guide.) This information enables the UniAccess ODBC Driver to present an ODBC compliant view of RDMS 2200 catalog information to the ODBC application.
• AIS-supplied RDMS 2200 Tables. Four RDMS 2200 tables— SPT_SERVER_INFO, SPT_DATATYPE_INFO, SPT_PROCEDURES, SPT_IOTYPES, and SPT_PROCEDURE_COLUMNS—are supplied in the UNIACCESS1S1 schema. These tables enable UniAccess to provide the UniAccess ODBC Driver with server, datatype, general procedure, and procedure column information (respectively), but they may be used independently by the client as well. The data in these tables can be modified by the system administrator using RDMS 2200 SQL commands. (Refer to Appendix E for details on modifying SPT_PROCEDURES and SPT_PROCEDURE_COLUMNS.)
Configuring UARS. The UARS transaction is configured in the same way as any other TIP transaction. The system administrator must ensure that the UARS transaction is properly configured in each application group where it will run. Configuration requirements for the UARS transaction in particular are found in Chapter 4. Information on registering TIP transactions in general is found on page 8-6. Additionally, configuration considerations for optimizing UARS performance begins on page 8-7.
Release 10R3: October 31, 2005 Application Development Overview 2-15
User and Map Data. In addition to the tasks generally assigned to a TIP transaction — to translate client requests, to retrieve and/or modify data in the database, and to return results to the client—UARS also performs the following tasks:
• Retrieves database access information from user definitions maintained in UADT
• Uses map definitions maintained in UADT to translate RDMS 2200 message codes into SQL Server message codes and return them to the user.
Information about configuring user definitions in UADT is found on page 16-78; map definition configurations are explained on page 16-73. The user definitions are explained on page 9-6. Information on the map definitions is found on page 10-5. Appendix D contains a list of messages returned by UARS.
UniAccess Hierarchical Service for DMS 2200
UniAccess Hierarchical Service (UAHS) for DMS 2200 offers dynamic SQL query capability to DMS 2200 databases. UAHS provides a TIP transaction, UAHS, that accepts SQL language requests from remote clients, translates the request into DML commands, fetches the appropriate DMS work, and returns results to clients. UAHS performs all the necessary logic to validate the SQL SELECT statement, determine what DMS records and fields must be accessed, decide whether a DMS logical path for each table in the SELECT request can be created, and then retrieve the data and construct a result. No transaction programming is required by the user. (For more information on the client’s use of UAHS, see Chapter 9 of the UniAccess for OS 2200 Client Guide.)
Note In this manual, the TIP transaction that processes language requests to DMS 2200 is called by its default name, UAHS. You can, however, assign it to a different name when you define it to TIP.
Release 10R3: October 31, 2005 2-16 UniAccess for OS 2200 System Administration Guide
Configuring UAHS. The UAHS transaction is configured in the same way as any other TIP transaction. The system administrator must ensure that the UAHS transaction is properly configured to each application group where it will run. Configuration requirements for the UAHS transaction in particular are found in Chapter 4. Information on registering TIP transactions in general is found on page 8-6. Additionally, configuration considerations for optimizing UAHS performance begins on page 8-9.
Building and Updating the Database Information File. During the installation of UAHS, the UniAccess System utility SCHEMADEF builds the UAHS Meta Database from existing DMS schema definitions. The meta database, contained within a TIP file, is used by UAHS to map SQL requests to a relational representation of a DMS schema. A second UniAccess System utility, TABLEDEF, processes a command file that the system administrator uses to update the UAHS Meta Database and define how the DMS schema will be presented to the end user. For more information on using the UAHS utilities, see Chapter 14.
User and Map Data. Like UARS, UAHS also performs the following tasks:
• Retrieves database access information from user definitions maintained in UADT.
• Uses map definitions maintained in UADT to translate DMS 2200 message codes into SQL Server message codes and return them to the user.
Information about configuring user definitions in UADT is found on page 16-78; map definition configurations are explained on page 16-73. The user definitions are explained on page 9-6. Information on the map definitions is found on page 10-5. Appendix D contains a list of messages returned by UAHS.
UniAccess Server-Library
UniAccess Server-Library (UASL) is the set of functions that allow OS 2200 programmers to create TIP transactions that retrieve requests from and format responses to ODBC and Open Client applications through UACS. Programmers primarily use these functions to create RPC-processing transactions, although they may create general-purpose language transactions as well. OS 2200 transactions created with Server-Library functions are the equivalent of stored procedures on a SQL Server.
Release 10R3: October 31, 2005 Application Development Overview 2-17
UASL functions are designed to be symmetrically paired with those of client applications. If the client application issues a send call, the corresponding server transaction must issue a receive call, and vice versa. For instance, the UASL function TDRCVPRM corresponds to the UACL function CTBSEND, and the UASL function TDSNDPRM corresponds to the UACL function CTBFETCH.
UniAccess Server-Library is built using SYBASE Open Server and uses TDS protocol to transmit data between server and client. UASL functions call UniAccess Message Manager functions to handle data communications. The application programmer concentrates on the application and does not need to know the intricacies of client/server communications.
General Processing Procedures. Whether a Server-Library TIP transaction is designed to process RPCs or language requests, its tasks fall into three categories:
• Prepare the environment and accept the request
• Perform the requested action
• Return results to UACS for the requesting client and end the conversation.
The UniAccess for OS 2200 Server-Library Programming Reference explains how to perform the first and third tasks using UASL functions to communicate with UACS. The manual is a reference of all functions available in UASL, giving the functions’ description, return values, and generated errors. The second task is performed using familiar programming procedures.
Configuring UASL. UASL transactions are configured in the same way as other TIP transactions. The system administrator must ensure that UASL transactions are properly configured in each application group in which they will run. Information on registering TIP transactions in general is found in on page 8-6. Additionally, information on optimizing the performance of Server-Library programs begins on page 8-12. (See also the UniAccess for OS 2200 Server-Library Programming Reference.)
Sample UASL Programs. The UniAccess System includes four Server-Library programs, three that process RPCs and one that processes a language request. The programs work in conjunction with sample client programs and demonstrate Server- Library program design. They also illustrate how UASL manages connections, sends and receives data, and processes a variety of datatypes. For more information about the sample programs, see Appendix C.
Release 10R3: October 31, 2005 2-18 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 II Install & Config Procedures Part II ...... Installation and Initial Configuration Procedures
Chapter 3: Planning Your UniAccess Installation
Chapter 4: Installing the UniAccess System
Chapter 5: Planning Your UniAccess Configuration
Chapter 6: Managing the UniAccess System
Chapter 7: Preparing for ODBC and Open Client Users
3 Planning Installation 3 Planning Your UniAccess Installation
This chapter overviews the steps a system administrator must take to initiate operation of the UniAccess System. It also provides pre-installation checklists of host hardware and software levels and of recommended peripheral software levels.
Topics Page
Before You Begin 3-1 Hardware and Software Requirements 3-4 Explanation of Values in Pre-Installation Checklist 3-6
Before You Begin Please review this section before installing the UniAccess product tape.
Table 3-1 gives a quick reference list of the steps a system administrator must take to initiate the operation of the UniAccess System. Chapters 3 through 7 explain these steps in more detail, providing you with checklists of necessary values and configurations. Please complete the appropriate checklists before proceeding with the installation or the execution of system processors.
Release 10R3: October 31, 2005 3-2 UniAccess for OS 2200 System Administration Guide
Table 3-1: Steps in Initial UniAccess System Administration
Step Action to be taken Reference
1 Inspect the current READ.ME document to determine any READ.ME document changes to the installation procedures and apply any fixes required.
2 Complete the Pre-Installation Checklist by obtaining the Chapter 3 required product levels and performing the required OS 2200 (Appendix B) configurations.
3 Complete the Installation Checklist, installing the UniAccess Chapter 4 System, and the Hierarchical Service, Relational Service, and UAINFO transactions as appropriate.
4 Complete the UniAccess Configuration Checklist, modify the Chapter 5 Source Configuration File where required to define the (Chapter 16) UniAccess System environment for your site. (Appendix B)
5 Execute the UniAccess System processors, UACF and UACS. Chapter 6 (Chapter 17)
6 Complete the Client Preparation Checklist, providing required Chapter 7 values to ODBC and Open Client Users.
Step 1) Inspect the READ.ME Document
The READ.ME document, provided with each version of a UniAccess release, updates installation procedures, lists required fixes, and gives other information that may be essential to a successful installation. Additionally, this document is available on our Web site at http://www.uniaccess.com. Please consult this document before you begin the installation steps outlined in this manual.
Step 2) Complete the Pre-Installation Checklists
To prepare the UniAccess System for full operation, complete the Pre-Installation Checklist provided in this chapter. This list ensures that your site meets the required product levels to install the UniAccess System and helps you configure OS 2200 components that interface with the UniAccess System.
Release 10R3: October 31, 2005 Planning Your UniAccess Installation 3-3
Step 3) Install the UniAccess System Products
Next, you will need to install the UniAccess System products purchased for your OS 2200 Series system. Chapter 4 explains installation operations and procedures. It also provides a checklist for UAHS, UARS, and UAINFO transaction installations. (Appendix A provides a complete list of the UniAccess System files that will be installed.)
Step 4) Complete the UniAccess Configuration Checklist
After your installation is complete, you will need to modify the Source Configuration File by completing the checklist provided in Chapter 5. The UniAccess System product tape provides you with default configuration templates (see page 5-2), but you will need to adapt some of the information in this file to your own site. Some modifications will be required for all sites; other modifications depend on the UniAccess System products installed at your site and the way you intend to use these products. The checklist explains the required and optional items for each UniAccess product. Chapter 16 provides a reference to all UniAccess configuration statements. Appendix B gives detailed configuration relationship information and indicates how each configuration relates to the default Source Configuration File.
Step 5) Execute the UniAccess System Processors
After you have modified the Source Configuration File, you will need to execute the UACF processor to generate the UniAccess Configuration File and initialize the UniAccess Fixed- gate. When this step has completed successfully, you may start UACS, the UniAccess Communications Server.
Chapter 6 explains the design and management of to the UniAccess System, including the UniAccess Fixed-gate and the two UniAccess System processors, UACF and UACS. It also provides the steps involved in initial and subsequent executions. Chapter 17 gives the execution syntax for each processor and defines all execution options.
Release 10R3: October 31, 2005 3-4 UniAccess for OS 2200 System Administration Guide
Hardware and Software Requirements The Pre-Installation Checklist describes the host hardware and software levels and configurations required for an initial installation of a new UniAccess level. Before you begin installation on your system, please verify each of the requirements in the table, based on the UniAccess product package being used at your site. On the table, the columns entitled UniAccess Product Requirements indicate whether the product is required or optional for each UniAccess package—UniAccess Transaction Client, UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, or UniAccess ODBC Server for DMS 2200. The explanation section that follows this table describes how to obtain the required values.
Table 3-2: Pre-Installation Checklist — Host Hardware Levels, Software Levels, and Configurations
Host Hardware/Software UniAccess Product Requirements
ODBC ODBC Transaction Transaction Server for Server for Client Server RDMS 2200 DMS 2200
1. Unisys mainframe: 2200/300, required required required required 2200/500, 2200/700, 2200/900, 2200/3800, or ClearPath IX System 2. TCP/IP Connectivity to the LAN or required required required required WAN via CMS 1100 or CPComm 3. Software level CP-IX 6.1, or later 3-1. CMS 1100 level 8R5, or later; or required required required required CPComm level 3R2, or later 3-2. EXEC level 46R4, or later required required required required 3-3. MCB level 8R2E, or later optional1 required required required 3-4. URTS level 11R1A, or later required required required required 3-5. ASCII COBOL level 7R3D n/a optional2 n/a n/a 3-6. Collector level 33R1I n/a optional2 n/a n/a 3-7. Linking System level 10R1A required required required required 3-8. LSS level 12R1A required required required required 3-9. SOLAR level 3R6 required required required required 3-10. SORT level 20R2A n/a n/a n/a optional3
Release 10R3: October 31, 2005 Planning Your UniAccess Installation 3-5
Host Hardware/Software UniAccess Product Requirements
ODBC ODBC Transaction Transaction Server for Server for Client Server RDMS 2200 DMS 2200
3-11. TIPUTIL level 46R4 optional required required required 3-12. UCS C level 8R1A optional4 optional4 n/a n/a 3-13. UCS COBOL level 10R1A optional4 optional4 n/a n/a 3-14. UDS Control level 10R2 optional5,4 optional5,6,7 required required 3-15. UDS DMS 2200 level 17R2 optional5 optional5 n/a required 3-16. UDS RDMS 2200 level 10R2 optional6 optional6 required n/a 3-17. UREP 2200 level 6R2 n/a optional6 required n/a 4. Install TIPUTIL in MODE UCS optional1 required required required 5. Configure the EXEC to include each optional8 required required required application group in which the UniAccess System will operate 6. Enable and configure TIP optional1 required required required 7. Configure UDS for each application optional8 optional8 required required group in which the UniAccess System will operate 8. Configure MCB for each application optional1 required required required group in which the UniAccess System will operate 9. Configure MCB in extended mode optional1 required required required 10. Configure a process name, a required required required required password, and an I.P. address (or range of I.P. addresses) in the CMS configuration or CPComm configuration
1 Required if transactions are to be used in the UACL environment. 2 Required if basic mode transactions are to be used in the UASL environment. 3 Required to support ORDER BY and DISTINCT. 4 Required for writing UniAccess programs in these languages. 5 Required if DMS is to be used in the UniAccess environment. 6 Required if RDMS is to be used in the UniAccess environment. 7 Required to support distributed transactions. 8 Required if RDMS and/or DMS is to be used in the UniAccess environment.
Release 10R3: October 31, 2005 3-6 UniAccess for OS 2200 System Administration Guide
Explanation of Values in Pre-Installation Checklist
The following section explains how to obtain values for each of the software items in the Pre-Installation Checklist and explains the OS 2200 configurations required before you begin your UniAccess installation.
1. Unisys mainframe: 2200/300, 2200/500, 2200/700, 2200/900, 2200/3800, or ClearPath IX System
2. TCP/IP connectivity to the LAN or WAN via CMS 1100 or CPComm
3. Software Level CP-IX 6.1 or later
3-1. CMS 1100 level 8R5 or CPComm Level 3R2
Either CMS 1100 level 8R5 (or later) or CPComm level 3R2 (or later) is required for all UniAccess product packages.
To determine the CMS 1100 level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,CMS1100.
To determine the CPComm level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,CPCOMM.
Release 10R3: October 31, 2005 Planning Your UniAccess Installation 3-7
3-2. EXEC level 46R4
EXEC level 46R4, or later, is required for all UniAccess product packages. To determine the EXEC level at your site:
@@CONS SS will return the EXEC level.
3-3. MCB level 8R2E
MCB level 8R2E, or later, is required by the UniAccess Transaction Server and the ODBC Servers. It is required for the UniAccess Transaction Client if UACL programs will be executing in a TIP environment. To determine the MCB level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,MCB.
3-4. URTS (UCS Runtime System) Level 11R1A
URTS (USC Runtime System) level 11R1A, or later, is required for all UniAccess product packages. To determine the URTS level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,URTS.
3-5. ASCII COBOL level 7R3D
ASCII COBOL level 7R3D, or later, is required if you wish to write UASL transactions for the basic mode environment. To determine the ASCII COBOL level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name (ACOB), or
Release 10R3: October 31, 2005 3-8 UniAccess for OS 2200 System Administration Guide
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,ACOB.
3-6. Collector level 33R1I
Collector level 33R1I, or later, is required if you wish to write UASL transactions for the basic mode environment. To determine the Collector level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name (MAP), or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,MAP.
3-7. Linking System level 10R1A
Linking System level 10R1A, or later, is required for all UniAccess product packages. To determine the Linking System level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,LINK.
3-8. LSS level 12R1A
LSS level 12R1A, or later, is required for all UniAccess product packages. To determine the LSS level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,LSS.
Release 10R3: October 31, 2005 Planning Your UniAccess Installation 3-9
3-9. SOLAR level 3R6
SOLAR level 3R6, or later, is required for all UniAccess product packages. To determine the SOLAR level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,SOLAR.
3-10. SORT level 20R2A
SORT level 20R2A, or later, is required if you use ORDER BY or DISTINCT clauses in the UAHS environment. To determine the SORT level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,SORT.
3-11. TIPUTIL level 46R4
TIPUTIL level 46R4, or later, is required for the UniAccess Transaction Server and the ODBC Servers, and for UniAccess Transaction Client if UACL programs will be executing in a TIP environment. To determine the TIPUTIL level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
Note Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,TIPUTIL.
Release 10R3: October 31, 2005 3-10 UniAccess for OS 2200 System Administration Guide
Note TIPUTIL must be installed. Copying the files onto the system is not equivalent to installing TIPUTIL.
3-12. UCS C level 8R1A
UCS C level 8R1A, or later, is required if you wish to write UASL or UACL programs in this language. To determine the UCS C level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name (UC), or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,UC.
3-13. UCS COBOL level 10R1A
UCS COBOL level 10R1A, or later, is required if you wish to write UASL or UACL programs in this language. To determine the UCS COBOL level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name (UCOB), or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,UCOB.
3-14. UDS Control level 10R2
UDS Control level 10R2, or later, is required if you will use RDMS or DMS in the UniAccess environment. To determine the UDS Control level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name (UDSC), or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,UDSC.
Release 10R3: October 31, 2005 Planning Your UniAccess Installation 3-11
3-15. UDS DMS 2200 level 17R2
UDS DMS 2200 level 17R2, or later, is required if you will use DMS in the UniAccess environment. To determine the UDS DMS level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,DMS.
3-16. UDS RDMS 2200 level 10R2
UDS RDMS 2200 level 10R2, or later, is required if you will use RDMS in the UniAccess environment. To determine the UDS RDMS level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,RDMS.
3-17. UREP 2200 level 6R2
UREP 2200 level 6R2, or later, is required if you use RDMS 2200 in the UniAccess environment. To determine the UREP level at your site:
• Execute @SOLAR and from the Main Menu, select Installed Products. The level will be listed beside the product name, or
Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The product level is present on the image containing the character string PRODUCT,UREP.
4. Install TIPUTIL in Mode UCS
TIPUTIL must be installed in Mode UCS for UniAccess Transaction Server and ODBC Server and for UniAccess Transaction Client if UACL programs will be executing in a TIP environment. To determine the TIPUTIL mode at your site:
Release 10R3: October 31, 2005 3-12 UniAccess for OS 2200 System Administration Guide
• Execute @SOLAR and from the Main Menu, select Installed Products. Mode UCS will be listed beside the product name, or
• Inspect the element SYS$*DATA$.CO$INSTALL$/COMUS$. The mode is present on the image containing the character string PRODUCT,TIPUTIL.
Note The extended mode processing environment, used by the UniAccess System, requires that the TIP utilities be installed formally on the system. Sites that do not currently use extended mode transactions may have copied the TIP library files onto the system instead of installing the library files. The TIP utilities must be installed formally on the system to create the common banks used to process extended mode requests for TIP services.
5. Configure the EXEC to include each application group in which the UniAccess System will operate
The UniAccess System imposes no unique constraints on the configuration of application groups within the EXEC. The application group is defined in the EXEC using a series of STEPCONTROL SGSs. The format of this SGS is:
STEPCONTROL application-number APPLICATION NAME IS name,
where:
application-number = MCB parameter APNUMBER and UDS dynamic configuration parameter APPL-GROUP-NUMBER, and
name = MCB parameter APNAME and the UDS dynamic configuration parameter APPL-NAME.
6. Enable and configure TIP
The UniAccess System imposes no unique constraints upon the EXEC TIP configuration. However, UARS, UAHS, and user-written transactions must be
Release 10R3: October 31, 2005 Planning Your UniAccess Installation 3-13
registered with the EXEC and placed into TIP files. Therefore, TIP must be enabled and a TIP file number must be available.
To enable TIP, the Transaction Processing SGS configuration parameter TIP should be set to TRUE. The following parameters may also need to be configured:
• TFPMAX—should be set large enough to allow at least one file to contain TIP transactions. (The UniAccess ODBC Server for DMS 2200 requires an additional TIP file for each application group in which it will be executed.)
• TIPMEF—should be set large enough to allow at least one file to contain TIP transactions. (The UniAccess ODBC Server for DMS 2200 requires an additional TIP file for each application group in which it will be executed.)
• TIPTPS—controls the number of concurrent TIP transactions. The setting of this value may affect system performance.
7. Configure UDS for each application group in which the UniAccess System will operate
For each application group, the following UDS dynamic configuration parameters must match the MCB parameters:
• APPL-GROUP-NUMBER must match APNUMBER
• APPL-NAME must match APNAME
• MCB-ENTRY-POINT should be 01000
• MCB-MSG-BANK-BDI must match MCBBDI
• MSG-RECY-BANK-BDI should be defined as 0. (This is needed, even though it is not used.)
• MAX-THREADS should be large enough to handle the number of concurrent users. Dynamic SQL and extended sessions may increase the number of concurrent users.
Release 10R3: October 31, 2005 3-14 UniAccess for OS 2200 System Administration Guide
• The THREAD-BANK-SIZE should be large enough to prevent it from being expanded by TIP transactions.
SUDS, UDSMON, and OSAM can be used to monitor the number of concurrent threads and the size of the thread banks. (For more information, see the Unisys OS 2200 Universal Data System (UDS) Administration and Support Reference Manual.) The clearance level of the UDS system files (FDT$, Root-file, System-file, etc.) should be such that legitimate users are allowed access to the files.
8. Configure MCB for each application group in which the UniAccess System will operate
An MCB (Message Control Bank) must be configured for each application group in which the UniAccess System will operate. (This requirement applies to the UniAccess Transaction Server and the ODBC Servers. It also applies to the UniAccess Transaction Client if UACL programs will be executing in a TIP environment.) MCB configuration parameters limit the number of connections UACS can support.
The MCB parameter APNUMBER must match the EXEC STEPCONTROL application-number. The MCB parameter APNAME must match the EXEC STEPCONTROL APPLICATION NAME and the UDS dynamic configuration parameter APPL-NAME.
9. Configure MCB in extended mode
The UniAccess System operates in an extended mode environment. It requires extended mode support within the MCB for the UniAccess Transaction Server and the ODBC Servers. Extended mode support is also required for the UniAccess Transaction Client if UACL programs will be executing in a TIP environment. MCB support of extended mode can be determined by editing the element CO$CONFIG in the installed file. The parameter EXTENDEDMODE should be set to YES.
10. Configure a process name, password, and IP address (or range of IP addresses) in the CMS or CPComm configuration
One unique CMS 1100 or CPComm PROCESS statement must be configured for each UACS. The PROCESS statement process-id variable must match the UniAccess COMSRV PROCNAM parameter.
Release 10R3: October 31, 2005 Planning Your UniAccess Installation 3-15
The password variable on the CMS 1100 or CPComm PROCESS statement must match the UniAccess COMSRV PROCPSWD parameter. This value need not be unique.
Each CMS 1100 or CPComm PROCESS statement must relate to an Internet (IP) address. CMS 1100 specifies the IP address as the parameter of the INTERNET-ADR configuration statement. CPComm specifies the IP address as a parameter of the IP configuration statement. A single execution of UACS will support up to 25 Internet addresses.
Release 10R3: October 31, 2005 3-16 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 4 Installing UniAccess 4 Installing the UniAccess System
After you complete the Pre-Installation Checklist in Chapter 3, you are ready to install the UniAccess System. This chapter discusses the installation steps necessary for all UniAccess products as well as the format of the UniAccess Release tape.
Topics Page
Installation Checklist 4-1 Explanation of Installation Requirements 4-4
Appendix A provides a list of all UniAccess System files.
Installation Checklist The Installation Checklist (Table 4-1) gives a quick reference of the steps a system administrator must take to install the UniAccess System. On the table, the columns entitled UniAccess Product Requirements indicate whether the step is required or optional for each UniAccess package—UniAccess Transaction Client, UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, or UniAccess ODBC Server for DMS 2200.
Release 10R3: October 31, 2005 4-2 UniAccess for OS 2200 System Administration Guide
Table 4-1: UniAccess Installation Checklist
Host Requirements UniAccess Product Requirements
ODBC ODBC Transaction Transaction Server for Server for Client Server RDMS 2200 DMS 2200
UniAccess System 1. Make a backup copy of the UniAccess optional optional optional optional System release tape 2. Consult the READ.ME document for required required required required upgrade considerations 3. Determine the UniAccess Installation required required required required Mode 4. Register the UniAccess Release Tape required required required required with SOLAR 5. Install the UniAccess Product required required required required
UAHS transaction 6. Obtain Hierarchical Service installation n/a n/a n/a required information 6-1. application number n/a n/a n/a required 6-2. SUPUR file number n/a n/a n/a required 6-3. UAHS transaction name n/a n/a n/a required 6-4. UAHS transaction number n/a n/a n/a required 7. Install the UAHS transaction n/a n/a n/a required 8. Create the UAHS Meta Database n/a n/a n/a required
UARS transaction 9. Update the UREP configuration n/a n/a optional1 n/a MASTER-RUN-USERID attribute
1 Required if UARS is to be used in a non-TIP session control environment. 2 Required if UADriver is to be used without UARS or UAHS. 3 Required if UniAccess Transaction Server programs are to written in a basic mode environment.
Release 10R3: October 31, 2005 Installing the UniAccess System 4-3
Host Requirements UniAccess Product Requirements
ODBC ODBC Transaction Transaction Server for Server for Client Server RDMS 2200 DMS 2200
10. Obtain Relational Service n/a n/a required n/a installation information 10-1. application number n/a n/a required n/a 10-2. application name n/a n/a required n/a 10-3. SUPUR file number n/a n/a required n/a 10-4. UARS transaction name n/a n/a required n/a 10-5. UARS transaction number n/a n/a required n/a 11. Install the UARS transaction n/a n/a required n/a 12. Prepare the UREP repository n/a n/a optional n/a
UAINFO transaction 13. Obtain UAINFO installation n/a optional2 n/a n/a information 13-1. application number n/a optional2 n/a n/a 13-2. SUPUR file number n/a optional2 n/a n/a 13-3. UAINFO transaction name n/a optional2 n/a n/a 13-4. UAINFO transaction number n/a optional2 n/a n/a 14. Install the UAINFO transaction n/a optional2 n/a n/a
UniAccess System 15. Configure and install the ASCII n/a optional3 n/a n/a COBOL Interface 16. Install the UniAccess Samples optional optional optional n/a
1 Required if UARS is to be used in a non-TIP session control environment. 2 Required if UADriver is to be used without UARS or UAHS. 3 Required if UniAccess Transaction Server programs are to written in a basic mode environment.
Release 10R3: October 31, 2005 4-4 UniAccess for OS 2200 System Administration Guide
Explanation of Installation Requirements
1. Make a backup copy of the UniAccess System release tape
We recommend that you make a backup of the UniAccess System release tape before registering it with SOLAR.
2. Consult the READ.ME document for upgrade considerations
Inspect the READ.ME document for upgrade considerations pertaining to previous levels of UniAccess products. The READ.ME document is provided with each version of a UniAccess release.
The most current version of the READ.ME document may also be accessed from the AIS Web site at http://www.uniaccess.com.
3. Determine the UniAccess Installation Mode
The level 10R3 release of the UniAccess product suite is delivered in the standard Unisys SOLAR stack tape format. The UniAccess product release tape includes the following four installation options:
Mode A is the official release version of the UniAccess Level 10R3 product suite. It has been configured using BDI 405220. This is the default mode and may be installed directly from the SOLAR release tape using the SOLAR INSTALLPKG runstream. This mode is also referred to in this manual as a production mode install.
Mode B is the latest maintenance update version of the UniAccess product suite. This version is based on the 10R3 release and incorporates all fixes available at the time the release tape was built. Like Mode A, it has been configured using BDI 405220. It is installed by selecting Mode B in a SOLAR installation operation. This mode is also referred to as a production mode install.
Mode C allows the user to configure and install the official release version of the UniAccess product suite using a site selected BDI. This mode is referred to as a test mode install.
Release 10R3: October 31, 2005 Installing the UniAccess System 4-5
Mode D allows the user to configure and install the maintenance update version, described in Mode B, using a site selected BDI. This mode is also referred to as a test mode install.
Note Modes A and B are mutually exclusive and cannot be installed at the same time because they both reference the same files and BDI. Modes C and D are also mutually exclusive.
4. Register the UniAccess Release Tape with SOLAR
From the operator’s console, enter ST REGISTERPKG and respond to the system prompts.
Additionally, the UniAccess tape can be registered using SOLAR in demand or batch mode. Refer to the Unisys OS 2200 Software Library Administrator (SOLAR) End Use Reference for more details.
5. Install the UniAccess Product
Note that for SOLAR installations, the user must have privileges allowing a SOLAR install. For more information on SOLAR installations, refer to the Unisys OS 2200 Software Library Administrator (SOLAR) End Use Reference for more details.
Mode A (Official Production Mode). Mode A is the default installation mode and may be installed from the operator’s console by entering ST INSTALLPKG and responding ‘Y’ to the INSTALL DEFAULT MODES system prompt. Additionally, UniAccess can be installed using SOLAR in demand or batch mode.
Mode B (Maintenance Update Production Mode). Mode B may be installed using INSTALLPKG from the operator’s console or by using SOLAR in demand or batch mode. The user must have privileges allowing a SOLAR install.
To perform a Mode B installation from the operator’s console, start the INSTALLPKG runstream via the key unsolicited keyin ’ST INSTALLPKG’, and respond to the messages. Where:
Release 10R3: October 31, 2005 4-6 UniAccess for OS 2200 System Administration Guide
Product name is UNIACCESS,
Level is 10R3, and
Mode is B.
To perform a demand mode installation of Mode B, complete the actions listed below.
Step Action
1 Call the SOLAR processor by keying-in @SOLAR.
2 At the main menu, select Software Installation: Registered Packages.
3 At the Registered Packages Menu, find the UniAccess 10R3 Product. You may use F11 to search for the UniAccess 10R3 Product, or page through the packages (F6 amd/or F7).
4 Select the UniAccess Package by moving the cursor to UNIACCESS 10R3 and then pressing F8 to display the mdoe options.
5 At the Mode Selection Screen, select Mode B by placing a non-blank character next to Mode B and then pressing F5 (commit).
A runstream will be placed in SOLAR*RUNSTREAMS.PRODLD/xx.
6 If you are ready to start the runstream, select Y at the prompt, followed by F5. If you wish to start the runstream later, select N followed by F5.
The command to start the runstream is: @START SOLAR*RUNSTREAMS.PRODLD/xx.
The batch mode installation uses the SOLAR batch utility PRODLD. To perform a batch mode installation of Mode B, create a batch runstream containing the following syntax and start it.
@ELT,IS TPF$.PROD-LD,,PRODLD PACKAGE_TAPE_INFOREEL,UATAPE OPTIONS,TJ TYPE,HICL PRODUCT NAME,UNIACCESS LEVEL,10R3 MODE,B @END PRODLD
@SYS$LIB$*SOLAR.PRODLD,P TPF$.PROD-LD
Release 10R3: October 31, 2005 Installing the UniAccess System 4-7
Modes C and D Installation (Test Modes). Modes C and D may be installed using INSTALLPKG from the operator’s console or by using SOLAR in demand or batch mode. Refer to Mode B installation above for these procedures, substituting the term Mode C or Mode D for Mode B where appropriate.
Note For all modes, the installation procedure installs the UniAccess files listed in Appendix A. The installation procedure for Modes C and D, however, does not install the UniAccess Fixed-gate shared subsystem.
Following the SOLAR installation of Modes C or D, the user must tailor and install the UniAccess 10R3 Fixed-gate. An @ADD of the runstream UNIACCESS/SITE-INSTALL in file SYS$LIB$*UATEST requests the site-selected BDI for the UniAccess Fixed-gate and creates a runstream TPF$.INSTALL/UA-SITE that, once added, installs the fixed-gate.
Test Mode CMS Usage. If you wish to use a Mode A or B installation with a test mode CMS installation, you must manually build a new UACS by adding the runstream, SYS$LIB$*UAUTIL.UACSTC/BUILD. This runstream will build a UniAccess Communication Server that is linked to the test mode CMS installation. The new UACS will be named UACSTC and will be placed in the file SYS$LIB$*UAUTIL. The start scripts created during the SOLAR installation of UACS (SYS$LIB$*RUN$.UACS) must be modified to reference the UACSTC absolute or a new start script must be created. (See Chapter 17 for details about UACS processor execution options.)
If you wish to use a Mode C or D installation with a test mode CMS installation, you must update the file SYS$LIB$*UATEST.UACS/LINK runstream, adding an INCLUDE statement to LINK directives. (The location of the file being included is dependent upon how the test more CMS was installed.) This runstream is called via TPF$.INSTALL/UA-SITE to link UACS with the test mode CMS. The following example shows an updated SYS$LIB$*UATEST.UACS/LINK runstream using the default CMS test mode entry points:
Release 10R3: October 31, 2005 4-8 UniAccess for OS 2200 System Administration Guide
@LINK,S ,SYS$LIB$UAUTILT.UACS INCLUDE SYS$LIB$*UATEST.UACOMN/OBJ INCLUDE SYS$LIB$*UATEST.UACS/OBJ INCLUDE SYS$LIB$*EMOMRTS.C$NPADS INCLUDE CMS1100*TEST$LIB/CBEP$CMS RESOLVE ALL REFERENCES USING SYS$LIB$*EMOMRTS, SYS$LIB$*UAFGT,LCN set lowadr = 0130000 for all DATA banks except uas100$bank, uas101$bank, uas102$bank, uas103$bank, uas104$bank, uas105$bank, uas106$bank, uas107$bank, uas108$bank, uas109$bank, uas110$bank, uas111$bank, uas112$bank, uas113$bank, uas114$bank, uas115$bank, uas116$bank, uas117$bank, uas118$bank, uas119$bank set merge_order = any for all banks except urts$tables, ss$egy_list set merge_order = none for uas100$bank, uas101$bank, uas102$bank, uas103$bank, uas104$bank, uas105$bank, uas106$bank, uas107$bank, uas108$bank, uas109$bank, uas110$bank, uas111$bank, uas112$bank, uas113$bank, uas114$bank, uas115$bank, uas116$bank, uas117$bank, uas118$bank, uas119$bank set size = 0100000 for urts$tables process for extended zoom DELETE ALL DEFINITIONS EXCEPT starts SET ZERO_FILL = LOAD FOR ALL BANKS @EOF
(Refer to the Unisys OS 2200 Communications Management System (CMS 1100) Programming Reference for more details.)
Release 10R3: October 31, 2005 Installing the UniAccess System 4-9
CPComm Usage. If you wish to have UACS access CPComm directly, you must manually build a new UACS by adding the runstream, SYS$LIB$*UAUTIL.UACSCP/BUILD (or SYS$LIB$*UAUTILT.UACSCP/BUILD for Mode C or D). This runstream will build a UniAccess Communication Server that is linked to CPComm. The new UACS will replace the one in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT).
If CPComm is installed in a mode other than Mode A, the element UACSCP/BUILD should be updated to reflect the installation mode.
6. Obtain Hierarchical Service installation information
If the UniAccess Hierarchical Service is part of your site’s package, it must be defined and installed in each application group in which it will operate. An interactive runstream, described in step 7, will prompt for the following information and build an installation script for one application group.
6-1. The application number of the application group in which the UAHS transaction will operate. Defaults to 3.
6-2. The SUPUR file number in which the UAHS transaction will operate.
6-3. The transaction name for the UAHS transaction. Defaults to UAHS.
6-4. The transaction number for the UAHS transaction.
7. Install the UAHS transaction
An interactive SSG runstream named UAHS/INSTALL, located in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode installation), may be added at a demand terminal to generate the following runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode installation):
• UAHS/BUILD — Link, create a VALTAB and copy the UAHS transaction to the SUPUR file.
This runstream may be tailored to your site’s needs and then @ADDed to create and install the UAHS transaction.
Release 10R3: October 31, 2005 4-10 UniAccess for OS 2200 System Administration Guide
8. Create the UAHS Meta Database
The DMS schema information and relational mapping of the schema needed for UAHS to operate are contained in a TIP file called the UAHS Meta Database. The system administrator must create the TIP file, then use the utilities SCHEMADEF and TABLEDEF to enter the information needed by UAHS. See Building the UAHS Repository on page 14-3 for procedures and background information.
9. Update the UREP configuration MASTER-RUN-USERID attribute
If UARS is part of your site’s package and TIP session control is not is use, the UDS configuration must be modified to allow the default TIP userid to act as a MASTER- RUN-USERID. The default TIP userid is defined by the EXEC configuration parameter TIPSECUSER. If the TIPSECUSER parameter is not used, the default userid is binary zero and should be represented as "@@@@@@@@@@@@". The following commands must be executed to update the UREP CONFIGURATION MASTER-RUN-USERID attribute. (The tokens <
@DD,E ,,<
The following example demonstrates updating the MASTER-RUN-USERID for application group UDSSRC with a configuration name of RELEASE.
@DD,E ,,UDSSRC UPDATE CONFIGURATION RELEASE. ADD MASTER-RUN-USERID '@@@@@@@@@@@@'. PROCESS CONFIGURATION RELEASE INSTALL.
If an error occurs on the statement “ADD MASTER-RUN-USERID ‘@@@@@@@@@@@@’,” refer to the READ.ME document.
Release 10R3: October 31, 2005 Installing the UniAccess System 4-11
10. Obtain Relational Service installation information
If the UniAccess Relational Service is part of your site’s package, it must be defined and installed in each application group in which it will operate after step 9 has been completed. An interactive runstream, described in step 11, will prompt for the following information and build installation scripts for one application group.
10-1. The application number of the application group in which the UARS transaction will operate. Defaults to 3.
10-2. The application name of the application group in which the UARS transaction will operate. Defaults to UDSSRC.
10-3. The SUPUR file number in which the UARS transaction will operate.
10-4. The transaction name for the UARS transaction. Defaults to UARS.
10-5. The transaction number for the UARS transaction.
11. Install the UARS transaction
An interactive SSG runstream named UARS/INSTALL, located in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode installation), may be added at a demand terminal to generate the Relational Service installation runstreams. Five runstreams are generated and placed in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode installation):
• UARS/BUILD — Link, create a VALTAB and copy the UARS transaction to the SUPUR file.
• UNIACCESS/CREATE — Create the UNIACCESS1S1 schema used by the UARS transaction. (Refer to Appendix E, UniAccess System Tables for a description of site-maintained tables.) Note The UNIACCESS1S1 schema is required in each application group where the UARS transaction will be executed. Multiple UACSs running in an application group that schedules UARS transactions will use the same UNIACCESS1S1 schema.
Release 10R3: October 31, 2005 4-12 UniAccess for OS 2200 System Administration Guide
• UNIACCESS6R1/MIGRATE — Migrate site-specific data from the 6R1 schema to a 10R3 schema.
• UNIACCESS/DELETE — Delete the UNIACCESS1S1 schema used by the UARS transaction.
• UNIACCESS6R1/DELETE — Delete a pre-6R2 version of the UNIACCESS schema.
These runstreams may be tailored to your site’s needs and then @ADDed to create and install the UARS transaction and the UNIACCESS database.
The UNIACCESS/CREATE runstream updates the attributes RDMS-LEVEL and VIEW-PROCESSING in the OPTIONS RDMS entity. The RDMS-LEVEL attribute is set to a value of COMPLETE and the VIEW-PROCESSING attribute is set to a value of IMMEDIATE. These settings are necessary to enable UREP to capture meta- database information that will be used by the UniAccess Relational Service.
The UNIACCESS/CREATE runstream also creates the UNIACCESS1S1 schema. This schema includes views of the RDMS catalog. Therefore, the userid used to add this runstream must be allowed to access the RDMS database.
The UNIACCESS6R1/MIGRATE runstream extracts site-defined entries for procedures and columns from the 6R1 UNIACCESS schema and inserts them into the 10R3 schema. Any other site modifications to the 6R1 schema must be applied manually to the 10R3 schema. This script can only be used for upgrades between these levels. The userid used to add this runstream must be the owner of the 6R1 UNIACCESS schema.
The UNIACCESS/DELETE runstream must be @ADDed by the owner of the UNIACCESS1S1 schema.
The UNIACCESS6R1/DELETE runstream must be @ADDed by the owner of the UNIACCESS schema.
Release 10R3: October 31, 2005 Installing the UniAccess System 4-13
12. Prepare the UREP Repository
When the ODBC Server for RDMS 2200 is included in a UniAccess installation, the system administrator should address the items discussed below. These items relate to entities and information contained in the Unisys Repository (UREP). General procedures are described here. For details and specific UREP command syntax, refer to the Unisys Repository Manager (UREP) Administration Guide and Unisys Repository Manager (UREP) Programming Reference Manual.
Storage Areas
There are two options for storage areas when ODBC clients create RDMS tables. You can specify that tables (for one or more ODBC data sources) reside in a pre-defined storage area; or you can allow RDMS to implicitly create an area for each CREATE TABLE SQL request issued by a client. You can also use a combination of the two techniques. By default the UniAccess ODBC Driver will use implicit storage areas.
Explicitly Controlled Storage Areas. If you wish to have newly created tables reside in pre-defined storage areas, the areas must be defined (external to the UniAccess System) before the tables are created. To define a storage area:
• Catalog the EXEC file that will contain the storage area
• Create and install the STORAGE-AREA in UREP.
The client user then configures the name of UREP storage-area entity in the UniAccess ODBC data source on the client workstation (see page 7-4).
Implicitly Created Storage Areas. If you want RDMS to create all storage areas implicitly, no action is necessary during installation. RDMS will create storage areas with the same names as the tables. However, remember that such storage areas are not deleted by DROP TABLE commands. The system administrator must manually delete the area (in UREP) before another table with the same name can be created. The system administrator must also manually delete the EXEC file that was created to contain the storage area.
Release 10R3: October 31, 2005 4-14 UniAccess for OS 2200 System Administration Guide
Populate the Repository
The UARS installation (specifically, the UNIACCESS/CREATE runstream on page 4-11), will configure UREP to track detailed data about all RDMS 2200 objects. This meta-database information allows UARS to provide the catalog information required for ODBC support. However, such details may not be available for objects that were created prior to UARS installation. In this case, the information must be extracted from an RDMS internal table called the Relational Description Table (RDT). To copy the information about tables and views from the RDT to the repository, use the UREP PROCESS command with the ATTACH option for each table and view.
13. Obtain UAINFO installation information
Configure the UAINFO transaction in each application group for which you wish to schedule UASL transactions using the UniAccess ODBC Driver. An interactive runstream, described in step 14, will prompt for the following information and build an installation script for one application group.
13-1. The application number of the application group in which UAINFO will operate. Defaults to 3.
13-2. The SUPUR file number in which the UAINFO transaction will operate.
13-3. The transaction name for the UAINFO transaction. Defaults to UAIN.
13-4. The transaction number for the UAINFO transaction.
14. Install the UAINFO transaction.
An interactive SSG runstream named UAINFO/INSTALL, located in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations), may be added at a demand terminal to generate the following runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode installation):
UAINFO/BUILD — Link, create a VALTAB and copy the UAINFO transaction to the SUPUR file
This runstream may be tailored to your site’s needs and then @ADDed to create and install the UAINFO transaction.
Release 10R3: October 31, 2005 Installing the UniAccess System 4-15
15. Configure and install the ASCII COBOL Interface
UniAccess is installed as an extended-mode fixed-gate subsystem. If Server-Library transactions are to be created using ASCII COBOL, the ASCII COBOL Interface must be installed to enable the transactions to access the fixed-gate subsystem.
To create an installation runstream for the ASCII COBOL Interface, an interactive SSG runstream named UASLBMB/INSTALL may be added at a demand terminal. The UASLBMB/INSTALL runstream is located in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations). This runstream requests a site-selected BDI for the alternate file common bank (AFCB) used by the ASCII COBOL Interface. The installation runstream that UASLBMB/INSTALL creates is named UASLBMB/BUILD. It is located in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations). The UASLBMB/BUILD runstream may be tailored to your site’s needs and then @ADDed to install the ASCII COBOL Interface.
16. Install the UniAccess Samples
To set up the sample system, you must create the sample database and then build and install the client and server applications. Scripts to create all the components of the sample system are included with each product package. However, UniAccess Transaction Server must be installed in order to compile and run the Transaction Server examples, and UniAccess Transaction Client must be installed in order to compile and run the Transaction Client examples. The PC Client sample requires either the UniAccess Transaction Server or the UniAccess ODBC Server for RDMS 2200. Refer to Appendix C, Setting up the Sample System, for instructions on installing the UniAccess Samples.
Release 10R3: October 31, 2005 4-16 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 5 Planning Configuration 5 Planning Your UniAccess Configuration
This chapter describes basic configuration of the UniAccess System. It identifies and describes the statements and parameters required to make the system operational. It also describes the source files involved in configuration and the templates provided with the product. Note that this chapter is limited to the minimum configuration requirements; many other configurations options are available. All configuration options are described in Chapter 16, UniAccess Source Configuration Statement Reference.
Topics Page
Configuration Overview 5-1 Configuration Requirements 5-3 Explanation of Configuration Requirements 5-4
Configuration Overview After you have installed the UniAccess product tape and prior to starting UACS, you must configure the UniAccess System to your site’s environment and specify its operational characteristics. To assist you in configuring UniAccess, AIS provides two configuration files. The UA Information File contains information that will only be modified by sites wishing to localize the error messages. The Site Information File contains site-specific configuration information. (See page 16-9 for more information about these two source configuration files.)
The UA Information File is the element UNIACCESS/INC in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations). For the most part, information in this file will remain constant and does not need to be updated by the site.
Release 10R3: October 31, 2005 5-2 UniAccess for OS 2200 System Administration Guide
AIS provides the following four templates for the Site Information File in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations):
• UATC/CFG — Site Information File template for UniAccess Transaction Client customers
• UATS/CFG — Site Information File template for UniAccess Transaction Server customers
• UAOSRDMS/CFG — Site Information File template for UniAccess ODBC Server for RDMS 2200 customers
• UAOSDMS/CFG — Site Information File template for UniAccess ODBC Server for DMS 2200 customers.
For each of these templates, AIS has indicated which values are required by including the # sign. You may add other configuration statement parameters to set additional characteristics. Those characteristics that you do not chose to set will default to the values assigned by AIS. The example below illustrates a section of the UATS/CFG template:
APPINF APPNUM,## ; APPNAME,###### ; MCBBDI,040####
The template should be edited and the updated configuration should be saved in a locally selected file. (Saving the updated configuration in the file provided by UniAccess will result in it being overwritten in subsequent installs of UniAccess.) The following example shows how the values in the above template might be completed and additional statement parameters added. (Note that the product key in the example is not a valid product key.)
APPINF APPNUM,3 ; APPNAME,UDSSRC ; MCBBDI,0400612 OSPARM SESSCTRL,YES ; UARSPRODKEY,12345678-12345678-12345678-12345678 ; UASLPRODKEY,12345678-12345678-12345678-12345678 COMSRV PROCNAM,UACS3; APPNUM,3 ; DFLTTRAN,UARSTRAN ; PIDCNT,10000 ; PIDSTART,100
Release 10R3: October 31, 2005 Planning Your UniAccess Configuration 5-3
Configuration Requirements Before you begin work with the configuration template, you should complete the Configuration Checklist found in Table 5-1. This table lists the minimum required host values you will need to complete the Site Configuration File. It explains which parameters are required and which are optional for each UniAccess product. The discussion that follows this table explains each of these values in more detail. Chapter 16 describes all the available UniAccess configuration parameters. Appendix B gives configuration examples.
Table 5-1: UniAccess Configuration Checklist
Host Requirements UniAccess Product Requirements
ODBC ODBC Transaction Transaction Server for Server for Client Server RDMS 2200 DMS 2200
1. Indicate the product key(s) required required required required 2. Assign a UACSTYPE for each UACS required required required required 3. Assign a process name and password required required required required for each UACS 4. Assign an application group name and n/a required required required number for each UACS 5. Assign an MCBBDI for each n/a required required required application group 6. Assign a UDSBDI for each application n/a optional optional n/a group 7. Specify the UAHS Meta Database TIP n/a n/a n/a required file number 8. Assign a PID range and starting PID required required required required for each UACS 9. Indicate that TIP session control is on, n/a required required required if applicable 10. Assign a port for each UACS n/a required required required 11. Assign language transactions for each n/a optional required required UACS 12. Assign a default language transaction n/a optional required required and services for each UACS
Release 10R3: October 31, 2005 5-4 UniAccess for OS 2200 System Administration Guide
Host Requirements UniAccess Product Requirements
ODBC ODBC Transaction Transaction Server for Server for Client Server RDMS 2200 DMS 2200
13. Configure the UAINFO transaction n/a optional n/a n/a 14. Determine the default processing n/a optional optional n/a environment for RPCs and/or create RPC map records 15. Define default operational n/a n/a optional optional characteristics for the UARS and UAHS language transactions 16. Define UAUSER statements required required required required 17. Indicate the server name, port, and I.P. required n/a n/a n/a address to which a UACL application will be allowed to connect
Explanation of Configuration Requirements
1. Indicate the product key(s)
You must indicate the product key(s) for each UniAccess for OS 2200 product package that is purchased. Up to four product keys may be entered. The product keys are indicated by entering the key as the value for the OSPARM UACLPRODKEY, OSPARM UAHSPRODKEY, OSPARM UARSPRODKEY, and/or OSPARM UASLPRODKEY configuration parameters. At least one of these parameters is required.
If the product was shipped directly to you by AIS, the product key(s) are included with the shipment of the product.
All Unisys customers should obtain the necessary permanent UniAccess product keys by contacting UniAccess Technical Support at:
Phone (703) 860-7808 FAX (703) 860-7820 Email [email protected]
Release 10R3: October 31, 2005 Planning Your UniAccess Configuration 5-5
Note ClearPath limited license customers receive temporary product keys with the UniAccess 10R3 PC Client CD shipped by Unisys. However, they still need to contact UniAccess Technical Support to obtain permanent keys. Permanent keys should be ordered before the temporary keys expire to assure continued use of the product.
2. Assign a UACSTYPE for each UACS
If the site has licensed UniAccess Transaction Server, ODBC Server for RDMS, or ODBC Server for DMS, all instances of UACS should have a COMSRV UACSTYPE of UATS. If the site has licensed UniAccess Transaction Client, all instances of UACS should have a UACSTYPE of UATC. If the site has licensed both Transaction Server and Transaction Client, the UACSTYPE can be UATC, UATS, or UATC/UATS.
3. Assign a process name and password for each UACS being defined
Each UACS being defined must have unique COMSRV PROCNAM and PROCPSWD configuration parameters. (Multiple UACSs must be assigned unique COMSRV PROCNAM parameters.) These parameters must match the PROCESS name and PASSWORD in the CMS 1100 or CPComm configuration file. When using CMS 1100, the PROCESS network definition statement must be of type TSAM.
4. Assign an application group name and number for each UACS
Each application group in which a UACS will participate must be defined with the APPINF APPNAME configuration parameter. Each application group number must be defined in the APPINF APPNUM parameter as well as the COMSRV APPNUM parameter. (This step is not required if all instances of the COMSRV UACSTYPE configuration parameter within this application group are set to UATC.)
UniAccess may access any valid application group consisting of the EXEC and MCB at a minimum. If UniAccess programs access UDS data, UDS and the IRU are required in the same application group. Therefore, the APPINF APPNUM and COMSRV APPNUM values must be defined in the EXEC and must match the MCB parameter APNUMBER and the UDS dynamic configuration parameter APPL-GROUP-NUMBER. The UniAccess APPINF APPNAME value must be
Release 10R3: October 31, 2005 5-6 UniAccess for OS 2200 System Administration Guide
defined in the EXEC and must match the MCB parameter APNAME and the UDS dynamic configuration parameter APPL-NAME.
5. Assign an MCBBDI for each application group
An MCB bank descriptor index (BDI) must be defined in the APPINF MCBBDI configuration parameter. This is the BDI for the MCB interface bank (MCBBNK) in the application group that has been defined by the APPNUM parameter. It is a six-digit octal number with a range from 0400001 to 0407777. A unique MCBBDI is required for each application group. (This step is not required if all instances of the COMSRV UACSTYPE configuration parameter within this application group are set to UATC.)
The UniAccess APPINF MCBBDI parameter must match the MCB MCBBDI and the UDS MCB-MSG-BANK-BDI statement.
6. Assign a UDSBDI for each application group.
Each application group using UniAccess distributed transaction processing must have a UDS bank descriptor index (BDI) defined in the APPINF UDSBDI configuration parameter. This is the UDS thread control ICR bank in the application group defined by the APPNUM parameter. It is a six-digit octal number with a range from 0400001 to 0407777. A unique UDSBDI is required for each application group that will process UniAccess distributed transactions. (This step is not required if your site is not using UniAccess distributed transaction features.)
The UniAccess APPINF UDSBDI parameter must match the BDI assigned to the installed TICRI bank for this application group (see page 16-11 for more information).
7. Specify the UAHS Meta Database TIP file number
In a UAHS environment, you must configure a value for the APPINF UAHSTIPF parameter for each application group that will be using UAHS. This parameter gives the TIP file number of the UAHS Meta Database. The file is a repository of relational mappings of a DMS schema for an application group. The TIP file is created using usual methods for user FCSS files, and is then populated by the UAHS utilities, SCHEMADEF and TABLEDEF. For more information on the UAHS Meta Database, see Chapter 14.
Release 10R3: October 31, 2005 Planning Your UniAccess Configuration 5-7
The APPINF UAHSTIPF value must be a number with the range of 12—TIPMEF, where TIPMEF is an EXEC system generation parameter specifying the maximum number of EXEC files that may be registered with TIP.
8. Assign a PID range and starting PID for each UACS
Unique UniAccess COMSRV PIDCNT and PIDSTART parameters must be assigned to each UACS being configured. There is a one-to-one relationship between PIDs and connections; therefore, this value indicates the maximum number of concurrent connections that will be supported. PID ranges among COMSRV records may not overlap; that is, each UACS must be assigned a unique range of PIDs. PIDSTART is the first PID of a group of consecutive PIDs. (When the UACSTYPE parameter is set to UATC, this value simply indicates the number of connections supported.)
The following conditions must also be met, except when the COMSRV UACSTYPE configuration is set to UATC:
• The UniAccess PID range covered by the COMSRV PIDCNT and PIDSTART parameters must be within the range of PIDS configured by the MCB P$ID configuration statement. These PIDs must not be in use by CMS or MAPPER when the associated COMSRV is active.
• If TIP session control is on, you must define the maximum number of sessions that can exist for each application group in which UACS will be operating. The value is defined in the STEPCONTROL NUMBER-OF-CONCURRENT- SESSIONS parameter of the EXEC. This number must be large enough for UACS to establish a session for each PID assigned to it. If you will be utilizing non-UniAccess transactions, as well as UniAccess transactions within an application group, the number of concurrent sessions must be large enough to allow UACS to establish a session for each PID while the non-UniAccess transactions are active.
Note The number of current connections supported by a UACS execution is the smaller of the COMSRV PIDCNT parameter, the UAMM PROCCNT parameter, or the sum of concurrent connections supported by the product keys (the UACLPRODKEY, UAHSPRODKEY, UARSPRODKEY, and UASLPRODKEY parameters of the OSPARM statement).
Release 10R3: October 31, 2005 5-8 UniAccess for OS 2200 System Administration Guide
9. Indicate that TIP session control is on, if applicable
If TIP session control is turned on in your system, you must indicate so by setting the OSPARM SESSCTRL configuration parameter to YES. Otherwise, this parameter defaults to NO. (This parameter is not required if all instances of the COMSRV UACSTYPE configuration parameter are set to UATC.)
If this parameter is YES, you must configure the maximum number of sessions and the session file in the EXEC configuration (see step 4).
If your site has made custom modifications to the TIP session control prompts, you may need to configure additional parameters in the OSPARM configuration statement. (Refer to the OSPARM statement in Chapter 16 for a description of these parameters.)
10. Assign a port for each UACS
You must assign a port upon which each UACS will listen for connections by defining the COMSRV LISTENPRT configuration parameter. We recommend that values for this parameter start above 1024. Each UACS must be assigned a unique address, which is a combination of an I.P. address and a port number. The I.P. address is determined by the INTERNET-ADR parameter of the PROCESS specified in step 3. Clients use this address to establish a connection with UACS (see page 7-3).
Note If multiple Internet addresses are supported by UACS (that is, the COMSRV MULTIIP configuration parameter is set to YES), then the port number must be unique.
11. Assign language transactions for each UACS.
A UACS can concurrently support three language transactions: UARS, UAHS, and a user-written language transaction. These are defined in the UARSTRAN, UAHSTRAN, and USERTRAN parameters of the COMSRV statement. For UARSTRAN, the value supplied must match the value supplied in the UARS/BUILD runstream (see page 4-11). For UAHSTRAN, the value supplied must match the value supplied in the UAHS/BUILD runstream (see page 4-9). If USERTRAN is configured, the value supplied must match the TIP VALTAB ACT statement variable identified as the user-written language transaction.
Release 10R3: October 31, 2005 Planning Your UniAccess Configuration 5-9
If one or more of the above parameters are selected, you must also designate a default language transaction.
12. Assign a language transaction and services for each UACS.
The COMSRV DFLTTRAN parameter defines the default language transaction and services that are available to Open Client applications and to ODBC applications using a pre-9R1 UADriver. The UniAccess 9R1, and later version of UADriver can override these settings.
The default language transaction is used to process language requests from Open Client applications. This transaction is also used to process catalog RPCs (either UAHS or UARS). If the site desires to allow client applications to request information about Server-Library transactions, the parameter should be set to UARSTRAN.
The COMSRV DFLTTRAN parameter also specifies the default services (UAHS, UARS, and/or UASL) that will be available from Open Client applications and ODBC applications using a pre-9R1 UADriver.
ODBC users can override this value by configuring another language transaction via the UADriver Data Source Administrator. Open Clients cannot override this value.
13. Configure the UAINFO transaction.
If the UAINFO transaction has been installed (see page 4-14), it must be configured for the UACS on which it will run. To configure the UAINFO transaction assign a value for the COMSRV UAINTRAN configuration parameter. This value must match the (TIP) VALTAB ACT statement variable suppled in the UAINFO/BUILD runstream (see page 4-14).
14. Determine the default processing environment for RPCs and/or create RPC map records.
When RDMS 2200 stored procedures and Server-Library transactions are supported in the same environment, the possibility exists that an RDMS procedure and a Server- Library transaction can have the same name. The RPCMAP record is the definitive way of defining how UACS will route RPCs, and can help alleviate the problem of conflicting names. This configuration statement maps RPC names of up to 30
Release 10R3: October 31, 2005 5-10 UniAccess for OS 2200 System Administration Guide
characters to their appropriate VALTAB transaction codes. In addition, the OSPARM DFLTPROCENV configuration parameter allows you to designate a default processing environment for unmapped RPCs sent to the UniAccess System.
15. Define default operational characteristics for the UARS and UAHS language transactions.
The HIERSRV and RELSRV configuration statements define operational characteristics for the UAHS and UARS language transactions respectively. The system administrator can use these statements to set default settings for the individual user records defined with the UAUSER statement. Defining these statements can avoid having to set each parameter of a UAUSER record individually for each user. Most HIERSRV and RELSRV parameters have default values that will be used if a setting is not assigned. However, the HIERSRV SCHEMAH parameter does not have a default value. If you are configuring UniAccess ODBC Server for DMS 2200, the HIERSRV statement must include a SCHEMAH parameter or the parameter must be set individually for each user.
Most parameters of the HIERSRV, RELSRV, and UAUSER configuration statements may be set to allow client applications to override the parameter’s default settings. These parameters correspond to required and optional settings for ODBC and Open Client applications. ODBC clients set these options through the UADriver Setup dialog boxes or through connection string attribute names (described in Chapter 5 of the UniAccess for OS 2200 Client Guide). Open Clients may set these options through UARS and UAHS commands (see Chapter 7 and Chapter 10 respectively of the UniAccess for OS 2200 Client Guide).
16. Define UAUSER statements
A UniAccess UAUSER configuration statement must be defined for each user of the UniAccess System except under the following circumstances:
• For UASL, if the COMSRV USEUAUSER parameter is set to NO.
• For UARS and UAHS, if the COMSRV USEUAUSER parameter is set to NO and if one default UAUSER record is configured for all users
• For UACL, if one default UAUSER record is configured for all users.
Release 10R3: October 31, 2005 Planning Your UniAccess Configuration 5-11
A default UAUSER record is set up with a USERID of “@@@@@@@@@@@@” (see page 16-79).
For UACL, the UAUSER USERID parameter must be a valid userid on remote servers being accessed.
If TIP session control is on, UniAccess users should be assigned valid TIP userids. The userid can be created using SIMAN. The remote client builds the logon packet containing the userid and password. The UniAccess System utilizes defaults for any other field requested during the TIP session manager sign-on sequence. Therefore, the userid should be created with valid default values.
17. Indicate the server name, port, and IP address to which a UACL application will be allowed to connect
For UACL, you must configure the name, port, and either the host name or Internet address of all servers to which UniAccess Client-Library programs may connect. This information is defined in the SERVER configuration statement’s NAME, PORT, HOSTNAME, and ADDR parameters. A maximum of 1,000 SERVER statements may be configured.
If the server being configured is a SQL Server, the name, port, and either the host name or Internet address must match those in the SQL Server configuration. If this server is a UniAccess server, the name and port must match the COMSRV PROCNAM and LISTENPRT parameters, respectively. Additionally, either the Internet address should match the address in the CMS 1100 INTERNET-ADR statement (or the CPComm IP statement), or the HOSTNAME should resolve to match this address.
Release 10R3: October 31, 2005 5-12 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 6 Managing UniAccess 6 Managing the UniAccess System
This chapter provides an overview of UniAccess System management. It also explains the implementation and management of the UniAccess Fixed-gate subsystem, including the initialization of UAMM.
Topics Page
Starting UniAccess Operations 6-2 Overview of UniAccess System Management 6-3 UniAccess Configuration Management 6-3 UniAccess Fixed-gate Management 6-5 Steps in UniAccess System Management 6-8 Initial UniAccess System Execution 6-8 Subsequent UniAccess System Executions 6-10
Release 10R3: October 31, 2005 6-2 UniAccess for OS 2200 System Administration Guide
Starting UniAccess Operations After completing the UniAccess Configuration Checklist in Chapter 5, you are ready to begin operation of the UniAccess System. If this is a first-time installation, you are advised to read the Overview of UniAccess System Management section in this chapter before proceeding. Table 6-1 lists the steps required to begin UniAccess operations following an installation. Information on subsequent UniAccess System executions is found on page 6-10.
Table 6-1: Steps in Starting UniAccess Operations
Step Action to be taken Reference
Preliminary Read the Overview of UniAccess System Management page 6-3 section in this chapter.
1 Execute UACF to check the syntax of the Source page 6-9, page 17-2 Configuration Files.
2 Execute UACF to generate the UniAccess Configuration page 6-9, page 17-2 File from the Source Configuration File.
3 Execute UACF to initialize the UniAccess Fixed-gate. page 6-9, page 17-2
4 Start UACS. page 6-10, page 17-6
Release 10R3: October 31, 2005 Managing the UniAccess System 6-3
Overview of UniAccess System Management When the UniAccess System has been installed on your OS 2200 system, you will have the following components in place:
• The two processors that manage the UniAccess System—the UniAccess Configuration utility (UACF) and the UniAccess Communication Server (UACS)
• The UniAccess Fixed-gate (UAFG) shared subsystem that contains UADT, UASL, UACL, and UAMM (depending on what products have been purchased for your site)
• Two source configuration files—the Site Information File and the UA Information File.
Information utilized by these components is maintained by the configuration management system. This system consists of the configuration utility (UACF) and the data management service (UADT) within the UniAccess Fixed-gate (see Figure 6-1). The information maintained by this system is shared by all other components of the UniAccess System.
This chapter discusses UniAccess configuration management, management of the UniAccess Fixed-gate subsystem, and the steps required for initial and subsequent system executions.
UniAccess Configuration Management
The UniAccess Configuration utility (UACF) processes three files: the Site Information File, the UA Information File, and the UniAccess Configuration File. The Site Information File and the UA Information File can be either SDF data files or symbolic elements in a program file. They contain the configuration statements that define the environment in which the UniAccess System operates and specify its operational characteristics. The Site Information File contains site-specific configuration statements while the UA Information File contains general configuration statements that will not be modified at most sites. Both source files are read by the UACF utility and converted to the UniAccess Configuration File that exists in a fixed binary form, which is readable by UniAccess products. (The minimum requirements for operational source configuration were presented in Chapter 5. Chapter 16 is a complete configuration reference.)
Release 10R3: October 31, 2005 6-4 UniAccess for OS 2200 System Administration Guide
UniAccess Fixed-Gate
UASL UACS 2 UAMM
UACL
UACS 1 UADT
Site Information File UniAccess UniAccess Configuration Configuration UA Utility File Information File
Figure 6-1: The UniAccess Configuration Management Design
The UACF processor must be executed at least twice to initialize the UniAccess System. First, it is executed to read the two source configuration files and to create the UniAccess Configuration File. In doing so, it checks the syntax of source statements and verifies that the necessary relationships exist among them. (The syntax check can also be done with a separate UACF execution, prior to the actual Configuration File creation.)
Release 10R3: October 31, 2005 Managing the UniAccess System 6-5
After the configuration succeeds, UACF must be executed again to initialize UAFG. During this step, it initializes the UAMM and UADT services within the fixed-gate. When the UACS processor (UniAccess Communication Server) is executed, it reads its operational information from the UniAccess Configuration File and retrieves user and other information from UADT. (For a description of the data banks housed within UADT, see the section beginning on page 8-17.)
UniAccess Fixed-gate Management
The UniAccess Fixed-gate (UAFG) is a system-wide shared subsystem that contains the UniAccess Data Manager (UADT), UniAccess Server-Library (UASL), UniAccess Client- Library (UACL), and UniAccess Message Manager (UAMM) services. Although many UACSs may operate simultaneously within one OS 2200 system, they will all share a single UAFG and the services it provides (see Figure 6-1). This organization facilitates the administrator’s management of the UniAccess Fixed-gate.
Note The discussion, illustrations, and examples in this chapter refer to a single (Mode A or B) installation of UniAccess with one UACS being configured on a fixed-gate. If your site has more than one fixed-gate and/or more than one UACS per fixed gate, the procedures will remain the same, however the syntax may differ slightly. Refer to page 17-2 for specific information about the UACF processor syntax.
Fixed-gate Design
UAFG is an OS 2200 protected fixed-gate shared subsystem (FGSS). An FGSS is a software subsystem, the extended mode equivalent of common banks. These banks are loaded into memory when they are first referenced and logically remain there until the subsystem is explicitly deactivated or implicitly deactivated by a system stop. (OS 2200 subsystems are discussed in the Unisys OS 2200 Linking System Subsystems Programming Guide.)
The UAFG fixed-gate shared subsystem, illustrated in Figure 6-2, is comprised of:
• A shared object module—UAOM
Release 10R3: October 31, 2005 6-6 UniAccess for OS 2200 System Administration Guide
• A subsystem definition element—SSDEF$
• A fixed-gate definition element—MASM-EP.
UniAccess Fixed-Gate
Shared Object Subsystem Definition Fixed-Gate Module Module Definition Element
UAOM SSDEF$ MASM-EP
SYS$LIB$*UAOM SYS$LIB$*UAFG
Figure 6-2: UAFG Shared Subsystem Overview
The shared object module, UAOM, resides in the file SYS$LIB$*UAOM (or SYS$LIB$*UAOMT for test mode installations). The object module is the functional equivalent of a basic mode common bank. In extended mode terminology, this is known as a shared bank. A shared bank can be utilized by one or more programs, but only one copy exists in main memory regardless of how many programs are using it.
The subsystem definition module, SSDEF$ in the file SYS$LIB$*UAFG (or SYS$LIB$*UAFGT for test mode installations), defines the characteristics of the subsystem. The UAFG subsystem is defined as a protected subsystem. The shared bank can be found in the file UAOM. The external entry points are defined as public fixed-gates, located in the file named UAFG.
Release 10R3: October 31, 2005 Managing the UniAccess System 6-7
The fixed-gate definition element, MASM-EP in the file SYS$LIB$*UAFG (or SYS$LIB$*UAFGT for test mode installations), is an object module that contains the fixed, virtual addresses representing the location of the gates in main storage. The Linking System will use these definitions to satisfy references within the user program to the subsystem.
Activating and Deactivating the Fixed Gate
By design, fixed-gate subsystems are loaded and activated the first time they are referenced. They logically remain in main memory until deactivated, explicitly or implicitly. However, two services within the UniAccess Fixed-gate (UAFG) must be initialized by the UniAccess Configuration Utility (UACF) before other components of the UniAccess System may use them.
The UAMM and UADT services of UAFG are initialized using the ‘I’ option on the UACF processor (see page 17-4). The UAMM service may only be initialized once. If changes must be made to UAMM configuration information, the fixed-gate must be deactivated and then reinitialized using UACF (see page 18-4). The UADT service may be reloaded using the ‘L’ option without deactivating UAFG. A typical use of the UADT reload facility would be to add a new user or server definition without deactivating UAFG.
Fixed-gate subsystems can only be deactivated (i.e., logically unloaded from memory) by the SOLAR DEACT utility or by a system stop. The runstream SYS$LIB$*UAUTIL.DEACTUAFG (SYS$LIB$*UAUTILT.DEACTUAFG for test mode installations) is provided to perform this function. SYS$LIB$*UAUTIL.DEACTUAFG invokes the SOLAR DEACT program and passes the proper qualifier, filename, file cycle, and element name of the subsystem definition element for the UAFG subsystem.
Release 10R3: October 31, 2005 6-8 UniAccess for OS 2200 System Administration Guide
Steps in UniAccess System Management After you have built the two source configuration files (the Site Information File and the UA Information File) following the steps outlined in Chapter 5, you will then need to execute the UniAccess Configuration utility to generate the UniAccess Configuration File and initialize UAFG. The UACF utility has several modes of execution. Each of these options is explained in Chapter 17, which gives the syntax of UACF execution.
Initial UniAccess System Execution
The first time you initiate the operations of the UniAccess System, you should perform each of the UACF executions described in this section independently before starting UACS (see Figure 6-3).
4 Start UACS
3 Initialize UAFG succeeds
2 Generate Configuration File
Check messages, 1 Check Configuration File Syntax Correct problems
fails
Source Check messages, Configuration Correct problems File
Figure 6-3: Steps in Initially Starting UniAccess Operations
Release 10R3: October 31, 2005 Managing the UniAccess System 6-9
Step 1) Execute UACF to check the syntax of the Source Configuration File
Use the ‘S’ option in the UACF execution statement to perform a syntax check on the contents in the two source configuration files—the Site Information File and the UA Information File—before generating the UniAccess Configuration File. The following is an example of executing UACF for a syntax check using the default UA Information File (SYS$LIB$*UAUTIL.UNIACCESS/INC). (See page 17-4 for detailed information about the ‘S’ option of the UACF execution syntax.)
@SYS$LIB$*UAUTIL.UACF,S qual*file.configfile
UACF will process the Site Information File first and then the UA Information File. If any errors are detected in the Site Information File, the UA Information File will not be processed. If errors are detected in either file, the UACF processor will return an appropriate error message. (The description of messages returned by UACF begins on page D-40.) Correct any error that occurred and perform Step 1 again.
Note You may use the ‘M’ option with the ‘S’ option to find the amount of dynamic memory that will be used by the configuration, in addition to the syntax check. (See page 8-16 for information about UniAccess memory utilization in conjunction with page 8-22 which explains the report generated by the ‘M’ option.)
Step 2) Execute UACF to generate the UniAccess Configuration File
Use the ‘A’ option in the UACF execution statement to request that UACF generate the UniAccess Configuration File. The following is an example of generating the default UniAccess Configuration File (UNIACCESS*CONFIG) using the default UA Information File (SYS$LIB$*UAUTIL.UNIACCESS/INC). (See page 17-3 for detailed information about the ‘A’ option of the UACF execution syntax.)
@SYS$LIB$*UAUTIL.UACF,A qual*file.configfile
Step 3) Execute UACF to initialize UAFG
Execute UACF to initialize UAFG using the ‘I’ option of the UACF execution statement. The following is an example of performing an initialization of UAFG using the default
Release 10R3: October 31, 2005 6-10 UniAccess for OS 2200 System Administration Guide
UniAccess Configuration File (UNIACCESS*CONFIG). (See page 17-4 for detailed information about the ‘I’ option of the UACF execution syntax.)
@SYS$LIB$*UAUTIL.UACF,I
UAFG initialization loads selected information from the UniAccess Configuration File into the UAFG subsystem. This step must be performed only once, such as after installing UniAccess, after every system boot, and after deactivating UAFG.
Step 4) Start UACS
UACS is executed as an OS 2200 processor and accepts command line parameters. The following is an example of starting a default installation of UACS:
@SYS$LIB$*UAUTIL.UACS ,UACS
UACS is normally started by a batch runstream that calls the UACS processor. Installation Modes A and B will create a runstream in SYS$LIB$*RUN$.UACS (SYS$LIB$*RUN$.UACST for Modes C and D), which calls the UACS processor. This runstream can then be started at the console with an ST keyin. ST keyin syntax will be dependent upon the OS 2200 security environment implemented.
Subsequent UniAccess System Executions
To Reconfigure UniAccess
The procedures for UniAccess System executions required for reconfiguring UniAccess depend on the particular configuration statements involved and on the UniAccess System component (UADT, UACS, UAMM) affected. Reconfigurations always involve rebuilding the configuration file and may require loading selected information into the Fixed-gate, restarting UACS, or reinitializing the UniAccess Fixed-gate. Chapter 18 outlines these various procedures and the circumstances for employing them. It also details reconfiguration information required for adding new users or a new UACS.
Following a System Reboot
After any OS 2200 System reboot, the following steps must be completed:
Release 10R3: October 31, 2005 Managing the UniAccess System 6-11
• Initialize UAFG with the ‘I’ option on the UACF execution statement, as explained in Step 3 above.
• Start all UACS runs with the UACS command line, as explained in Step 4 above.
To initialize the Fixed-gate automatically following a system reboot or system stop, add the statement @SYS$LIB$*UAUTIL.UACF,I (or SYS$LIB$*UAUTILT. UACF,I for test mode installations) in the SYS$LIB$*RUN$.UACS runstream prior to the UACS processor call . For example:
@RUN,/LK UACS,0/0,SYS$,9999,9999/9999 @. @.SET UP DIAG$ @. @FREE DIAG$ @CAT,P UACS*DIAG$FILE(+1).,F/200//9000 @ASG,AX UACS*DIAG$FILE. @USE DIAG$.,UACS*DIAG$FILE. @. @.EXECUTE UACS @. add-> @SYS$LIB$*UAUTIL.UACF,I @COPY,A SYS$LIB$UAUTIL.UACS,TPF$.UACS @FREE SYS$LIB$*UAUTIL. @TPF$.UACS UNIACCESS*CONFIG.,UACS @FIN
If the Fixed-gate has already been initialized, you will receive the error message:
UAMM initialization failed [1] [0]. [3] *ERROR * UACF processing failed
This error message can be ignored.
Note If both production and test mode versions of UniAccess are installed on a system, both Fixed-gate subsystems must be initialized following a reboot. This is accomplished by executing the appropriate UACF for each subsystem.
Release 10R3: October 31, 2005 6-12 UniAccess for OS 2200 System Administration Guide
To Deactivate and Reinitialize UAFG
The UniAccess Fixed-gate should be deactivated when the UAMM configuration statement must be reconfigured or to recover UAMM connection slots that are marked in error.
Note System administrators can determine when an excessive number of UAMM connection slots are marked in error by reviewing the UAMM statistics. (Refer to page 19-29 for information on obtaining UAMM status information.)
To deactivate and reinitialize the UniAccess Fixed-gate, complete the following steps:
• Shut down all currently connected UACSs by using the UACS TERM UACS statement (see page 19-24 for information on terminating UACS).
• Deactivate the UniAccess Fixed-gate. This is accomplished by the SOLAR DEACT utility. After you have signed on with proper security clearance to accomplish this task, add the following runstream to deactivate the production Fixed-gate:
@ADD SYS$LIB$*UAUTIL.DEACTUAFG
• If you have made changes to the configuration file, you should execute UACF to check syntax and load the Fixed-gate (Steps 1 and 2 above). The ‘S’ and ‘A’ options may be combined to reduce the number of UACF executions.
• Initialize UAFG with the ‘I’ option on the UACF execution statement, as explained in Step 3 above.
• Start all UACSs.
In other words, reinitializing UAFG may require that steps 1 through 4 of the initial system execution (page 6-8) be completed again.
Release 10R3: October 31, 2005 7 Preparing for Client Users 7 Preparing for ODBC and Open Client Users
This chapter provides information that will be useful to system administrators who are preparing UniAccess System server environments (UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200) for ODBC and Open Client users. The first section provides a checklist of actions that should be taken by the system administrator. The second section presents a table of values that should be passed to users so that they can connect to UACS.
Topics Page
Client Preparation Checklist 7-1 Explanation of Actions in the Client Preparation 7-2 Checklist Value Table for Client Users 7-6
Client Preparation Checklist The following checklist assists system administrators in assembling the information needed by UniAccess client users and developers. You may enter values into the tables in the subsequent section, Value Table for Client Users, and distribute the tables to users. (Only items relevant to clients are covered in this chapter. Other UniAccess configuration options are available; see Chapter 16 for these options.)
Release 10R3: October 31, 2005 7-2 UniAccess for OS 2200 System Administration Guide
Table 7-1: Client Preparation Checklist
Action to be Taken Comments
Required Steps for All Clients 1. Provide users with an IP address/host name and Required. port for each UACS. 2. Verify that UAUSER entries exist for all users of Required, except when COMSRV the UniAccess System. Supply users with USEUAUSER is set to NO. assigned USERIDs and pertinent UAUSER statement parameter values. 3. Indicate which transaction services are available Required. Controlled by COMSRV and the default language transaction for each configuration parameters. UACS.
Site-Optional Steps For RDMS 2200/ODBC users. Required 4. Supply the user with the name of the RDMS if a pre-defined storage area has been storage area for creating tables. created for RDMS tables. 5. Ensure that RDMS meta database information is For RDMS 2200 users. maintained in the UREP repository. 6. Provide users with the name of the machine on For UADTC users. which the UADTC service is running, if it is not installed on the user’s PC. 7. Provide users with relational mappings of their For DMS 2200 users. DMS schema.
Explanation of Actions in the Client Preparation Checklist
The following discussion of the Client Preparation Checklist reviews several key administrative responsibilities in preparing the UniAccess environment. It also explains values that must be provided to client users.
Release 10R3: October 31, 2005 Preparing for ODBC and Open Client Users 7-3
1. Provide users with an IP address/host name and port for each UACS
Provide client users with the CMS 1100 INTERNET-ADR statement or the CPComm IP statement, or a host name, and the port (COMSRV LISTENPRT value), for each UACS to which a client application can connect (see page 5-8).
For ODBC clients, the IP address/host name and port are entered in the UADriver Setup dialog and are stored in the registry. Other clients and Microsoft SQL Servers store the IP address and port in their configuration files.
2. Verity UAUSER entries and supply users with configured values
Confirm that UAUSER configuration entries exist for all client users (unless the COMSRV USEUAUSER configuration parameter is set to NO).
You can record the userid (UAUSER USERID parameter) on Table 7-3. Note that the userid is case-sensitive. (For more information on defining UAUSER statements, see page 5-10.)
You should also review the UAUSER statement parameters and supply any pertinent settings or values to the user. You may record these values in Table 7-3 under Additional Site-Specific Values.
3. Indicate which transaction services are available and the default language transaction for each UACS
In configuring a UniAccess a data source, the ODBC client user must designate the service type (UARS, UAHS, or UASL) that will be used as well as the default language transaction to be used. The client’s choices for the transaction service(s) are dependent on the product keys configured in the OSPARM configuration statement (see Table 7-2). A single data source may access multiple services, but specifies a single language transaction as the default.
An administrator should inform ODBC users of the transaction services available to their client applications. Open Client users are limited to using the default language transaction (COMSRV DFLTTRAN value). All SQL requests issued by Open Client applications will be processed by the transaction configured there. Pre-9R1 UADriver users may select the default language transaction, but are limited to using the default services (COMSRV DFLTTRAN).
Release 10R3: October 31, 2005 7-4 UniAccess for OS 2200 System Administration Guide
Table 7-2: Transaction Service Options Available to ODBC Clients
OSPARM Config UADriver Setup UADriver Setup COMSRV Config Parameter Option: Services Option: Language Parameter Transaction
UARSPRODKEY UniAccess Relational UARS UARSTRAN Service UAHSPRODKEY UniAccess Hierarchical UAHS UAHSTRAN Service UASLPRODKEY UniAccess Server-Library User-Written Language USERTRAN Transaction UAINTRAN* No Language Transaction UAINTRAN* * If users will be allowed to use UADriver to connect to Server-Library transactions, that is, if users will be using UADriver without UARS or UAHS, then the UAINFO transaction must be installed. See page 4-14 for information on UAINFO installation.
4. Supply the user with the name of the RDMS storage area
When the user is authorized to issue CREATE TABLE commands to RDMS 2200, the system administrator may decide whether the tables should reside in a pre-defined storage area or RDMS should implicitly create a storage area for each table (the default). If you choose to create the RDMS storage area for newly created tables (see page 4-13), you must supply the client user with its name. If you choose to have RDMS implicitly create the storage area, there is no special configuration required of the client user.
The name of the storage area will be entered in the UARS Setup Options dialog of the UADriver data source configuration.
This item is only relevant for ODBC users access RDMS 2200.
Note Storage areas implicitly created by RDMS will not be deleted by a DROP TABLE command and must be manually deleted by the system administrator before another table with the same name can be created.
Release 10R3: October 31, 2005 Preparing for ODBC and Open Client Users 7-5
5. Ensure that RDMS meta-database information is maintained in the UREP repository
In order to support RDMS catalog procedure services, UARS requires meta-database information about RDMS objects. Occasionally, meta-database information may not be available about objects that were created prior to UARS installation. In these cases, the system administrator must manually update information in the UREP repository. An explanation of this situation and the procedures for updating UREP are found on page 4-14.
This item is only relevant to clients accessing RDMS 2200.
6. Provide users with the name of the machine on which the UADTC service is running
If your site is using UniAccess’ distributed transaction features and the UniAccess Distributed Transaction Coordinator (UADTC) is not running locally on the users’ PC, provide users with the name of the machine on which the UADTC service is running. The name of the machine will be entered in the Advanced Setup Options dialog of the UADriver data source configuration.
This item is only relevant to clients participating in distributed transactions.
7. Provide users with relational mappings of their DMS schema
In order to effectively use the UniAccess Hierarchical Service (UAHS) to access DMS data, users may need to know the names of UAHS databases and tables, and how they are defined, or mapped, from the DMS schema. An administrator can provide users with a listing of the database and table definition commands used to build the UAHS repository or produce a report using one of the TABLEDEF reporting options. (Chapter 14 covers UAHS, the Repository, and relational mapping in detail.)
This item is only relevant to clients accessing DMS 2200.
Release 10R3: October 31, 2005 7-6 UniAccess for OS 2200 System Administration Guide
Value Table for Client Users
Table 7-3 summarizes the information that should be provided to ODBC and Open Client users. Values correspond to the discussion in the preceding section, Client Preparation Checklist.
Table 7-3: Required Values for ODBC and Open Client Users
Requirements Values
Required UniAccess Values: 1. IP address/host name (by UACS) Port (by UACS) 2. User ID 3. Transaction services available to ODBC clients (by UACS) Default language transaction for non-ODBC clients (by UACS)
Site-Optional Values: 4. The name of the RDMS 2200 Storage Area if this option is to be filled 6. The name of the machine on which the UADTC service is running, if it is not installed on the user’s PC
Additional Site-Specific Values: 7. Relational mapping information
Release 10R3: October 31, 2005 III Advanced Procedures Part III ...... Advanced UniAccess Procedures
Chapter 8: Optimizing Performance
Chapter 9: Providing Security
Chapter 10: Returning Server Program Messages to Client Applications
8 Optimizing Performance 8 Optimizing Performance
To a large degree, the performance of your UniAccess System for OS 2200 depends on the non-UniAccess components you are using. Efficiency varies according to the following issues, discussed in this chapter:
Topics Page
UniAccess Communication Server Optimization 8-2 UniAccess Message Manager Optimization 8-2 Database Performance 8-4 Transaction Configuration and Design 8-6 Registering Transactions 8-6 UARS Performance 8-7 UAHS Performance 8-9 Server-Library Program Design 8-12 Host Performance 8-16 Processor Utilization 8-16 Memory Utilization — ClearPath IX, 2200/500, 8-16 and 2200/900 I/O Utilization 8-16
Release 10R3: October 31, 2005 8-2 UniAccess for OS 2200 System Administration Guide
UniAccess Communication Server Optimization The UniAccess Communication Server (UACS) handles all communications between client and server applications. Three parameters on the COMSRV configuration statement control the number of activities and their execution priorities.
The TIPQCNT and TSAMCNT parameters of the COMSRV statement control the number of activities that are initialized (see page 16-29). The TIPQCNT parameter controls the number of MMQ tasks that are started. This activity will process any UniAccess Message Manager output that is directed to the PIDs. The TSAMCNT parameter controls the number of activities available to handle inbound messages and to schedule transactions in a UniAccess System server environment (UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200).
Note In a high volume UniAccess environment, it is recommended that the TIPQCNT and TSAMCNT parameters each be configured to equal the number of processors.
The PRIORITY parameter of the COMSRV statement controls the real-time priority used by all UACS activities (see page 16-27). This parameter can be used to balance the processor priority of UACS if other real-time activities are negatively impacting UniAccess performance.
UniAccess Message Manager Optimization The UniAccess Message Manager (UAMM) provides message transfer capabilities between UniAccess library-based programs and one or more UACSs. UAMM manages a pool of memory blocks that are used to stage message buffers in transit. The UAMM configuration statement allows the system administrator to specify the size and number of memory blocks available to UAMM. The UAMM statement also allows the administrator to define the total number of connections UAMM will support and the maximum number of memory blocks a single connection can use. Table 8-1 lists the UAMM parameters and their purpose.
Release 10R3: October 31, 2005 Optimizing Performance 8-3
Table 8-1: UAMM Primary Storage Parameters
UAMM Parameter Purpose
BLOCKCNT Defines the total number of UAMM memory blocks to allocate. At least one block must be available for each active process slot. The valid range is 1 to 262143. Defaults to the PROCCNT value. BLOCKSIZE Defines the size in bytes of each UAMM memory block. This value limits the maximum size of a TDS buffer that can be requested by a client application. Valid values are 512, 1024, 2048, and 4096. Defaults to 512. MAXBLKS Defines the maximum number of memory blocks a single process can use before a TCP/IP suspend is sent to the remote peer requesting that it temporarily suspend transmission of additional data. (This only affects incoming data blocks.) The valid range is 1 to the BLOCKCNT value. Defaults to 10. PROCCNT Defines the total number of process slots system wide supported by UAMM. Usually, there is a one-to-one relationship between these process slots and the number of PIDs allocated to a UACS via the COMSRV PIDCNT and COMSRV PIDSTART statements. Defaults to the number of PIDs allocated among all COMSRVs. Up to 65000 process slots may be allocated.
A balance must exist between each of these parameters to ensure optimum system performance. The following list summarizes these balancing issues:
• At least one memory block must exist for each concurrently active process that UAMM will support. Allocated but inactive connections do not use any memory blocks.
• If a small number of concurrent connections will be transferring large volumes of data, the MAXBLKS parameter should be set to a large number. Conversely, if a large number of concurrent connections will be transferring small volumes of data, the MAXBLKS parameter should be set to a small number.
• The BLOCKSIZE value should be increased when clients capable of supporting larger block sizes are being used and when a large volume of data is being transferred. When clients that are not capable of using larger block sizes are being used, the BLOCKSIZE should be kept at its default value. If a mixture of clients are being used (some clients can support larger block sizes and some
Release 10R3: October 31, 2005 8-4 UniAccess for OS 2200 System Administration Guide
cannot) with a UniAccess environment where the BLOCKSIZE value has been increased from its default, memory will be under utilized by those clients that cannot support larger block sizes. The 8R1 and newer versions of the UniAccess ODBC Driver and the UniAccess Transaction Client can both be configured to use block sizes up to 4096 bytes.
• When large numbers of concurrent connections will be transferring large volumes of data, the value of the BLOCKCNT parameter should be increased.
• As a general rule, the MAXBLKS parameter should be set to the number of memory blocks divided by the total number of process slots (BLOCKCNT/ PROCCNT). If large numbers of throttles are being issued by UACS, performance can be improved by increasing the number of MAXBLKS. The number of throttles issued can be determined by executing the UACS STATUS SUMMARY console command (see page 19-10). The total amount of memory allocated to memory blocks can be calculated by multiplying the block size by the number of blocks (BLOCKSIZE * BLOCKCNT).
• When all is functioning correctly, there is a one-to-one relationship of PIDs to process slots. When an error occurs, however, the one-to-one relationship may be broken to ensure that an error can not result in an application getting erroneous data. The simplest case is terminating a COMSRV with active connections. Depending upon the state of processing for the active connection, the process slot may be lost. Database Performance Your database is the dominant factor in UniAccess System performance. You can effect minor improvements by making TIP, CMS 1100 and Telcon adjustments, but you will get the greatest return from optimizing the performance of your database. The following list summarizes ways you can utilize major features of OS 2200 Universal Data System (UDS) to optimize your database environment:
• Configure the value of MAX-THREADS to minimize queuing. Queuing can occur if the maximum number of threads is active, or if there are insufficient resources (i.e., buffer space in the page banks) to support all of the active threads.
Release 10R3: October 31, 2005 Optimizing Performance 8-5
• Size the UDS Thread Banks properly to avoid expansions.
• Configure Dedicated Page Banks and use the Large I/O feature to keep high usage data in memory, if possible.
• Configure internal UDS files (e.g., FDT$, system file, retention files, root-file) as TIP files.
• Use Dedicated Schema Banks for DMS 2200 schemas and subschemas.
• If you use multiple page sizes, dedicate files of the same size to page banks.
• Configure the maximum audit only recovery limit (MAXIMUM-AOR-UPDATES) to balance the utilization of page buffers versus I/O to the retention file.
• If you are using RDMS, review the section Improving Database Performance in the Unisys OS 2200 Relational Data Management System (RDMS 2200) Administration Guide.
• Review the section Monitoring Performance and Diagnosing Problems in the Unisys OS 2200 Universal Data System (UDS) Administration and Support Reference Manual.
• Configure storage areas as TIP files, or as Keep-Assigned.
• Use deferred updates, instead of quick looks.
• Use frequent commits to avoid use of the root-file.
Of course, when considering these and other performance enhancements, there are trade- offs. How best to configure these attributes can only be determined by the processing characteristics and performance goals at your site. For further information about the above parameters see the Unisys OS 2200 Universal Data System (UDS) Configuration Guide, Unisys OS 2200 Universal Data System (UDS) Administration and Support Reference Manual, and the Unisys Repository Manager (UREP) Administration Guide.
Release 10R3: October 31, 2005 8-6 UniAccess for OS 2200 System Administration Guide
Transaction Configuration and Design This section discusses considerations for optimizing TIP transactions within the UniAccess System for OS 2200, namely the UARS and UAHS transactions and all UASL transactions.
Registering Transactions
All Server-Library programs, including UARS and UAHS, are implemented as TIP transactions. TIP transactions must be registered with the operating system and placed in TIP files. The Unisys OS 2200 Universal Compiling System (UCS) Application Development Programming Guide and the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual describe the general requirements.
The following table describes UniAccess VALTAB requirements.
Table 8-2: VALTAB Requirements
Variable Explanation
Trans Code The code in the transaction code field must be unique with respect to all (ACT) other transaction codes. Audit Trail The audit trail number contains the audit trail number for the application (AUD) group. This number must match the application group number of the UACS that scheduled this transaction. Program Name The name of the absolute element copied to a program file. (NAM) Program Options Program Options define system capabilities for this program. (OPT) Recommended options are LMTZ. Program Type This number indicates the type of execution environment required for this (PRG) program. A ‘3’ indicates the program is reentrant. This is used with high performance transactions. This option will increase performance by decreasing load times. Recovery Options Recommended no recovery options (NONE). Data is passed via UAMM (REC) and not the MCB. Program Status These options define the status of this transaction program. An ‘I’ option (STA) allows the program to remain in main storage. When used with high performance transactions, this option will increase performance by decreasing load times. Options JLM must be specified for all transactions. Standard File This field contains a number indicating which TIP file contains the Selector Field transaction to be executed. TIP ZOOMs must be contained in SUPUR (STF) files. SUPUR files are indicated by a code of 0.
Release 10R3: October 31, 2005 Optimizing Performance 8-7
Note We recommend that UniAccess transactions be placed in SUPUR files.
UARS Performance
The UARS transaction is configured in much the same way as any other TIP transaction. The system administrator must ensure that the UARS transaction is properly configured to achieve its maximum performance level. The following sections explain considerations for configuring UARS.
VALTAB Settings
Table 8-3 suggests settings for the VALTAB entry to improve the performance of UARS transactions.
Table 8-3: VALTAB Settings Affecting UARS Performance
Variable Discussion
COP When UARS is installed, the maximum number of copies of UARS that can execute concurrently is set to two (COP,2 on the VALTAB parameter). If client applications are using manual commit or executing multiple long and complex SQL statements, the UARS transaction will likely be queued with this default value. When this occurs, to the end user, it can appear that UARS is in a hung condition. If this is occurring at your site, you may want to increase this value appropriately.
When configuring multiple language transactions—UARSTRAN2, UARSTRAN3, and/or UARSTRAN4 parameters of the COMSRV statement—the COP parameter for the initial language transactions must be set to 63 (see page 16-31). RUN When UARS is installed, the value for the estimated standard unit of processing (SUP) seconds is set to 4095 seconds. This value can be increased if your site is submitting complex SQL requests requiring more than 4095 SUP seconds, resulting in a time out condition. This is accomplished by setting the VALTAB option IND to X. With IND,X the maximum SUP time is in minutes instead of seconds. Since it is on the VALTAB, only the UARS transaction is affected. (Refer to PLE 16385506.)
Release 10R3: October 31, 2005 8-8 UniAccess for OS 2200 System Administration Guide
COMSRV UARSTRAN Parameters
The COMSRV UARSTRAN2, UARSTRAN3, and UARSTRAN4 options define language transactions in addition to the 63 allowed by the UARSTRAN parameter (see page 16-31). Together, these parameters allow up to 252 copies (4 language transactions set to the VALTAB limit of 63 copies) of the language transaction to run concurrently. Typically, these additional language transactions should be required only when large numbers of extended session requests are being processed by UARS and requests are being queued by the TIP scheduler.
RELSRV WAITTIME Parameter
Optimum performance can be obtained by reducing the number of loads of the UARS transaction. Loads can be reduced by configuring the UARS transaction to use the resident transaction program system (RTPS) or by setting the RELSRV WAITTIME parameter to a non-zero value. The RELSRV WAITTIME parameter in the UniAccess Configuration File indicates the time in seconds that the UARS transaction will wait for a request before terminating (see page 16-58).
If the RELSRV WAITTIME parameter is set to zero, the transaction will check for a queued input prior to terminating. This is the preferred configuration setting if you wish to make the UARS transaction resident (RTPS). For additional information on RTPS transactions please refer to the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual.
If the RELSRV WAITTIME parameter is set to a non-zero value, UARS simulates a resident transaction program by checking for input every 50 milliseconds. If an input is not received within the WAITTIME, the UARS transaction will terminate.
Note Some operating system levels will not allow the UARS transaction to retrieve multiple input messages. When this happens, the transaction will remain active for the RELSRV WAITTIME value after processing the input request. This may cause the transaction to appear hung. Please refer the READ.ME document shipped with UniAccess for the latest information on operating system dependencies.
Release 10R3: October 31, 2005 Optimizing Performance 8-9
Resident Transaction Program System (RTPS)
If your site executes a high volume of UARS transactions, you may want to consider configuring UARS to utilize the RTPS feature of TIP. RTPS can reduce system overhead by causing UARS to stick until explicitly unloaded. Please refer to the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual for additional information concerning RTPS.
When UARS is configured as a resident transaction, the RELSRV WAITTIME parameter should be set to zero (0). If RELSRV WAITTIME is not set to zero, an error may occur when the transaction is deactivated (TP D keyin).
UAHS Performance
As mentioned in the Database Performance section, the database is the dominant factor in UniAccess performance. Database performance for UAHS includes the relational view of the database, as well as the design of the DMS 2200 database and UDS sizing.
The UAHS transaction is configured in much the same way as any other TIP transaction. The system administrator must ensure that the UAHS transaction is properly configured to achieve maximum performance. The following sections explain considerations for configuring UAHS.
VALTAB Settings
Table 8-4 suggests settings for the VALTAB entry to improve the performance of UAHS transactions.
Table 8-4: VALTAB Settings Affecting UAHS Performance
Variable Discussion
COP When UAHS is installed, the maximum number of copies of UAHS that can execute concurrently is set to two (COP,2 on the VALTAB parameter). If client applications are issuing multiple requests that involve large record volumes or area searches, the UAHS transaction will likely be queued with this default value. When this occurs, to the end user, it can appear that UAHS is in a hung condition. If this is occurring at your site, you may want to increase this value appropriately.
Release 10R3: October 31, 2005 8-10 UniAccess for OS 2200 System Administration Guide
Variable Discussion
RUN When UAHS is installed, the value for the estimated standard unit of processing (SUP) seconds is set to 4095 seconds. This value can be increased if your site is submitting complex SQL requests requiring more than 4095 SUP seconds, resulting in a time out condition. This is accomplished by setting the VALTAB option IND to X. With IND,X the maximum SUP time is in minutes instead of seconds. Since it is on the VALTAB, only the UAHS transaction is affected. (Refer to PLE 16385506.)
UAHS Meta Database
The UAHS Meta Database contains information described the DMS schema and the mapping of relational tables to the underlying DMS structure. The UAHS Meta Database resides in a standard TIP FCSS user file. If a large percentage of the SQL requests handled by UAHS retrieve a small amount of data, access to this TIP file may have an impact on performance of the UAHS transaction. Some methods to improve access to the TIP file follow.
• Since records in the TIP file are hashed, increasing the size of the file may reduce the number of duplicates created (see Step 2. Estimate the Optimal TIP File Size, page 14-6).
• Creating the TIP file as a duplex file with one leg residing in memory and the second leg residing on local mass-storage may reduce the time required for I/O to the TIP file. See the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual for additional information.
• Creating the TIP file using XPC caching, if available, may reduce the time required for I/O to the TIP file. See the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual for additional information.
Table Definition (TABLEDEF)
The mapping of a relational table onto the hierarchical structure may significantly impact performance. When UAHS tables are created, one of the records in the set hierarchy must be designated the root of the table. UAHS allows either the topmost or bottommost record in the set structure to be used as the root record. The defined root record drives the retrieval process in two ways:
Release 10R3: October 31, 2005 Optimizing Performance 8-11
• If the search criteria cannot be used to access keyed DMS records, then the defined root record will be used as the starting point for retrieving DMS data (employing the AREASEARCH mechanism).
• If the WHERE clause is present and the search criteria specifies values for DMS keys in multiple records, the root record will be used to determine which key will be used as the starting point for retrieving DMS data.
For additional information, see page 14-21, Root Records.
AREASEARCH Parameter
Area searches allow UAHS to sequentially examine every record in a DMS area (or areas) in response to a client SELECT request. Area searches are employed by UAHS when DMS record key values are not available to limit the number of records that qualify for a selection.
The use of area searches should be limited because they can have a significant impact on the system. Area searches may result in UAHS retrieving every record in the DMS 2200 areas that contain the target DMS records associated with the tables.
Area searches are controlled by the AREASEARCH parameter on the UAUSER and HIERSRV configuration statements, and by UADriver setup and run-time options for the client. When area searches are necessary, specific users should be granted this capability on the UAUSER configuration statement to avoid careless use of the capability.
HIERSRV WAITTIME Parameter
Optimum performance can be obtained by reducing the number of loads of the UAHS transaction. Loads can be reduced by configuring the UAHS transaction to use the resident transaction program system (RTPS) or by setting the HIERSRV WAITTIME parameter to a non-zero value. The HIERSRV WAITTIME parameter in the UniAccess Configuration File indicates the time in seconds that the UARS transaction will wait for a request before terminating (see page 16-40).
If the HIERSRV WAITTIME parameter is set to zero, the transaction will check for a queued input prior to terminating. This is the preferred configuration setting if you wish to make the UAHS transaction resident (RTPS). For additional information on RTPS
Release 10R3: October 31, 2005 8-12 UniAccess for OS 2200 System Administration Guide
transactions please refer to the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual.
If the HIERSRV WAITTIME parameter is set to a non-zero value, UAHS simulates a resident transaction program by checking for input every 50 milliseconds. If an input is not received within the WAITTIME, the UAHS transaction will terminate.
Note Some operating system levels will not allow the UAHS transaction to retrieve multiple input messages. When this happens, the transaction will remain active for the HIERSRV WAITTIME value after processing the input request. This may cause the transaction to appear hung. Please refer the READ.ME document shipped with UniAccess for the latest information on operating system dependencies.
Resident Transaction Program System (RTPS)
If your site executes a high volume of UAHS transactions, you may want to consider configuring UAHS to utilize the RTPS feature of TIP. RTPS can reduce system overhead by causing UAHS to stick until explicitly unloaded. Please refer to the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual for additional information concerning RTPS.
When UAHS is configured as a resident transaction, the HIERSRV WAITTIME parameter should be set to zero (0). If HIERSRV WAITTIME is not set to zero, an error may occur when the transaction is deactivated (TP D keyin).
Server-Library Program Design
Build your Server-Library transactions to handle multiple requests. Multiple requests can be handled by self-initializing, re-entrant, RTPS, or HVTIP transactions.
Self-initializing transactions must ensure that all data values are set to the required initial value at program initiation. A copy of a self-initializing transaction in memory can be serially re-used. If multiple copies of the transaction are allowed, a self-initializing transaction in memory can be copied to create additional copies.
Release 10R3: October 31, 2005 Optimizing Performance 8-13
Reentrant transactions must meet the criteria for self-initializing transactions and can not modify the instruction bank. A single copy of a reentrant transaction instruction bank can be used simultaneously by multiple copies of the transaction. Each copy of a reentrant transaction will have its own data area.
RTPS (Resident Transaction Program System) transactions can reduce system overhead by causing the RTPS transaction to remain in memory (stick) until explicitly unloaded. In addition, an RTPS transaction is deactivated when it requests input and no input is available.
High performance Server-Library transactions can utilize RTPS without modification. However, Server-Library transactions designed to be executed as RTPS transactions should consider the following:
• The RTPS transaction will be deactivated by the operating system if an input message is not available when the TDACCEPT is performed.
• The RTPS transaction will only time-out when the transaction is being deleted from RTPS (TP D keyin). Therefore, the transaction should use a TDWAITTIME of zero, which will not cause the transaction to wait if a message is not available.
HVTIP transactions must meet the criteria for a reentrant transaction, utilize special library calls, and must use TIP memory. The following example demonstrates a technique for implementing multiple inital transactions.
Please see the Unisys OS 2200 Transaction Processing Programming Reference Manual and the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual for additional information on TIP program types.
Example: General Programming Sequence
The following is a general sequence for handling multiple initialization requests in a TIP transaction program. (For additional Server-Library programming sequences, see the section Transaction Types in Chapter 2 of the UniAccess for OS 2200 Server-Library Programming Reference.)
Release 10R3: October 31, 2005 8-14 UniAccess for OS 2200 System Administration Guide
Step one, program startup, is the recommended place to initialize the programs variables. The looping structure is demonstrated by steps three through nine. The Step Control BEGIN and END THREAD commands handle a single client request.
1. Start the program. Initialize program global variables.
2. Perform Server-Library function TDINIT to initialize your conversation with the client and receive the client login request.
3. Perform the Server-Library TDACCEPT function to receive the client RPC or language request.
If the return code is TDS-MCB-ERROR and the TDFHEIBLK TDSUBERROR field is set to 18, then there are no client requests to be processed. Go to step 10.
If you receive a return status indicating successful completion, then the accept function has received your client’s RPC or language request. Continue to step 4.
4. Initialize with the data manager (RDMS BEGIN THREAD and/or DMS IMPART).
5. Process the client request.
6. Terminate the connection to the data manager (RDMS END THREAD and/or DMS DEPART).
7. Perform the TDSNDDON function with the SEND-DONE-FINAL status set. This completes the conversation with the client and initializes the Server-Library structures and variables. 8. Initialize program variables.
9. Return to step 3.
10. Terminate the program. The TDFREE function must be the final Server-Library function performed.
Release 10R3: October 31, 2005 Optimizing Performance 8-15
Note In this example the data manager initialization and termination are part of the multiple execution loop. The data manager initialization must follow the TDACCEPT, which will cause the UniAccess Server to call the MCB to obtain the next request in the queue.
High performance transactions may be written using a single Integrated Recovery Step (i.e., data manager initialization and termination outside of the multiple execution loop). While this technique may improve performance, it also has disadvantages. The disadvantages are discussed in the UniAccess for OS 2200 Server-Library Programming Reference.
Additional Program Design Guidelines
The UniAccess System for OS 2200 supports all the transaction program types (self- destructive, self-initializing, reentrant, on-line-batch, HVTIP, and batch-connect), the resident transaction program system (RTPS) feature, and the use of TIP memory. TIP programmers may also use block transfer loading, program restart, and program sticking and reactivation techniques to improve performance.
One constraint for most of these program types and techniques is that the program cannot expand, contract, or create banks. The UniAccess System dynamically allocates and frees memory. However, this will not cause memory expansions or contractions as long as the URTS$TABLES is sufficient in size. URTS$TABLES is a UCS Runtime System data bank that maintains the storage management reserve as well as Runtime System tables, I/O buffers and packets, etc. UCS programs may set the size of the URTS$TABLES using the LINK processor to reserve space. For further information, consult the Unisys OS 2200 Transaction Processing Programming Reference Manual.
HVTIP programs and transactions that use TIP memory have restrictions if they use RDMS 2200. For further information, consult the Unisys OS 2200 Relational Data Management System (RDMS 2200) SQL Programming Reference Manual. Note Whether or not your system is TIP memory compatible is dependent upon the level of the operating system. For further information, consult the Unisys OS 2200 Transaction Processing Programming Reference Manual.
Release 10R3: October 31, 2005 8-16 UniAccess for OS 2200 System Administration Guide
Host Performance Optimizing the performance of your 2200 machine is a balance among processor, memory, I/O resources, your processing environment, and your site’s performance goals.
Processor Utilization
As a general rule, you should try to keep processor utilization below 85%. Long durations of high processor utilization rates typically indicate that the resource is being exhausted during peak periods. High processor utilization can cause additional system overhead, switching between tasks and assigning priorities.
I/O Utilization
I/O performance is critical to providing good system performance. I/O characteristics will vary widely based on equipment types. If multiple equipment types are available, high usage files should be placed on the fastest equipment. If only one equipment type is present, I/O should be evenly distributed across disks and subsystems. The proper distribution of files across mass-storage devices can increase system throughput significantly.
The following files can have a significant impact on performance: audit trail, TIP program files, retention files, and the TIP session file (if TIP session control is enabled).
Memory Utilization — ClearPath IX, 2200/500, and 2200/900
ClearPath IX, 2200/500, and 2200/900 systems provide a paged memory environment. Typically, memory utilization should not be an issue on these systems. If SIP data indicates that a large number of page faults are occurring, the amount of memory that is dynamically acquired by UniAccess may be a concern. This section will provide information to allow a site to fine tune the UniAccess memory utilization.
There are two aspects of UniAccess memory allocation and use that the system administrator should understand:
• UAFG Shared Memory — Memory that is stored in data banks shared between applications and multiple UACSs using a single install of UAFG (UniAccess Fixed-gate subsystem)
Release 10R3: October 31, 2005 Optimizing Performance 8-17
• UACS Exclusive Memory — Memory that is stored in data banks used exclusively by a single execution of UACS (UniAccess Communication Server).
UAFG Shared Memory
The UniAccess Fixed-gate subsystem (UAFG) contains all memory banks that are shared and accessible by common components and processes within the UniAccess system (see Figure 8-1). Some of these banks—e.g., UASL, and UACL—are static banks created by the LINK processor. (These static banks are not discussed here.) Other banks are created dynamically. These dynamic banks and their relationship to UniAccess Configuration File parameters are the topic of this section. (The static banks are not affected by configuration changes.)
The dynamic data banks fall into three categories: banks that are created when UAFG is initialized (UACF I option), banks that are modified when a portion of the UAFG is re-loaded (UACF L option), and banks that are created when a UACS starts. (See Table 8-5.)
Table 8-5: Creation and Modification of UAFG Data Banks*
Banks Created When Banks Modified When Banks Created for Each UAFG is Initialized UAFG is Reloaded UACS Started
UAMM set of banks RPCMAP bank MMQ bank — Management bank UAUSER bank — MMPROC bank General bank — MEMLIST bank — UAMM block banks RPCMAP bank UAUSER bank General bank * Banks listed in this table are described in the sections that follow the table.
Release 10R3: October 31, 2005 8-18 UniAccess for OS 2200 System Administration Guide
Figure 8-1 shows the banks that are contained within UAFG. UACL and UASL are the static banks which are not affected by configuration changes. UAMM and UADT are comprised of the dynamic banks which are affected by configuration changes, as well as static code. (For a view of UAFG within the overall UniAccess management system, see Figure 6-1 on page 6-4. For a description of UAMM and UADT, see page 1-21 ).
UniAccess Fixed-gate Shared Subsystem
UniAccessUniAccess UniAccessUniAccess Server-LibraryServer-Library Client-LibraryClient-Library (UASL)(UASL) (UASL)(UASL)
UniAccess Message Manager (UAMM)
MGMTMGMT Bank Bank
MMPROCMMPROC Bank Bank
MEMLISTMEMLIST Bank Bank
UAMMUAMM Block Block Bank(s Bank(s
MMQMMQ Bank(s) Bank(s)
UniAccess Data Manager (UADT)
GeneralGeneral Bank Bank
RPCMAPRPCMAP Bank Bank
UAUSERUAUSER Bank Bank
Figure 8-1: UniAccess Fixed-gate Data Banks
Release 10R3: October 31, 2005 Optimizing Performance 8-19
The following is a description of the dynamic data banks within UAFG, their contribution to system memory, and the UniAccess Configuration File statements and parameters that affect them.
UAMM Dynamic Banks With the exception of the MMQ bank(s), the UAMM dynamic banks are only created when UAFG is initialized (@UACF,I) and consists of:
Management (MGMT) bank Controls to access to all UAMM banks, allocation/release of UAMM blocks and all UACS connection control information.
This bank is normally quite small and does not contribute much to the use of system memory.
Common UAMM process control structure (MMPROC) bank Contains the MMPROC structures that are used as a vehicle to communicate between the UAFG and UACS. There is one MMPROC structure for each process defined by the UAMM PROCCNT parameter.
In a typical production configuration, this bank should not contribute significantly to the overall memory use.
MEMLIST bank Controls allocation and release of all UAMM blocks. (The maximum number of UAMM memory blocks allocated to a process is defined by the UAMM MAXBLKS parameter.)
This bank is normally quite small (2 words per UAMM Block) and does not contribute much to the use of system memory.
UAMM Block Bank(s) Contains reusable blocks that are used as the communications vehicle between the client and server programs. The UAMM BLOCKCNT and BLOCKSIZE parameters define the number and size of the blocks.
This bank is the major contributor to the use of system memory in a production UAFG environment. Therefore, due diligence is required when creating the UAMM parameters, i.e. the increased network speeds gained
Release 10R3: October 31, 2005 8-20 UniAccess for OS 2200 System Administration Guide
by increasing the value of BLOCKSIZE must be balanced against the potential negative effect of increasing in memory use.
MMQ Bank Contains the MMQITEM entries that are used for communications between the UAFG and a particular UACS. There is one MMQ bank for each active UACS; each MMQ entry consumes 6 words per configured UACS PID (COMSRV PIDCNT parameter). The MMQ bank is created during the startup of a UACS.
This bank is normally quite small and does not contribute much to the use of system memory.
UADT Dynamic Banks The UADT set of banks are created when UAFG is initialized (@UACF,I) and regenerated when the UAFG is reloaded (@UACF,L). The UADT set of banks consists of:
RPCMAP Bank Encapsulates all configured RPCs (RPCMAP records) in the UAFG. The use of memory associated with the RPCMAP bank is directly proportional to the number of RPCs configured; a single RPC entry consumes 12 words.
In a typical production configuration, this bank should not contribute significantly to the overall memory use.
UAUSER Bank Encapsulates all configured users (UAUSER records) in the UAFG. The use of memory associated with the UAUSER bank is directly proportional to the number of users configured; a single user entry consumes 37 words.
In a typical production configuration, this bank should not contribute significantly to the overall memory use.
General Bank Encapsulates all UAFG configuration parameters not captured in the above banks.
This bank should not contribute significantly to the overall memory use.
Release 10R3: October 31, 2005 Optimizing Performance 8-21
UACS Exclusive Memory
In addition to the one shared MMQ bank which UACS creates at startup time (see MMQ Bank above), UACS dynamically creates non-shared banks in the form of one TIPQ bank and one or more CSPROC banks during its initialization. These banks are private within UACS and are not shared, as is the case with the banks created in the UAFG.
TIPQ Bank Contains the UACS output routing queue entries. The size of this bank is directly proportional to the COMSRV TIPQSIZE parameter. Each TIPQ entry consumes 2 words. In addition to the TIPQ entries, the bank contains the CMS Registration packet plus some reserved words. The TIPQ bank is created during the startup of a UACS.
This bank is normally quite small and does not contribute much to the use of UACS system memory.
CSPROC Bank(s) Contains structures (CSPROCs) that control each PID configured for the UACS. The biggest segment of the CSPROC is the buffer allocated to perform the communications between UACS and CMS. The configurable buffer sizes are set by the UAMM BLOCKSIZE parameter and configurable values are 512, 1024, 2048 and 4096 bytes. The UACS buffer size is the same as the UAMM BLOCKSIZE value. Therefore, in order to maximize memory usage, the UAMM BLOCKSIZE value should match the client defined Packet Size configurable parameter (see Chapter 5 of the UniAccess for OS 2200 Client Guide). That is to say, memory will be wasted on the 2200 host if the UAMM BLOCKSIZE is set to 4096 bytes, but the client is only utilizing 512 bytes. The memory utilization goal should be to strike an acceptable balance between less time spent in client/ server communications and 2200 host memory usage.
Regardless of the client’s Packet Size value setting, the UACS CSPROC bank is created at UACS startup time and allocates memory based on the UAMM BLOCKSIZE value.
Release 10R3: October 31, 2005 8-22 UniAccess for OS 2200 System Administration Guide
UniAccess Dynamic Memory Bank Configuration Report
The UniAccess Dynamic Memory Bank Configuration Report displays the size of each portion of shared memory. The system administrator can use this report to fine tune the configuration when memory is a concern. The report is generated using the M option in the UACF execution statement (see page 17-4).
This reports takes the form illustrated below. The report processes the UniAccess configuration and highlights the UAFG bank profile and the COMSRV(s) bank profile.
@SYS$LIB$*UAUTIL.UACF,SM TPF$.CFGUACS,UNIACCESS*CONFIG. UniAccess Configuration Utility (UACF) v10R3-0 Processing siteinfo file [TPF$.CFGUACS]. Processing uainfo file [SYS$LIB$*UAUTIL.UNIACCESS/INC].
UNIACCESS Dynamic Bank Configuration Memory Requirements Report ======UAMM BLOCKCNT = 1000 UAMM BLOCKSIZE = 4096 Bytes UAMM PROCCNT = 65000
Fixed Gate Profile Start: ======UAMM BANKS Created by Initialization (@UACF,I) Words Allocated ======UAMM BLOCK Bank(s) 1024000 ======MEMLIST Bank 40000 ======MGMT Bank 20259 ======MMPROC Bank 580000 ======UADT BANKS Created by Initialization (@UACF,I) or Reload (@UACF,L) ======General Bank* 2700 ======RPCMAP Bank* 804 ======UAUSER Bank* 1406 ======BANKS Created by UACS Startup (@XQT UACS) ======MMQ Bank UACS 600 ======
Release 10R3: October 31, 2005 Optimizing Performance 8-23
MMQ Bank UACS02 600 ======MMQ Bank UACS03 1200 ======MMQ Bank UACS05 30 ======MMQ Bank UACS15 300 ======Banks Total Size 1671899 ======* Note that these banks although created by UAMM initialization are subject to dynamic change as the administrator redefines and reloads the components that make up these banks. Fixed Gate Profile End: ======
COMSRV Profiles Start ======BANKS Created by UACS Startup (@XQT UACS) Words Allocated ======CSPROC Bank(s) UACS 107760 ======TIPQ Bank UACS 8203 ======CSPROC Bank(s) UACS02 107616 ======TIPQ Bank UACS02 8203 ======CSPROC Bank(s) UACS03 215016 ======TIPQ Bank UACS03 8203 ======CSPROC Bank(s) UACS05 5586 ======TIPQ Bank UACS05 8203 ======CSPROC Bank(s) UACS15 54060 ======TIPQ Bank UACS15 8203 ======COMSRV Profiles End ======
Syntax check successful. UACF processing successful.
Release 10R3: October 31, 2005 8-24 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 9 Providing Security 9 Providing Security
This chapter explains how to use standard OS 2200 security facilities in conjunction with UniAccess System features to achieve security goals at your site.
Topics Page
Overview of UniAccess System Security 9-2 Component Security Responsibilities 9-3 Using UniAccess System Security Facilities 9-4 TIP Session Control 9-5 UniAccess Security API 9-6 Userid and Password 9-6 UAUSER Definitions 9-6 Co-existence With Unisys Security 9-8 Security Options 9-8 TIP Session Control 9-8 UACS Background Security Requirement 9-9 Console Privileges for UACS Commands 9-10
Release 10R3: October 31, 2005 9-2 UniAccess for OS 2200 System Administration Guide
Overview of UniAccess System Security When you plan security of the UniAccess System for OS 2200, you must consider security requirements at each client workstation, SQL Server, and OS 2200 host. Security planning for UniAccess System for OS 2200 must address the following issues:
• Client permissions. Does the client have permission to log into the network? Can the client’s login information be stored and passed along to the server to support the security systems in use there?
• SQL Server permissions. If the network includes one or more SQL Servers, which commands, data objects, stored procedures, and views does the user have permission to utilize?
• Host access permission. Does the user have permission to access the host?
• Host transaction permission. Does the user have permission to execute a given host transaction?
• Host data resource permission. Does the user have permission to access or modify the data in a particular file or database?
This chapter gives a brief overview of security at client workstations and at the SQL Server, but it primarily focuses on security procedures at the OS 2200 host. For information on client login and SQL Server security, refer to the basic SQL Server documentation set. You can find additional information about host security in the documentation provided with the OS 2200 System, your database, and any additional security products you are using.
Release 10R3: October 31, 2005 Providing Security 9-3
Component Security Responsibilities
Each component of the UniAccess System environment has its own responsibilities for security. This section summarizes the security responsibilities at each component.
At the Client Workstation
Most workstations have a secure login procedure that verifies the user’s identity and authorization by requiring a unique userid and password. A client’s user ID, password, and profile information can be passed to a SQL Server and to the UniAccess System.
At the SQL Server
A SQL Server can grant or deny a user permission to call a particular remote procedure. Requests routed through a SQL Server will undergo security checks.
At the UniAccess Transaction Client
The security attributes of the UniAccess Transaction Client are dependent upon the security configuration of the EXEC and the processing mode of the client application. If SECOPT1 is installed on the system, an Access Control Record on the file containing the UniAccess Fixed-gate (default name of SYS$LIB$*UAFG) can be used to control access to UniAccess Client-Library. Additionally, the client application must provide information to logon to the server.
At a UniAccess System Server
User validation for UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200 can be configured. The USEUAUSER parameter of the COMSRV statement controls user verification. If the parameter USEUAUSER is YES, the userid received from the client application must be configured in UADT using the UAUSER statement (see page 16-78).
When TIP session control is active, UACS will automatically respond to userid/password prompts issued by the EXEC using the userid and password received from the client application.
When the UniAccess Security API is utilized, UniAccess communicates with local or third- party security systems through a simple request and notification protocol. UniAccess requests a security system function. The security system notifies UniAccess with its response.
Release 10R3: October 31, 2005 9-4 UniAccess for OS 2200 System Administration Guide
Using UniAccess System Security Facilities The UniAccess System servers (UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200) provide additional security in several ways:
• They utilize TIP session control, if it is configured, to validate all user connections to the UniAccess System.
• With the optional UniAccess Security API in place, UACS interfaces with local or third-party security systems by initiating a logon transaction to validate security when a client makes a connection, and if configured, initiating a logoff transaction upon client disconnect (see Chapter 11).
• They can be configured to validate that all users connecting to the UniAccess System are defined in the UniAccess Data Manager (UADT) service. Therefore, you can restrict the use of UniAccess to a subset of the TIP users of the system.
• The UniAccess Transaction Server delivers the userid and password specified by the remote client application to the user-written Server-Library transaction.
• Custom security may be provided by the use of the user-written translation routines supported by the UniAccess languages services, UARS and UAHS. UAClientToHost and UAHostToClient are supported for the RDMS 2200 and DMS 2200 environments. (See Chapter 12 for information on these routines.)
• UniAccess Hierarchical Service mapping techniques may be used to prevent clients from accessing sensitive DMS data (see page 14-33). In addition, the Hierarchical Service supports several security options supplied by DMS 2200 (see page 14-34).
Release 10R3: October 31, 2005 Providing Security 9-5
TIP Session Control
When TIP session control is active, UACS will automatically respond to userid/password prompts issued by the EXEC using the userid and password received from the client application. For example:
> Enter your user-id/password: > [UACS responds with the user-id/password] > 1. AIS 2. APP1 3. APP2 ,1-3; > Enter your project-identifier (
If an invalid userid/password has been specified, the client logon request will be rejected and the connection will be terminated. If a valid userid/password has been specified, a TIP session is established. All subsequent requests from this client will be initiated using this TIP session.
Since UniAccess passes the user’s userid/password directly to the EXEC, the UniAccess System is in complete compliance with Unisys OS 2200 security. This allows the site to configure any of the security options and to utilize RDMS security.
Please see the Unisys OS 2200 Security Planning and Administration Reference Manual for additional information on OS 2200 security and the Unisys OS 2200 Relational Data Management System (RDMS 2200) Administration Guide for information on RDMS security.
Note When TIP session control is configured, UACS must establish a session with TIP session control using a message/response protocol. If customers make custom modifications to the operating system and modify the values required by UACS, they must enter the new values in the NEWPWDPRMPT, SYSTEMPRMPT, and/or UIDPWDPRMPT parameters of the OSPARM configuration statement. Otherwise, UACS will be unable to establish sessions under TIP session control.
Release 10R3: October 31, 2005 9-6 UniAccess for OS 2200 System Administration Guide
UniAccess Security API
Many sites have developed their own transaction security systems, due to the absence of native OS 2200 security for the transaction environment in past years. These systems normally query the user for an identifier and/or password and verify the existence of the identifier in a site defined database. The UniAccess System provides two methods of interfacing with these site security systems.
First, for the UniAccess System servers, it provides the UniAccess Security API. This allows the UniAccess System to communicate with local or third-party security systems through a simple request and notification protocol. The API utilizes logon, and optionally logoff and notification transactions to establish communication between the UniAccess System and the local security system. Chapter 11 describes the UniAccess Security API and explains how to configure it.
Second, for UniAccess Transaction Server, the UniAccess System provides userids and passwords to OS 2200 TIP transaction programs as described in the following section.
Userid and Password
All client applications must submit a userid and optional password to access a SQL Server or the UniAccess Transaction Server. The UniAccess Transaction Server delivers the userid and password to the user-written TIP transaction program after a successful call to the initialization function. The transaction program may then verify the existence of the userid and password in a site defined database if programmed to do so. For COBOL applications, the initialization call to TDINIT returns this information to the TDUSERID and TDPASSWD fields in the TDFHEIBLK area of COPYPROC SLCPCOB (see the UniAccess for OS 2200 Server-Library Programming Reference).
UAUSER Definitions
The UniAccess Data Manager (UADT) maintains a list of all users who are allowed access to the UniAccess System. These user definitions are utilized by UniAccess System components to validate all connection requests. If a user has not been defined, an error will be returned to the client application.
The userid within UADT is case sensitive; whereas, the EXEC userid (used for TIP session control) is not. This distinction can be used to allow the same EXEC userid to have
Release 10R3: October 31, 2005 Providing Security 9-7
different attributes when using UARS, based on the case of the userid submitted, as illustrated in the example below.
UAUSER USERID,demouser ; ACCESS,UPDATE ; RECOVERY,DEFERRED ; SCHEMA,UNIACCESS ; VERSON,PRODUCTION ; WORKSIZE,10000 ; COMSRV,UACS
UAUSER USERID,DEMOUSER ; ACCESS,READ ; RECOVERY,NONE ; SCHEMA,UNIACCESS ; VERSION,PRODUCTION ; WORKSIZE,10000 ; COMSRV,UACS
The ACCESS parameter of the UAUSER statement can be employed to restrict a user to retrieval-only dynamic SQL.
The set of user definitions maintained by UADT is created when the UADT service is initialized by the UACF processor. The information source of this definition set is the UniAccess Configuration File that is created by the UACF processor and is maintained by the system administrator. Each UAUSER statement in the UniAccess Configuration File defines a user. (See the UAUSER configuration statement on page 16-78 for a description of each parameter and information on maintaining the UniAccess Configuration File.)
Release 10R3: October 31, 2005 9-8 UniAccess for OS 2200 System Administration Guide
Co-existence With Unisys Security The UniAccess System co-exists with any of the Unisys Security Options and with or without TIP session control. The following sections describe considerations for various security configuration options.
Security Options
The UniAccess System will function in any of the four Unisys security environments: Fundamental, SECOPT1, SECOPT2, or SECOPT3. The UniAccess System does not impose any special constraints upon the security environment. However, the following items should be considered when installing the UniAccess System into an environment using SECOPT1, SECOPT2, or SECOPT3.
• All valid users of the UniAccess System should have a minimum of execute access to the file containing the fixed-gate. The production mode (Mode A or B) file name of the fixed-gate is SYS$LIB$*UAFG.
• The object module file should be private and does not need an ACR. The production mode (Mode A or B) name of the file containing the object modules is SYS$LIB$*UAOM.
• All database files, including the UDS internal files, should be at the same clearance level, if clearance levels are utilized.
TIP Session Control
When you configure TIP session control, you must configure the number of sessions for each application group in which UACS will be operating. The EXEC parameter STEP CONTROL NUMBER OF CONCURRENT SESSIONS defines the maximum number of concurrent TIP sessions that can exist for a single application group. This number must be large enough for UACS to establish a session for each PID (UniAccess COMSRV PIDSTART and COMSRV PIDCNT parameters) that is assigned to it.
If you will be utilizing non-UniAccess transactions, as well as UniAccess transactions within an application group, the number of concurrent sessions must be large enough to allow UACS to establish a session for each PID while the non-UniAccess transactions are active.
Release 10R3: October 31, 2005 Providing Security 9-9
When TIP session control is in use, the UniAccess APPINF configuration statement must specify an APPNAME value that matches the EXEC application name and not an alias.
UniAccess System users should be assigned userids, the same as any other TIP user. The userid can be created using SIMAN. The remote client will build the logon packet containing the userid and the password. The UniAccess System will utilize defaults for any other field requested. Therefore, the userid should be created with valid default values.
If the EXEC solicits for a new password during the sign-on process, the client application will receive notification, and the login request will fail. Upon notification, users should change their password at login with oldpw/newpw in the password field.
(You can find general instructions for configuring the EXEC in the Unisys OS 2200 EXEC System Software Installation and Configuration Guide.)
UACS Background Security Requirement
UACS requires specific privileges when it operates in a Security Option 1, or higher, environment. The privileges specified in this section assume that the site has not added to the set of secured privileges and Executive Requests (ER’s).
Privileges. UACS does not use any privileges from the set of privileges always enforced. The only privilege UACS uses from the set of privileges initially enforced is COM$PRV (SSCONSOLE).
Executive Requests. UACS does not use any executive requests (ERs) from the set of ERs that the system always enforces. The only ER used from the list of ERs that are initially enforced is PB$CON. UACS uses the following ERs from the list of ERs that the system potentially enforces:
ER Explanation
CMS$REG Register with the EXEC as a CMS RT$PID Associate a CMS number with a PID TIP$SM Open and close TIP sessions TIP$TALK Relay messages for TIP session control
Release 10R3: October 31, 2005 9-10 UniAccess for OS 2200 System Administration Guide
The userid that is used to start the background run must also have the QUOTA privilege to allow real-time execution. (For more information in executive requests, see the Unisys OS 2200 Security Planning and Administration Reference Manual.)
Console Privileges for UACS Commands
UACS unsolicited keyins verify the console mode of the userid submitting the console request. The following table maps the UACS unsolicited commands with the required console mode.
Table 9-1: Privileges for UACS Console Commands
Command Short Command Console Mode
HELP ? FULL LANGUAGE LOFF, LON, LC FULL STATUS SS, SA, SE, SP, SR, SU FULL TERM TU, TP RESPONSE TRACE TOFF, TL, TM, TH, TC FULL UAMM US FULL
Note A userid can be given response console mode without being allowed to respond to any message groups. However, the UACS background run will issue a message requiring response as part of the termination sequence. (The message is part of the SYSMSG message group, if the default EXEC groups have not been modified.)
Release 10R3: October 31, 2005 10 Returning Messages 10 Returning Server Program Messages to Client Applications
This chapter explains how UniAccess System for OS 2200 handles server program messages and what features are available to customize message handling.
Topics Page
Server Program Message Overview 10-1 Message Handling in the UniAccess System 10-2 Messages Generated by UniAccess System 10-3 Components Messages Generated by User-written Transactions 10-5 Map and Message Definitions 10-5 Map Definitions 10-5 Message Definitions 10-7 Server-Library Message Definitions 10-8
Server Program Message Overview The UniAccess server components provide the client with all available information to resolve a problem. UniAccess servers—UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200—return server program messages to the client application. (These message do not include those returned by UniAccess Transaction Client.) Server program messages may be error, informational, or warning messages. The system administrator can change the text of these messages, add messages, and modify the UADT record that maps RDMS 2200 errors to their SQL Server equivalents.
Release 10R3: October 31, 2005 10-2 UniAccess for OS 2200 System Administration Guide
Note SQL Server error messages may vary based upon the type of SQL Server and level. UniAccess provides a mechanism for mapping RDMS errors to SQL Server errors. This method is described in this chapter and can be used to ensure a correct mapping with the type and level of SQL Server in use.
The presentation of the error message is dependent upon the interface being used by the client application.
• Client applications using the Open Client interface will receive error messages in the same format as a SQL Server presents error messages.
• Client applications using the UniAccess ODBC Driver (UADriver) will receive messages using the SQLError interface, as defined in the ODBC specification.
Note UADriver handles setting the return code and conversion of server messages to SqlState. In some instances, warning messages will have a return code of SQL_SUCCESS_WITH_INFO. The native error code (pfNativeError) will be MESSAGE-NUMBER, described below.
This chapter explains how program messages are handled by the UniAccess System and what features are available to system administrators to customize message handling to their particular sites. A complete list of server program messages generated by the UniAccess System begins in Appendix D on page D-69.
Message Handling in the UniAccess System
If the UniAccess System detects a problem, it returns a message to the client. Messages that are returned to the client fall into these categories:
• Problems in the client request (for example, language syntax errors)
• Problems in the user-written TIP transaction (for example, syntax errors and errors in using Server-Library functions)
Release 10R3: October 31, 2005 Returning Server Program Messages to Client Applications 10-3
• Errors returned from the host database (for example, security violations, table specification errors, or I/O errors)
• Information related to connections, protocol violations, permission problems, and non-existent transaction names, which are returned by UACS.
These message types are handled by the UniAccess System in one of two ways.
• Messages generated by a UniAccess System server component are returned automatically to the client application. These messages are pre-defined in the UA Information File.
• Messages generated by a user-written transaction may be returned to the client application if the transaction is programmed to do so.
The following sections discuss these methods of message handling.
Messages Generated by UniAccess System Components
Messages generated by a UniAccess System server component such as UACS, UARS, or UAHS are returned automatically to the client application. The text of each message indicates its source. These messages look to the client like messages returned by a SQL Server.
These UniAccess System messages are defined in the UniAccess Configuration File and maintained by UADT. The section of this chapter entitled Map and Message Definitions explains how these messages are handled by the UniAccess System and how they may be modified by the system administrator.
Messages Generated by UACS
Messages concerning connection or permission problems are returned by UACS. When UACS detects problems in the connection sequence, the request sequence, or the transaction, it returns to the client the appropriate messages from among those maintained in the UniAccess Configuration File.
For example, an ODBC client would receive the following error notification after attempting to call a non-existent transaction.
Release 10R3: October 31, 2005 10-4 UniAccess for OS 2200 System Administration Guide
szSqlState = "S1000" *pfNativeError = 33811 *pcbErrorMsg = 92 szErrorMsg="[AIS][UniAccess ODBC Driver][UACS] UACS error: Undefined transaction (notxn ) (400000000035)"
Messages Generated by UARS
With the UniAccess Relational Service, messages from RDMS 2200 and Server-Library are processed and returned to the client by the UARS transaction. No additional programming is required. UARS attempts to translate RDMS 2200 errors into SQL Server equivalents using the UAMMAP statements in the UniAccess Configuration File. In most instances, RDMS 2200 errors are returned with their own text appended to a generic UARS error.
For example, an ODBC client would receive the following error notification after attempting to call a non-existent table.
szSqlState = "S0002" *pfNativeError = 208 *pcbErrorMsg = 142 szErrorMsg="[AIS][UniAccess ODBC Driver][UACS] Invalid object name (RDMS: [6006] APP 1 RDM EX 26040 Table or View UASAMPLE.NON_ESISTENT_TABLE undefined.)"
Messages Generated by UACS
With the UniAccess Hierarchical Service, messages from DMS 2200 and Server-Library are processed and returned to the client by the UAHS transaction. No additional programming is required.
For example, an ODBC client would receive the following error notification after attempting to call a non-existent database.
szSqlState = "S1000" *pfNativeError = 30002 *pcbErrorMsg = 97 szErrorMsg="[AIS][UniAccess ODBC Driver][UACS] UA service DMS error (11 - Invalid SQL database name [UASAMP])"
Release 10R3: October 31, 2005 Returning Server Program Messages to Client Applications 10-5
Messages Generated by User-written Transactions
Messages generated by a user-written Server-Library transaction may be returned to the client if the transaction is programmed to do so. A Server-Library transaction may receive error information from the UniAccess Server-Library function it calls or from the host resource being accessed. It can be programmed to format a message and to return it to the client application.
Errors detected by user-written transactions are returned to the client in the form designated by the transaction itself. The transaction programmer uses the Server-Library function TDSNDMSG to send an error message directly to the client. The section of this chapter entitled Server-Library Message Definitions describes the format of these messages.
The following is an example of a transaction error returned to an ODBC client.
szSqlState = "S1000" *pfNativeError = 40000 *pcbErrorMsg = 87 szErrorMsg="[AIS][UniAccess ODBC Driver][UACS] APPL Error: Incorrect number of parameters received"
Map and Message Definitions Messages returned by UniAccess System components are defined in the UniAccess Configuration File’s map and message records. These messages have already been defined by AIS in the UA Information File; however, the system administrator may modify or add to the map records and may modify the message records by using the UAMMAP and UAMESG configuration statements.
Map Definitions
UniAccess Relational Service maps RDMS 2200 errors to their SQL Server equivalents whenever possible. UADT within the UniAccess Fixed-gate maintains a cross-walk table to facilitate this mapping. Mapping records are loaded into UADT by the UACF processor from the UniAccess Configuration File. UADT maintains this information as the UAMMAP record.
Release 10R3: October 31, 2005 10-6 UniAccess for OS 2200 System Administration Guide
UAMMAP data also contains detailed information about each message. It contains the RDMS 2200 error code, map flag, SQL Server error code, severity, state, and fatality indicator for messages. (See the UniAccess configuration statement UAMMAP on page 16-73 for a definition of each of these fields.) The UAMMAP record also contains the severity, state, and fatality indicators for UNIACCESS-specific errors in the range from 30000-34000. The MAPCODE code will be ignored for these messages.
Note Applications using UADriver will see the equivalent SQL Server error code as the “native error code” (pfNativeError).
Changing Mappings
You can change any of the map records in UADT or add new map records using the UAMMAP configuration statement. You should be aware of the following guidelines and options for changes:
Guidelines
• As a general rule, you can make any changes you like to mappings, severity and/ or state. Normally, the fatality indicator should not be modified. These changes should be made to the UA Information File.
• You can add new mappings to translate additional RDMS 2200 errors to their SQL Server equivalents. These additions should be made to the Site Information File.
Permitted Changes
• You can modify and/or add mappings for RDMS 2200 errors. This is particularly useful when new RDMS 2200 errors are encountered that can be translated logically to SQL Server equivalents.
• You can map multiple RDMS 2200 errors to a single SQL Server error. Each one of these mapped errors can have a different severity, state, and/or fatality indicator.
Release 10R3: October 31, 2005 Returning Server Program Messages to Client Applications 10-7
Message Definitions
UADT maintains a list of messages returned to the client by RDMS 2200, DMS 2200, and the various components of the UniAccess Transaction Server or the UniAccess ODBC Servers. These program messages are retrieved from the UniAccess Configuration File generated by the UACF processor. This file contains the message number and the actual text for each message (see the UniAccess configuration statement UAMESG on page 16-68).
A typical entry looks like this:
32000, UARS Library Error (%s returned %s)
where the first two %s fields are used to return run-time information in the message.
Changing Messages
You can change the text of an AIS-written message or add new messages using the UAMESG configuration statement. The list of program messages currently generated by the UniAccess System begins on page D-69.
Guidelines
• As a general rule, you can make any changes you like to message text, severity, and/or state, but you cannot change message numbers. The numbers are used internally as keys by UniAccess components. Changes to existing messages should be made in the UA Information File.
• You can create new messages, particularly for mapping RDMS 2200 error messages. To assign a message number, refer to the MESSAGE-NUMBER definition in the following section, Server-Library Message Definitions. New messages should be added the Site Information File.
Permitted Changes
• You can modify the text of a message, replacing it with any string up to 255 characters in length. However, the variables (the % fields) must not be removed or reordered.
Release 10R3: October 31, 2005 10-8 UniAccess for OS 2200 System Administration Guide
Server-Library Message Definitions Messages generated by user-written Server-Library transactions are returned to the client by the TDSNDMSG function. The format of these messages is described below. For a complete description of TDSNDMSG, see the UniAccess for OS 2200 Server-Library Programming Reference.
Client applications are accustomed to receiving error messages from SQL Servers. They are familiar with the severity level and numbering systems used by the SQL Server error handler. The UniAccess Server-Library TDSNDMSG function allows you to return messages in a form the client is familiar with. TDSNDMSG uses the following parameters to return error information:
MESSAGE-TYPE Message type indicator. Indicates whether the message is an informational or an error message.
MESSAGE-NUMBER The unique number that identifies the message. The following conventions are observed:
00001-10000 SQL Servers use numbers between 1 and 10,000 for their error messages. For the client’s convenience, you should use the same number used by the SQL Server when you return a similar error to a client of a SQL Server. SQL Server errors are listed in your SQL Server documentation set.
20000-29999 These numbers are not currently in use.
30000-39999 Errors returned by a UniAccess System server. The list of these errors begins on page D-69.
SEVERITY The severity of the message. This is a number indicating the kind of problem encountered. Each SQL Server error has a severity level. The list of SQL Server errors in the SQL Server documentation indicates the severity level of each error. By referring to this list, you can assign the same level to corresponding errors.
Release 10R3: October 31, 2005 Returning Server Program Messages to Client Applications 10-9
The following conventions are observed to indicate the level of severity:
01-10 Status information. Messages with these levels are informational, not error messages.
11-16 Client application errors, such as datatype errors, syntax errors, or permission errors.
17-18 Non-fatal software or hardware errors, such as insufficient space or an attempt to open more than the maximum allotted number of connections.
19-24 Fatal system errors, such as database integrity problems or serious bugs. A fatal error ends the conversation.
ERROR-STATE This number provides additional information about the context of the error for technical support.
LINE-ID The identifier that marks the line number or area of the client program where the error was detected. You can use this parameter to return additional error information to the client.
TRANSACTION-NAME The name of the transaction that is currently executing. It identifies the application that is issuing the error message.
TRANSACTION-NAME-LENGTH The length of the TRANSACTION-NAME.
MESSAGE-TEXT The actual text of the message.
MESSAGE-LENGTH The length of the MESSAGE-TEXT.
Release 10R3: October 31, 2005 10-10 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 IV Special Features Part IV ...... Special UniAccess Features
Chapter 11: UniAccess Security API
Chapter 12: UniAccess Language Service Translation Routines
Chapter 13: Interactive SQL Parser
Chapter 14: UniAccess Hierarchical Service
Chapter 15: UniAccess Distributed Transaction Coordinator
11 Security API 11 UniAccess Security API
This chapter explains how to configure the UniAccess Security API to allow the UniAccess System to communicate with local or third-party security systems.
Topics Page
Overview of the UniAccess Security API 11-2 Security Transactions 11-4 UniAccess Security API Message Formats 11-5 Request Messages 11-5 Notification Messages 11-7 UniAccess Security API Configuration 11-10 UniAccess Sample Security Programs 11-10
Release 10R3: October 31, 2005 11-2 UniAccess for OS 2200 System Administration Guide
Overview of the UniAccess Security API The UniAccess Security API allows the UniAccess System to communicate with local or third-party security systems through a simple request and notification protocol. The UniAccess Communication Server (UACS) requests a security system function; the security system notifies UACS with its response. The system administrator must register and configure the transactions that will interface with the UniAccess Security API.
When the UniAccess Security API is configured, the UniAccess System may send and receive the following types of messages (see Figure 11-1):
• Logon request message. When UACS receives a user connection, it builds a request message containing logon information and routes it to the security logon transaction. The security system must notify UACS with a pass/ fail type message. If the security system indicates a pass status, the connection is allowed, otherwise the connection is terminated.
• Logoff request message. When UACS receives a disconnect request, it builds a request message containing logoff information and routes to the security logoff transaction. The security system must respond to a logoff request with a logoff completed message. Upon receipt of the logoff response, UACS will terminate the client.
• Notification message. UACS accepts unsolicited notification messages, that is, responses given without a request being made. Two unsolicited notification messages are currently defined. The defined messages are for session time-outs and illegal transaction requests denied for security reasons.
Release 10R3: October 31, 2005 UniAccess Security API 11-3
logon request message Logon Transaction pass/fail message
Local UACS Security System notification message
completed message Logoff Transaction logoff request message
Figure 11-1: UniAccess Security API Activities
Note The UniAccess Security API does not inhibit any function of TIP session control nor does it require implementation of any additional security measures.
Release 10R3: October 31, 2005 11-4 UniAccess for OS 2200 System Administration Guide
Security Transactions The UniAccess System and security applications communicate through three basic interfaces—logon, logoff, and notification. Local or third-party security utilizes a transaction to support logon functionality and, optionally, a transaction to support logoff functionality. The system administrator is responsible for registering and configuring these transactions.
Logon Transaction. The logon interface is used when a client application establishes a connection with UACS. UACS passes the userid, password, and PID to a designated logon transaction. The logon transaction is responsible for returning a pass/fail notification packet to UACS. If UACS receives a pass status, the client connection is permitted and a successful logon acknowledgment is returned. Otherwise, the connection is rejected and a negative acknowledgment is returned to the client.
Local security logon is indicated in the UniAccess Configuration File by the COMSRV LOGONTRAN parameter that specifies the logon transaction.
If both TIP session control and local security are configured, UACS first opens a session with TIP session control, logs into the TIP environment, and then executes the designated logon transaction.
Logoff Transaction. The logoff interface is used when a client application disconnects from UACS. UACS passes the userid and PID to a designated logoff transaction. The logoff interface is provided as a means of notifying the security system that the client has disconnected.
The logoff transaction must reply with a logoff completed message. Once received, UACS will complete the client termination and release resources dedicated to the connection. The TIP session will also be terminated at this time, if configured. If a reply is not received, UACS resources will remain committed until UACS is shutdown and restarted.
Local security logoff is indicated in the UniAccess Configuration file by the COMSRV LOGOFFTRAN parameter that specifies the logoff transaction.
If both TIP session control and local security are configured, UACS schedules the logoff transaction prior to terminating the TIP session. The local security package should not terminate the session.
Release 10R3: October 31, 2005 UniAccess Security API 11-5
UniAccess Security API Message Formats To facilitate the request and notification communication, UACS and the security transactions use the following MCB message structures to communicate.
Request Messages
UACS uses the request message in the logon and logoff interfaces to pass a message to the logon or logoff transaction. The message describes the userid, password, PID, and client IP address. The userid and password are obtained from the logon packet received from the client application. The PID is the UACS assigned PID. The IP address is the network address of the machine on which the client application is executing.
Message Format
Type Length Value
char 30 user id char 30 password char 6 PID char 15 IP address char 175 filler
Message Definitions
C language message definition:
/* VAR Request Packet */ typedef struct { char vr_userid[30]; char vr_passwd[30]; char vr_pid[6]; char vr_ipaddr[15]; char filler[175]; } VAR_REQ_PKT;
Release 10R3: October 31, 2005 11-6 UniAccess for OS 2200 System Administration Guide
COBOL language message definition:
* Request message 01VAR-REQ-PKT 05 VR-USERID PIC X(30). 05 VR-PASSWD PIC X(30). 05 VR-PID PIC X(6). 05 VR-IPADDR PIC X(15). 05 FILLER PIC X(175).
Message Packet Format
The userid and password fields of the request and notification messages are left justified and space filled. The PID of the request message and notification messages are right justified and zero filled. The IP address of the request message is left justified and space filled in nnn.nnn.nnn.nnn notation where nnn ranges from 1 to 255.
The character constant “~VS~” in the notification message is used to discern security packets from erroneous MCB output message packets. For example, a connection request with a userid of “bill”, a password of “123”, a PID of 7896, and an IP address of 192.168.1.1 would be passed to the logon transaction as:
00000000010000000002000000000300000000040000000005000000000600000000070000000008 12345678901234567890123456789012345678901234567890123456789012345678901234567890 bill 123 007896192.168.1.1
If TIP session control is active, the password will always be a 30-byte string filled with asterisks (*). For example the information from the above connection request would be passed to the logon transaction as:
00000000010000000002000000000300000000040000000005000000000600000000070000000008 12345678901234567890123456789012345678901234567890123456789012345678901234567890 bill *******************************007896192.168.1.1
If UACS fails to schedule the logon transaction for any reason, the client connection will be negatively acknowledged and the connection will be terminated.
Release 10R3: October 31, 2005 UniAccess Security API 11-7
Note UniAccess places no restrictions on the content of userids and passwords received from client applications, other than that they must specify valid UniAccess userids (if UniAccess userid validation is configured), and they must specify valid OS 2200 userids/passwords if TIP Session control is configured. This means the userid and password fields can be used for whatever purpose the local security package chooses. For example, the password field could contain an old password and a new password to support the capability of changing a password from a client workstation. The format of the change request is completely defined by the local security application.
Notification Messages
The security system uses the notification message to respond to UACS requests and to initiate unsolicited communication with UACS. A notification message contains a 4-byte literal string of “~VS~”, a 2-byte response indicator and a 30-byte, left-justified, space- padded userid, and an optional 112-byte comment to be recorded in the UACS trace file. The security system uses the 2-byte response field to indicate the type of notification.
Message Format
Type Length Value
char 4 ~VS~ char 2 response char 30 user id char 112 comment (an optional message to be included in the UACS Trace File)
Release 10R3: October 31, 2005 11-8 UniAccess for OS 2200 System Administration Guide
Message Definitions
C Language message definition:
/* VAR Notification Packet */ typedef struct { char vn_code[4]; char vn_fn[2]; char vn_userid[30]; char vn_comment[112] } VAR_NOTIF_PKT;
COBOL language message definition:
* Notification message 01VAR-REQ-PKT 05 VN-CODE PIC X(4). 05 VN-FN PIC X(2). 05 VN-USERID PIC X(30). 05 VN-COMMENT PIC X(112).
Response Types
Valid response types are as follows:
Response Type Description
1 logon accepted 2 logon denied, invalid userid or password 3 logon denied, the password has expired 4 transaction request denied 5 user session time-out 6 logoff completed
Response types 1, 2, and 3 represent valid responses for a logon request. Type 1 indicates that the logon transaction accepts the logon request. This causes UACS to positively acknowledge the connection request. Type 2 indicates that the logon transaction denies the logon request because an invalid userid or password is specified. This causes UACS to negatively acknowledge the connection request with message 4002 and to terminate the connection. Type 3 indicates that the logon transaction denies the logon
Release 10R3: October 31, 2005 UniAccess Security API 11-9
request because an expired password is specified. This causes UACS to negatively acknowledge the connection request with message 4022 and to terminate the connection. If the userid of “bill” is being accepted, the notification packet would appear as follows:
023456789112345678921234567893123456 023456789012345678901234567890123456 ~VS~01bill
Response types 4 and 5 represent unsolicited notification messages. Type 4 is for transaction security rejections and type 5 is for session time-outs. The local security application is responsible for determining the transaction being accessed, timing user inactive periods, and generating these responses.
For example, if the transaction requested by the userid of “bill” is being rejected by the security system, the security system would generate the following message:
023456789112345678921234567893123456 023456789012345678901234567890123456 ~VS~04bill
If UACS receives a type 4 notification message, it returns an error message 262 to the client. The client connection will remain open. If a type 5 notification message is received by UACS, the network connection is terminated and no attempt is made to notify the client.
UACS handles notification of local security system time-outs the same way it handles TIP session control time-outs—by immediately aborting the connection with the client application.
Note A logoff transaction must be defined if the local security system will be issuing any unsolicited messages such as the time-out notification message.
Response type 6 is the valid response to a logoff notification message. The logoff transaction must respond to a logoff request with this response type to ensure that UACS resources (PID) are released and, if configured, that TIP session control is terminated for this connection.
Release 10R3: October 31, 2005 11-10 UniAccess for OS 2200 System Administration Guide
UniAccess Security API Configuration The UniAccess Security API is configured using parameters of the COMSRV configuration statement. The parameters LOGONTRAN and LOGOFFTRAN contain the names of the logon and logoff security transactions. (For a description of these parameters, see page 16-24.) If these parameters are not defined, the UniAccess Security API is disabled.
A logoff transaction must be defined if the security system will send unsolicited notifications. For example, it is required if the security system will generate notification of a user session time-out condition. UACS uses the logoff interface to inform the security system that the user session has been terminated and that no further notification messages should be sent for this PID.
A logoff transaction must be defined if the security system needs to delay the release of UACS resources until its own logoff processing is complete: if, for example, the security system uses the PID reported by UACS to control the number of simultaneous logons of a user. By defining a logoff transaction, the security system forces UACS to retain these resources until a logoff completed response is received.
If configured, the security system’s logon and logoff transaction will be executed every time a user connects and disconnects from UACS, therefore these programs should be optimized for speed. The developer should evaluate the performance features provided by the transaction system such as self-initializing, re-entrant, and program sticking attributes.
UniAccess Sample Security Programs UniAccess System includes two security programs. The SECON program handles the logon request. The SECOFF program handles the logoff request. The programs are provided in both C and COBOL. The sample security programs are located in the OS 2200 file SYS$LIB$*UASAMP (or SYS$LIB$*UASAMPT for test mode installations). The transaction code and the name of the element where the source program resides are as follows:
Transaction Code UCS C Element Name UCS COBOL Element Name
SECON SECON/C SECON/UCOB SECOFF SECOFF/C SECOFF/UCOB
Release 10R3: October 31, 2005 UniAccess Security API 11-11
SECON. This program performs the logon functions required by the security interface. For simplicity, it also performs the functions most probably handled by the security system. The SECON program performs three functions: read the logon request packet, verify the userid and password, and notify UACS with the logon result.
• To read the logon request, the SECON program must initialize with MCB and retrieve the logon request message. The MCB packet must allocate a full size, 59 word user parameter area (UPA). UACS writes MCB packets with the full 59 UPA.
• Next, SECON verifies the userid and password. This sample program uses a simple hard-coded table of userids and passwords.
• Finally, SECON notifies UACS with a response to the logon request. For this, SECON builds a notification packet, VAR_NOTIF_PKT, composed of the constant “~VS~”, the response type, and the userid from the request packet. The packet is then sent to UACS.
SECOFF. The SECOFF program is an example of a security system logoff transaction. It simply reads the request packet and issues a logoff completed response. A logoff program must send a notification packet to UACS.
Sample Program Setup. To setup the sample security programs, perform the following steps:
• Verify that UACS is terminated.
• Obtain TIP program numbers for each of the programs (SECON and SECOFF).
• Create a VALTAB entry for each program.
• Edit the element selected, modifying all occurrences of the tokens ##AGNUMBER##, ##SUPURNUMBER##, and ##TIPSESS##. Change ##AGNUMBER## and ##SUPURNUMBER## to the appropriate values for the application group number and TIP SUPUR file number. Change ##TIPSESS## to TRUE if TIP session control is configured, FALSE if otherwise. The ##TIPSESS## value is only located in the SECON/C program.
Release 10R3: October 31, 2005 11-12 UniAccess for OS 2200 System Administration Guide
• Add the runstream. If the element SECON/UCOB is to be used with TIP session control active, either all of the passwords must be changed to all asterisks (*), or the password check must be deleted.
• After the sample security programs have been successfully created and installed, you must include the COMSRV LOGONTRAN and LOGOFFTRAN parameters in the UniAccess Configuration File. Refer to Chapter 16 for this syntax.
• Update the UniAccess Configuration File with the userids listed below (if COMSRV USEUAUSER configuration statement is set to YES).
• Rebuild the UniAccess Configuration File using the UACF processor. (See page 17-2 for the execution syntax of the UACF processor.)
•Restart UACS.
To test the security programs, establish a connection to UACS. To test a successful connection, use one of the following pre-configured userid and passwords:
Userid Password
varsec2 222222 varsec3 333333 varsec4 444444 varsec5 555555
If TIP session control is also configured, these userid and passwords must be entered into the Unisys Security System.
Release 10R3: October 31, 2005 12 Translation Routines 12 UniAccess Language Service Translation Routines
This chapter explains how to create and use the language service translation routines. Two user-written routines, UAClientToHost and UAHostToClient, are supported by UAHS (the UniAccess Hierarchical Service) and UARS (the UniAccess Relational Service), the language services provided by the UniAccess System. These pre-defined routines must be created by the user and are referred to as translation routines.
Topics Page
Overview of the Translation Routines 12-2 Translation Routine Definitions 12-4 UAClientToHost 12-4 UAHostToClient 12-5 Translation Routine Considerations 12-8 Processing SQL Statements 12-8 Processing Result Column Values 12-9 Processing Catalog RPCs 12-9 Coding the Translation Routines 12-13 Modifying Data 12-14 Handling Errors 12-15 Assigning a Return Code 12-16 Selecting an Error Message 12-16 Compiling and Installing the Translation Routines 12-17
Release 10R3: October 31, 2005 12-2 UniAccess for OS 2200 System Administration Guide
Overview of the Translation Routines The UniAccess System provides the capability for UARS and UAHS to pass incoming and outgoing data to user-supplied routines that may amend or translate the data as deemed appropriate and pass the data back to the language service for further processing. This functionality is provided through the UAUSER TRANSACTIVE and TRANSACTIVEH configuration parameters. Two translation routines are supported:
UAClientToHost allows a user-written translation routine to alter data received by UARS or UAHS from a client application.
UARS passes the following data to UAClientToHost: — SQL language strings — Stored procedure names — Stored procedure parameter names — Stored procedure parameter CHARACTER values — Stored procedure parameter NCHARACTER values.
UAHS passes the following data to UAClientToHost: — SQL language strings.
UAHostToClient allows a user-written translation routine to alter data being returned from the OS 2200 host before it is returned by UARS/UAHS to the client application.
UARS passes the following data to UAHostToClient: — Column names — Column CHARACTER values — Column NCHARACTER values — Stored procedure return parameter CHARACTER values — Stored procedure return parameter NCHARACTER values — Schema names.
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-3
UAHS passes the following data to UAHostToClient: — Column names.
The UAClientToHost and UAHostToClient routines of themselves provide no processing of passed data. They provide the parameters and calling syntax for creating user-written translation routines. They also provide a default routine in the event that the TRANSACTIVE configuration parameter is set to YES but the site has not written any translation routines. In this case, the default routines perform no translation.
The translation routines allow the incoming stored procedure names and parameter values to be replaced with values the user deems appropriate; they allow a similar translation of outgoing column names, column values, and stored procedure output parameters.
There are several potential uses for these routines. For example, you can use the translation routines to present data in a native character set, such as Kanji characters. You can use the translation routines to limit the scope of client access by limiting the number of tables from which the user can select data. You can also use the translation routines to modify the qualifiers for RDMS 2200 or DMS 2200 object names to provide additional security restraints, or you can perform character set modifications on the SQL statements before they are passed to RDMS 2200.
The translation routines also allow for the creation of a double-byte character set conversion routine that will be called for every NCHARACTER column returned by UARS. For example, Kanji LETS-J and Shift-JIS can be represented.
Release 10R3: October 31, 2005 12-4 UniAccess for OS 2200 System Administration Guide
Translation Routine Definitions This section defines the calling syntax for the translation routines and the definition of the parameters passed to the routines.
UAClientToHost
The UAClientToHost routine must be defined according to the following syntax, where the parameters are assigned to the meanings described in Table 12-1.
UARETURNCODE UAClientToHost (UAPARMTYPEParmType, UADATATYPE DataType, UAXLATETYPE XlateType, const void pValueIn, unsigned intValueInLength, void *pValueOut, unsigned int*piValueOutLength, unsigned intiValueOutMax, unsigned int*piMessageCode, void *vReserved )
UAClientToHost accepts the parameters described in the following table.
Table 12-1: UAClientToHost Parameters
Parameter Name Use Description
ParmType Input This parameter defines the parameter type. Possible values are: ua_language, ua_procedure_name, ua_parameter_name, and ua_parameter_value. DataType Input The parameter defines the datatype of the parameter. For ua_language, ua_procedure_name, and ua_paremter_name, the value will be ua_character. For ua_parameter_value, the value can be either ua_character or ua_ncharacter. XlateType Input The parameter defines the value of the current user’s TRANSOPTION value. Possible values are: ua_letsj, ua_sjis, and ua_no_xlate. If the value is ua_letsj or ua_sjis, RDMS has been requested to output Kanji identifiers in LETSJ or SJIS format. If the value is ua_no_xlate, RDMS has not been notified of a desired Kanji identifier format, and Kanji identifiers will be returned in the RDMS default format.
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-5
Parameter Name Use Description
pValueIn Input A pointer to the value to be converted. - For ua_language, ua_procedure_name, and ua_parameter_name, the data is NULL terminiated. -For ua_parameter_value, the data is padded with ASCII spaces to iValueOutMax characters. All of the data from iValueInLength to iValueOutMax should be ASCII spaces. This is done as part of the conversion from varchar to char. pValueInLength Input The length in bytes of the value to be converted. pValueOut Output The result of the conversion. piValueOutLength Output The total number of bytes available to return in pValueOut. iValueOutMax Input The length of pValueOut. - For a ParmType of ua_language, this is 16384 for UARS and 4096 for UAHS. - For a ParmType of ua_procedure_name or ua_parameter_name, is be 30. piMessageCode Output A pointer to the returned message code if return code is ua_failure. vReserved Unused Reserved for future use.
UAHostToClient
The UAHostToClient routine must be defined according to the following syntax, where the parameters are assigned to the meanings described in Table 12-2.
UARETURNCODE UAHostToClient (UAPARMTYPEParmType, UADATATYPEDataType, UAXLATETYPE XlateType, const voidpValueIn, unsigned int ValueInLength, void *pValueOut, unsigned int*piValueOutLength, unsigned intiValueOutMax, unsigned int*piMessageCode, void *vReserved )
UAHostToClient accepts the parameters described in the following table.
Release 10R3: October 31, 2005 12-6 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-7
Table 12-2: UAHostToClient Parameters
Parameter Name Use Description
ParmType Input This parameter defines the parameter type. Possible values are: ua_parameter_value, ua_column_name, ua_column_value, ua_schema_name. DataType Input The parameter defines the datatype of the parameter. For ua_column_name, the value will be ua_character. For ua_parameter_value, ua_column_value, and ua_schema_name the value can be either ua_character or ua_ncharacter. XlateType Input The parameter defines the value of the current user’s TRANSOPTION value. Possible values are: ua_letsj, ua_sjis and ua_no_xlate. If the value is ua_letsj or ua_sjis, RDMS has been requested to output Kanji identifiers in LETSJ or SJIS format. If the value is ua_no_xlate, RDMS has not been notified of a desired Kanji identifier format, and Kanji identifiers will be returned in the RDMS default format. pValueIn Input A pointer to the value to be converted. pValueInLength Input The length in bytes of the value to be converted. pValueOut Output The result of the conversion. Not NULL terminated. piValueOutLength Output The total number of bytes available to return in pValueOut. iValueOutMax Input The length of pValueOut. For a ParmType of ua_column_name, this will be 30. piMessageCode Output A pointer to the returned message code if return code is ua_failure. vReserved Unused Reserved for future use.
Release 10R3: October 31, 2005 12-8 UniAccess for OS 2200 System Administration Guide
Translation Routine Considerations The following considerations should be taken into account when implementing translation routines.
Processing SQL Statements
When a UniAccess language service receives SQL text from a client application, it processes the statements and prepares to send them to the OS 2200 database. The language service calls the translation routine before passing the SQL text to the OS 2200 database.
Note If the UAClientToHost routine modifies the SQL text, the UACS language trace file will contain the SQL passed from the client application to UACS and not the string passed to RDMS 2200 or DMS 2200. In other words, the UACS trace file will contain the unchanged SQL text.
Processing Batched SQL Statements
The UniAccess language service calls the UAClientToHost routine once for each SQL statement. If the SQL statements are batched using the semicolon delimiter, the language service processes each statement separately, calling the UAClientToHost routine and passing the returned SQL text to the OS 2200 database, until one of the following conditions occurs:
• The batch is exhausted.
•A SET TRANSACTIVE OFF command is processed.
• The UAClientToHost routine requests that the batch be aborted.
• An RDMS 2200 or DMS 2200 error occurs in processing any statement in the batch.
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-9
For example, if UARS receives the following batched SQL statement:
select * from employee;select * from job_description;select from job_category;
the UAClientToHost routine will be called three times with the following three strings:
select * from employee; select * from job_description; select * from job_category;
Processing Result Column Values
When processing result column CHARACTER and NCHARACTER values, the input and translated buffers are the same buffer, the output length must equal input length, and the translated string must not be NULL terminated.
Processing Catalog RPCs
Both UARS and UAHS honor the TRANSACTIVE setting when processing UniAccess catalog RPCs. If TRANSACTIVE is ON, both transactions pass incoming parameter values and outgoing result column values to the translation routines for further processing. The following tables list the catalog RPCs and the respective parameter and result column values that are passed to the translation routines. Note that the list of parameters and column values represent the order in which they are passed to the translation routines. Also when optional parameters are not passed as part of the RPC, UAHS and UARS will pass an empty string to the translation routines.
UARS Catalog Procedure Interface
Table 12-3 lists the UARS catalog RPCs and the interface to the translation routines. Additional information about the UARS catalog RPCs is contained in Chapter 8 of the UniAccess for OS 2200 Client Guide.
Release 10R3: October 31, 2005 12-10 UniAccess for OS 2200 System Administration Guide
Table 12-3: UARS Catalog RPC Translation
Parameters UARS Catalog Parameters Result Columns Result Columns Not Request Translatable Translatable Not Translatable Translatable sp_columns table_name table_qualifier data_type table_owner table_owner type_name table_qualifier table_name precision column_name column_name length sp_column_privileges table_name table_qualifier table_owner table_owner table_qualifier table_name column_name column_name grantor grantee sp_databases database_name database_size remarks sp_datatype_info data_type literal_prefix type_name literal_suffix data_type local_type_name precision create_params nullable case_sensitive searchable unsigned_attribute money auto_increment minimum_scale maximum_scale sp_fkeys pktable_name pktable_qualifier key_seq pktable_owner pktable_owner update_rule pktable_qualifier pktable_name delete_rule fktable_name pkcolumn_name fktable_owner fktable_qualifier fktable_qualifier fktable_owner fktable_name fkcolumn_name fk_name pk_name sp_pkeys table_name table_qualifier key_seq table_owner table_owner pk_name table_qualifier table_name column_name
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-11
Parameters UARS Catalog Parameters Result Columns Result Columns Not Request Translatable Translatable Not Translatable Translatable sp_server_info attribute_id attribute_name attribute_id attribute_value sp_special_columns table_name column_type column_name scope table_owner scope type_name precision table_qualifier nullable length scale pseudo_column sp_sproc_columns sp_name sequence_params sp_qualifier column_type sp_owner sp_owner data_type sp_qualifier sp_name length column_name column_name scale type_name radix nullable remarks sp_statistics table_name unique table_qualifier non_unique table_owner accuracy table_owner type table_qualifier table_name seq_in_index index_qualifier collation index_name cardinality column_name pages filter_condition sp_stored_procedures sp_name sp_qualifier num_input_params sp_owner sp_owner num_output_params sp_qualifier sp_name num_result_sets remarks procedure_type sp_tables table_name table_qualifier remarks table_owner table_owner table_qualifier table_name table_type table_type sp_table_privileges table_name table_qualifier privilege table_owner table_owner is_grantable table_qualifier table_name grantor grantee
UAHS Catalog RPC Interface
Release 10R3: October 31, 2005 12-12 UniAccess for OS 2200 System Administration Guide
Table 12-4 lists the UAHS catalog RPCs and the interface to the translation routines. Additional information about the UAHS catalog RPCs is contained in Chapter 11 of the UniAccess for OS 2200 Client Guide.
Table 12-4: UAHS Catalog RPC Translation
Parameters UAHS Catalog Parameters Result Columns Result Columns Not Request Translatable Translatable Not Translatable Translatable sp_columns table_name table_qualifier data_type table_owner table_owner type_name table_qualifier table_name precision column_name column_name length sp_datatype_info data_type type_name data_type precision literal_prefix literal_suffix local_type_name create_params nullable case_sensitive searchable unsigned_attribute money auto_increment minimum_scale maximum_scale sp_special_columns table_name column_type column_name; scope table_owner scope type_name; precision table_qualifier nullable length scale pseudo_column
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-13
Parameters UAHS Catalog Parameters Result Columns Result Columns Not Request Translatable Translatable Not Translatable Translatable sp_statistics table_name unique table_qualifier table_owner accuracy table_owner table_qualifier table_name index_qualifier index_name column_name non_unique type seq_in_index collation cardinality pages filter_condition sp_tables table_name table_qualifier remarks table_owner table_owner table_qualifier table_name table_type table_type
Coding the Translation Routines This section contains information about the tasks that the routine should be coded to perform. These tasks include:
• Modifying data
• Handling errors
• Assigning a return code
• Selecting an error message.
The translation routines must be written in UCS C and/or MASM. AIS supplies an example of the UAClientToHost and UAHostToClient routines (including header files) written in UCS C in the file SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode
Release 10R3: October 31, 2005 12-14 UniAccess for OS 2200 System Administration Guide
installation). The sample procedures UAClientToHost and UAHostToClient are contained in the element usrxlate/c. You can tailor these routines as necessary to meet your site requirements.
Modifying Data
If the translation routine modifies any data, it must transfer the modified data to the buffer indicated by pValueOut and return the size of the data in bytes in the integer indicated by piValueOutLength. The value set in piValueOutLength informs UAHS or UARS if the data has been modified. The modified data must not exceed the value specified in the iValueOutMax parameter. Note If the SQL text is modified, it is submitted as to RDMS 2200 or DMS 2200 as is and, therefore, must be complete and adhere to the syntax rules.
Client to Host Translation
The following types of data may be altered by a UAClientToHost routine: — SQL language strings — Stored procedure names — Stored procedure parameter names — Stored procedure parameter CHARACTER values — Stored procedure parameter NCHARACTER values.
Note The modified data string may be NULL terminated.
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-15
Host to Client Translation
The following types of data may be altered by a UAHostToClient routine: — Column names — Column CHARACTER values — Column NCHARACTER values — Stored procedure return parameter CHARACTER values — Stored procedure return parameter NCHARACTER values — Schema names.
Note The modified data string may not be NULL terminated.
Handling Errors
Errors associated with translation routine execution can occur before the routine is called, during the routine’s processing, and after the routine returns to the language service. This section discusses the types of errors and their consequences so that you can provide appropriate error handling code in a routine.
Before the Routine is Called
The translation routines are not invoked if an error occurs in UARS or UAHS processing before the translation routine call. One of the server program messages listed in Appendix D will be returned to the client application if this occurs.
During Translation Routine Processing
Errors that occur during the processing of a routine have the following results:
• If your routine generates a contingency and your code does not handle the contingency, the language service terminates and the UniAccess termination handler will be invoked. A message will be returned to the client application,
Release 10R3: October 31, 2005 12-16 UniAccess for OS 2200 System Administration Guide
indicating that a transaction error was detected. • If your routine generates a contingency and your code handles the contingency, the language service will not be aware of the problem. UARS or UAHS processing should continue normally.
• If your routine contains an internal logic error, results are unpredictable.
After the Return to The Language Service
Only translation routine processing should be able to cause errors after returning control to the language service. Errors that occur after the return to UARS or UAHS have the following results:
• If your routine’s modification of the SQL text string is invalid, RDMS or DMS performs its usual error handling.
• Any RDMS or DMS error that occurs in batched SQL commands terminates the entire batch.
Assigning a Return Code
Only 2 valid return codes are possible. If a translation routine processes successfully, the return code is ua_success; otherwise it must return ua_failure. A return of ua_failure should also be accompanied by an appropriate message code.
Return Code Meaning
ua_success piValueOutlength points to the size of any modified data. The modified data should replace the original data. ua_failure piMessageCode should point to the related error message number.
Selecting an Error Message
If a translation routine returns a code of ua_failure, it should also set the output message code field pointer to piMessageCode. When a translation routine returns a code of ua_failure, the language service matches the message code against the message table
Release 10R3: October 31, 2005 UniAccess Language Service Translation Routines 12-17
maintained in UADT. If the message code is in UADT, the language service sends the text associated with that message number. If the language service cannot find the message code in UADT, it sends the default error message 33308. Message numbers between 33900 and 33999 are available as message codes.
Altering the Message Table
To add messages for a translation routine to the message table, add UAMESG and UAMMAP entries to the Site Information File. (See Chapter 10, Returning Server Program Messages to Client Applications, for more information about altering and adding messages.) After adding messages to the Site Information File, the UniAccess Configuration File must be processed and loaded into UADT. (See page 18-1 for information on updating the Configuration File.)
Compiling and Installing the Translation Routines
The UAClientToHost and UAHostToClient translation routines are contained in the USRXALTE/C module. The ECL for compiling the USRXALTE/C module is in the USRXLATE/CMP element in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode installation).
After compiling your translation routines, the standard UARS or UAHS installation routines should be used to link the transaction. Chapter 4, Installing the UniAccess System, describes the steps to install these language service transactions. If the UARS/BUILD or UAHS/BUILD runstream already exists in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for a test mode installation), it can simply be @ADDed in order to link and install UARS or UAHS with the new translation routines.
Release 10R3: October 31, 2005 12-18 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 13 ISQL 13 Interactive SQL Parser
This chapter describes how to use the Interactive SQL (ISQL) processor in the UniAccess Transaction Client environment.
Topics Page
Overview of the Interactive SQL Parser 13-1 Invoking ISQL 13-2 Entering ISQL Commands 13-3 Viewing Data Results 13-3
Overview of the Interactive SQL Parser Interactive SQL Parser for OS 2200 (ISQL) is a feature of the UniAccess Transaction Client. It is a processor that allows you to enter SQL language requests under an OS 2200 demand session. Transaction Client routes these SQL requests to the requested server and displays the results on your terminal. No programming is required.
From the OS 2200, you can use the ISQL processor to access SQL Servers, Open Servers, the UniAccess Transaction Server, or either of the UniAccess ODBC Servers. You specify the server during the login process. This chapter includes samples and describes options available with ISQL.
Release 10R3: October 31, 2005 13-2 UniAccess for OS 2200 System Administration Guide
Invoking ISQL ISQL is executed as an OS 2200 processor using the following format:
@ISQL,option spec
where:
option
is one of the following:
H display ISQL help and version information
N no paging prompt. Without this option, ISQL displays a prompt to continue or to terminate after each screen of displayed data
X abnormally terminate processor upon first error.
spec is the system data format (SDF) source input file. ISQL will read and processes the statements in this source file and display the results to the terminal (PRINT$).
When the ISQL processor has been invoked, a prompt for userid will appear. After this prompt is answered, prompts for password and server name will appear. The password prompt is issued at line 23 as a non-display field. Changing the insert point with the @@INS command will cause the password prompt to be abnormally positioned. Responding with an empty response will terminate the processor and return you to demand mode. The initial prompt appears as follows:
------Interactive SQL Parser for OS2200 Level 10R3-0 ------Userid: >
After you are connected to a server the following prompt will appear:
1>
Release 10R3: October 31, 2005 Interactive SQL Parser 13-3
Entering ISQL Commands After the connection to the server has been established, SQL language commands can be entered into a command buffer. Every time a line is transmitted, the current line is appended to the command buffer. When the keyword go is entered on a line by itself, the command buffer is sent to the server specified at initialization time. The following commands have particular meaning to ISQL when they are entered on a line by themselves:
go — submit the current command buffer.
quit — terminate without submitting the current command buffer.
exit — terminate without submitting the current command buffer.
reset — clear the current command buffer.
Viewing Data Results The sample output below shows the results from an SQL request. When more than one page of results are being displayed, a prompt is displayed to allow the results to be paged, scrolled continuously, or canceled. Simply pressing Return will display the next page of results. Changing the insert point with the @@INS command will cause the paging display prompt to function incorrectly.
FIRST_NAME LAST_NAME ------Roger Harmon Glenn Ellsworth Margaret Lichtenstein Douglas Isaacs Susan O'Rielly Helga Smith Allison Underwood Franklin Cooper Julie Sanders Nancy Erickson William Daniels Fredrick Chadwick
Release 10R3: October 31, 2005 13-4 UniAccess for OS 2200 System Administration Guide
Bradley Nelson Kenneth Russell Paul Thomas Louise Urich Patrick Sutherland Wayne Lucas Steven Wilson Samantha Edwards Thelma Rogers Edward Andrews
(22 row(s) affected)
Release 10R3: October 31, 2005 14 UAHS 14 UniAccess Hierarchical Service
This chapter provides an overview of UniAccess Hierarchical Service (UAHS) design and describes the function of system components. It explains how to build a UAHS repository, how to create a relational mapping of a DMS schema, and how to use the SCHEMADEF and TABLEDEF utility programs to create the UAHS Meta Database. It also summarizes UAHS support of DMS and SQL.
Topics Page
UAHS Overview 14-2 Terminology 14-3 Building the UAHS Repository 14-3 UAHS Meta Database Procedures 14-4 DMS Schema Mapping 14-9 The Sample Schema 14-9 UAHS Database Definition 14-15 UAHS Table Definition 14-16 Retrieval Methods 14-30 Security 14-33 UAHS Guidelines and Restrictions 14-35 SCHEMADEF and TABLEDEF Reference 14-38 SCHEMADEF 14-38 TABLEDEF 14-40 TABLEDEF Data Definition Entries 14-43
Release 10R3: October 31, 2005 14-2 UniAccess for OS 2200 System Administration Guide
UAHS Overview UniAccess Hierarchical Service for DMS 2200 (UAHS) provides read-only access to DMS 2200 data using a relational mapping over the hierarchical structure. Components of UAHS include the utilities to create the relational mappings, a TIP file that serves as the repository for the relational mappings, and a TIP transaction to service both SQL and catalog requests. No OS 2200 programming is necessary. Both ODBC and Open Client applications can call the UAHS TIP transaction.
The two utilities provided by UAHS are used to create a relational view of the DMS 2200 hierarchical schema that is maintained in the UAHS Meta Database. The utility SCHEMADEF, as the name implies, is used to enter a DMS schema definition into the Meta Database. The utility TABLEDEF builds on the information recorded by SCHEMADEF and allows the system administrator to define relational structures (databases, tables, and columns) based on that information. SCHEMADEF and TABLEDEF will be discussed in detail in this chapter.
The UAHS repository, as mentioned above, is called the UAHS Meta Database. It contains all the information about the DMS schema and relational representations of it. The Meta Database resides in a permanent TIP/FCSS user file.
The UAHS TIP transaction, called UAHS, provides dynamic SQL access to DMS 2200 using the relational views in the Meta Database. SQL access involves parsing the request, validating the SQL SELECT statement, accessing DMS 2200 data (using DMS DML commands), and returning the data as relational rows. UAHS restricts access to simple selections based on comparisons, with limited sorting and summarizing. For more specific information and guidelines on writing client applications for use with UAHS, see Chapter 9 of the UniAccess for OS 2200 Client Guide.
The TIP transaction also 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 may also be used independently by ODBC and Open Clients and are described in Chapter 11 of the UniAccess for OS 2200 Client Guide.
In addition to installing and configuring the UAHS transaction(s) as specified in Chapter 4, system administrators are responsible for the creation and maintenance of the UAHS Meta Database. They should be familiar with the topics covered in this chapter.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-3
Terminology
In this manual, the TIP transaction that processes language requests to DMS 2200 is called by its default name, UAHS. You can, however, assign a different name when you define it to TIP.
In an attempt to clarify discussions in this chapter, the terms schema and database are used distinctly. Schema is used to refer to a DMS 2200 schema. The term database, refers to a specific relational mapping specified by the UAHS CREATE DATABASE command, as described in the section TABLEDEF Data Definition Entries. It is sometimes explicitly referred to as a UAHS database.
The term UAHS Meta Database refers to the repository containing all UAHS relational mappings of a given DMS schema.
Relational terms—table, column, etc.—are used only when referring to UAHS database items. Items in DMS are referred to by their traditional/hierarchical name—record, field, etc.
Building the UAHS Repository UAHS must know how a DMS schema is defined in order to access data. Additionally, it must have a relational view of the DMS entities in order to service SQL requests. The DMS schema information and relational mapping of the schema are contained in a repository called the UAHS Meta Database. The system administrator first creates the TIP file that will contain the Meta Database and then uses the utilities SCHEMADEF and TABLEDEF to enter the information needed by UAHS (see Figure 14-1).
The SCHEMADEF utility is used to enter the DMS schema information into the UAHS Meta Database. The schema information is obtained from the DDL (data definition language) source used to create the schema. Translating the DMS DDL into the UAHS Meta Database captures the information pertaining to areas, records, record-items, and set relationships.
The TABLEDEF utility is used to create a relational-type representation of the schema information. TABLEDEF uses a set of data definition commands (similar to SQL DDL commands) to create the relational view of the schema. The databases, tables, and columns
Release 10R3: October 31, 2005 14-4 UniAccess for OS 2200 System Administration Guide
defined with TABLEDEF are the item names that are available for use by ODBC client and Open Client requests via UAHS.
Executed 1st
DMS 2200 DDL SCHEMADEF A TIP file created by the system administrator.
Typically, the script of UniAccess System utility, the DMS schema source. installed in SYS$LIB$*UAUTIL(T). UAHS Meta Inputs DMS schema information. Database
A repository of the DMS UAHS Data schema definition and TABLEDEF Definition the relational mappings Commands needed by UAHS. Executed 2nd U Data Definition source entries. UniAccess System utility, A installed in SYS$LIB$*UAUTIL(T). Typically, created by the system H administrator and maintained in Creates and maintains a relational- S a symbolic element. type view of the schema information.
Figure 14-1: Building the UAHS Repository
Note that the utilities operate strictly on source language input and the UAHS Meta Database, updating only the Meta Database. The DMS schema absolute and data areas are not used by the utilities.
UAHS Meta Database Procedures
The steps to make a DMS 2200 schema available to UAHS and, thus, to client applications are listed in the following table.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-5
Table 14-1: Steps in Creating the UAHS Meta Database
Step Action to be taken
1 Create the relational representation of your DMS schema.
2 Estimate the Meta Database and optimal TIP file size.
3 Create the UAHS Meta Database TIP file.
4 Build the UAHS Meta Database using the SCHEMADEF and TABLEDEF utilities.
5 Adjust the TIP file size.
1. Create the Relational Mappings
As system administrator, you are responsible for providing a meaningful, accurate, relational view of (a portion of) your DMS schema. A relational view is required for servicing client SQL requests. You must analyze your schema and decide how to map the DMS entities to relational ones, using the following guidelines:
• Create one or more UAHS databases, based on a trivial subschema of your schema. Creating different databases will allow functional groupings of tables.
• Create UAHS tables based on DMS records. Where set relationships exist, you can combine related records into the same table.
• Create columns for your tables by selecting the desired fields from the DMS record(s) for inclusion in a table.
Because hierarchical and relational configurations are fundamentally different, and because the DMS 2200 schema may be complex, the mapping process is not trivial and can greatly affect UAHS performance in accessing data. The section DMS Schema Mapping later in this chapter discusses mapping issues at length.
The mapping described above is achieved by writing UAHS data definition commands, which are SQL-like commands processed by the utility, TABLEDEF. The system administrator is responsible for writing and maintaining these commands. The commands are system data format (SDF) ASCII images that can be placed in a file or program file
Release 10R3: October 31, 2005 14-6 UniAccess for OS 2200 System Administration Guide
element and @ADDed as input to the TABLEDEF utility. The section TABLEDEF Data Definition Entries in this chapter defines the format and explains the rules governing these commands.
2. Estimate the Optimal TIP File Size
Part of a TIP file’s definition is its record length and number of records in the file. They are specified as parameters when the file is created (Step 4). The record length for the UAHS Meta Database is fixed at 56 words. You determine the optimal number of records for your TIP file based on the number of Meta Database entities you will create. In lieu of estimating the size of the TIP file, however, you may chose to use a size of 10,000 records (313 tracks). This size should handle most DMS databases.
The UAHS Meta Database TIP file is implemented as a hashed file using the entity name as the hash key. It must be large enough to contain all the entities you will define. Also, a larger file will minimize duplicates created by the hashing algorithm, thereby reducing I/O when accessing the file and improving UAHS performance.
You can size the TIP file by estimating the number of entries that will be stored in it. The SCHEMADEF and TABLEDEF utilities each store one logical record for every entity they define. The SCHEMADEF utility stores approximately one logical record in the TIP file for each of the following DMS items: — DMS schema — DMS data name — DMS record — DMS record item — DMS area — DMS set.
The TABLEDEF utility stores one logical record for each of the following: — UAHS database — UAHS table — UAHS table column.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-7
Note For SCHEMADEF, you can obtain most numbers from the output of the @DDL processor. You only need to estimate the number of record items. If you structure your TABLEDEF commands so that each entity definition is on a separate line, the number of entities will be roughly the number of lines in your script.
Once you have an approximate number of entities, multiply that number by a factor of 2.5 (rounding up, if desired) to give the number of records you should configure as the TIP file size.
Note that the file sizing is approximate. You need not be exact when determining the number of entities. When in doubt, estimate high. A larger file will generally yield better performance. But note that this is true only to a point—you won’t see any performance gains by creating an unreasonably large file.
3. Create the TIP file
The TIP file that will contain the UAHS Meta Database must be created prior to using SCHEMADEF. A meta database file must exist for each application group in which UAHS will run. The file must be cataloged and registered as a permanent TIP FCSS file using whatever facilities are used at your site. The file should be configured with a record length of 56 words and the number of records estimated in the previous step. The TIP file must allow the write-without-lock (WW) function. The number of the TIP file is configured in the APPINF UAHSTIPF parameter of the UniAccess Configuration File (see Chapter 16).
The following is an example of creating the TIP file using FREIPS.
@CAT,P TIP$*SCHEMADEF.,FSCSI/313//313,REM003 @TIP$*TIPRUN$.FREIPS,XIU TREG TIP$*SCHEMADEF.,FIX RES 24,10000,56,,SCHEMADEF,WW=P
In this example, the TIP file number is 24 and will contain 10,000 records. The record length is set at 56 words, a requirement for the UAHS Meta Database. The APPINF host configuration entry is UAHSTIPF, 24.
Release 10R3: October 31, 2005 14-8 UniAccess for OS 2200 System Administration Guide
4. Build the Meta Database
This step is the actual construction of the UAHS Meta Database using the UAHS utilities. This step is comprised of two parts—running the SCHEMADEF utility program and running the TABLEDEF utility program.
Part 1. Execute SCHEMADEF to incorporate the DMS schema definition into the UAHS Meta Database. Input to the utility is the TIP file number established in Step 3, followed by the DMS schema DDL. The SCHEMADEF section on page 14-38 of this chapter defines the execution syntax and gives an example of running SCHEMADEF.
Part 2. Execute TABLEDEF to create relational information for UAHS clients. Input to the utility is the TIP file number established in Step 3, followed by database and table definition entries written in Step 1. The TABLEDEF section on page 14-40 of this chapter defines the execution syntax and gives an example of running TABLEDEF.
Note When changes are made to your schema DDL, you must re-run SCHEMADEF and TABLEDEF to rebuild the UAHS Meta Database. Otherwise, the contents will be out of synch with the DMS schema, and cause UAHS to produce erroneous results.
5. Adjust the TIP File Size
This optional step may be undertaken to improve performance after the TIP file and Meta Database information have been established and you have begun using UAHS. You may want to experiment with larger TIP file sizes to see if you effect a change in UAHS performance. The file size is changed using whatever TIP utilities are available at your site.
Note If you change the number of records in your TIP file, you must remember to re-run SCHEMADEF and TABLEDEF to rebuild the Meta Database. Otherwise, the contents will be incorrect and will cause UAHS to produce erroneous results.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-9
DMS Schema Mapping UAHS provides ODBC-like access to DMS data, including minimal SQL functionality; it does not transform DMS into a fully featured relational database engine. To accomplish ODBC-like behavior, UAHS operates from a meta database containing information that maps DMS schema entities to relational entities.
A hierarchical database is inherently different than a relational database. A DMS schema often represents complex structures that are optimized for hierarchical access. Therefore, entity mapping may not be a trivial exercise. The administrator responsible for this task should be experienced with DMS 2200 and DDL syntax, and understand relational structures and SQL. This administrator should be familiar with the given DMS schema as well as with client tools, applications, and methods for accessing DMS records.
This section describes how a system administrator creates a relational view of a DMS 2200 schema. It discusses the issues associated with mapping hierarchical structures to relational ones, as they apply in the DMS/UAHS environment. This section contains the details for designing the relational mapping of your schema, as outlined in Step 1 of UAHS Meta Database Procedures earlier in the chapter.
As mentioned above, there may be challenges associated with hierarchical-to-relational mapping, and there are no standards or rigid rules for mapping. Many factors can help you determine which is the best strategy to use. Speed of access and volume of records involved are major considerations. Usage patterns and end-user feedback will help you fine tune your UAHS mappings.
The Sample Schema
The discussions in this section present several examples of relational mapping and data access. The examples are based on the sample DMS schema described here. The sample schema and data are intentionally simple, so they can readily illustrate the mappings and data access paths. The examples assume a schema that has the following records and set relationships defined in DMS:
OFFICE-REC: Index Sequential record accessed using a single-field, non-RANGE key Owner of Set OFF-EMP
EMPLOYEE-REC: CALC record accessed using a single-field key Member of Set OFF-EMP Owner of Set EMP-DEP
Release 10R3: October 31, 2005 14-10 UniAccess for OS 2200 System Administration Guide
DEPENDANT-REC: Record accessed using DMS set relationship Member of Set EMP-DEP
TASK-REC: CALC record, also conditionally participates in a set relationship Manual member of set EMP-TASK
The application for the sample schema in our hypothetical company accomplishes the following: records the EMPLOYEEs working in various company OFFICEs, records the DEPENDANT(s) of each employee, and records the company’s TASKs and assigns them to EMPLOYEEs.
The sample schema DDL is shown below.
IDENTIFICATION DIVISION SCHEMA PROJECT FILE SAMPLE QUALIFIER UAHS
DATA DIVISION DATA NAME SECTION 01 AREA-GDN USAGE AREA-NAME 01 RECORD-GDN USAGE RECORD-NAME 01 SET-GDN USAGE SET-NAME 01 DBKEY-GDN USAGE DATABASE-KEY 01 AREA-KEY-GDN USAGE AREA-KEY
AREA SECTION AREA LOOKS INCLUDE QUICK-BEFORE-LOOKS AFTER-LOOKS
AREA OFF-INDEX CODE 001 MODE INDEX ALLOCATE 20 PAGES PAGES 1792 WORDS AREA OFF-AREA CODE 002 MODE DATA ALLOCATE 100 PAGES DYNAMICALLY EXPANDABLE TO 1000 PAGES 1792 WORDS
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-11
AREA EMP-AREA CODE 003 MODE DATA ALLOCATE 100 PRE-INITIALIZED PAGES DYNAMICALLY EXPANDABLE TO 2000 PAGES PAGES 448 WORDS CALC 1 CHAINS LINKED PRIOR
AREA DEP-AREA CODE 004 MODE DATA ALLOCATE 100 PRE-INITIALIZED PAGES DYNAMICALLY EXPANDABLE TO 1000 PAGES PAGES 448 WORDS
AREA TASK-AREA CODE 005 MODE DATA ALLOCATE 100 PRE-INITIALIZED PAGES DYNAMICALLY EXPANDABLE TO 1000 PAGES PAGES 448 WORDS CALC 1 CHAINS LINKED PRIOR
RECORD SECTION
RECORD NAME IS OFFICE-REC CODE 001 LOCATION MODE INDEX SEQUENTIAL USING ASCENDING KEY OFF-NAME INDEX AREA OFF-INDEX LINKS ARE NEXT AND PRIOR DUPLICATES NOT ALLOWED WITHIN OFF-AREA MODE ASCII 05 OFF-NAME PIC X(32)
RECORD NAME IS EMPLOYEE-REC CODE 002 LOCATION MODE CALC DMSCALC IN AREA-GDN USING EMP-SSN DUPLICATES NOT ALLOWED WITHIN EMP-AREA MODE ASCII 05 EMP-SSN PIC 9(09)
Release 10R3: October 31, 2005 14-12 UniAccess for OS 2200 System Administration Guide
05 EMP-NAME. 10 EMP-FNAME PIC X(10). 10 EMP-LNAME PIC X(20).
RECORD NAME IS DEPENDANT-REC CODE 003 LOCATION MODE VIA EMP-DEP-SET WITHIN DEP-AREA MODE ASCII 05 DEP-NAME PIC X(30)
RECORD NAME IS TASK-REC CODE 004 LOCATION MODE CALC DMSCALC IN AREA-GDN USING TASK-ID DUPLICATES NOT ALLOWED WITHIN TASK-AREA RESERVE 2 POINTERS MODE ASCII 05 TASK-ID PIC X(08) 05 TASK-NAME PIC X(32) 05 TASK-ACTIVITY PIC X(20) OCCURS 8 TIMES
SET SECTION
SET NAME IS OFF-EMP-SET CODE 001 MODE CHAIN LINKED PRIOR ORDER LAST OWNER OFFICE-REC MEMBER EMPLOYEE-REC AUTOMATIC SELECTION THRU CURRENT OF SET
SET NAME IS EMP-DEP-SET CODE 002 MODE CHAIN LINKED PRIOR ORDER LAST OWNER EMPLOYEE-REC MEMBER DEPENDANT-REC AUTOMATIC SELECTION THRU CURRENT OF SET
SET NAME IS EMP-TASK-SET CODE 003 MODE CHAIN LINKED PRIOR ORDER LAST OWNER EMPLOYEE-REC MEMBER TASK-REC MANUAL SELECTION THRU CURRENT OF SET
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-13
The SDDL for a UCS COBOL subschema is shown below.
IDENTIFICATION DIVISION SUBSCHEMA NAME IS UCOBSUB01 IN FILE SAMPLE OF SCHEMA PROJECT HOST LANGUAGE IS UCS COBOL DATA DIVISION DATA NAME SECTION DATA NAMES ARE ALL AREA SECTION AREAS ARE ALL RECORD SECTION RECORDS ARE ALL SET SECTION SETS ARE ALL
The following diagram depicts occurrences of the OFF-EMP-SET and EMP-DEP-SET sets:
Accounting Marketing
000000001 0000000002 000000003 000000007 0000000008 000000009 Howard Johnson Dennis Watson Myrtle Eastgate Mary Mathews Fran Finney Rhonda Rooney
Carol David Stanley Mary John Mary Thomas Marie Patrick
Engineering Sales Blimps Sales Jets
000000004 0000000005 000000006 0000000010 00000000011 0000000012 Peter Graves Robert Yates John Keating Richard Rich Joanie Ward Bennie Goodman
Shirley Elisabeth Linda Anne Anne Joseph Jon
Figure 14-2: Office and Employee Sample Data
Release 10R3: October 31, 2005 14-14 UniAccess for OS 2200 System Administration Guide
The following diagram depicts the TASK-REC records and occurrences of the EMP-TASK-SET.
000000004 000000009 Peter Graves Rhonda Rooney
T0000001 Analysis T0000002 Coding T0000003 Presentation (1) Design (1) Prototype (1) Demo (2) Review (2) Construct (2) Meeting (3) Test (4) Optimize
000000001 Howard Johnson
T0000004 Accounting T0000005 Clerical T0000006 Cleaning (1) Budget (1) WP (1) Windows (2) Payroll (2) Admin (2) Floors (3) Trash
Figure 14-3: Employee and Task Diagram Sample Data
The TABLEDEF data definition commands to create the sample relational mappings of the schema are shown below. All samples used throughout the section are given here for reference. Each is discussed in detail later under the appropriate topics of this section.
CREATE TABLE TASK FOR PROJECT_DB.TASK-REC COLUMN TASK_ID IS TASK-REC.TASK-ID COLUMN TASK_NAME IS TASK-REC.TASK-NAME
CREATE TABLE DEPENDANT FOR PROJECT_DB.DEPENDANT-REC COLUMN DEP_NAME IS DEPENDANT-REC.DEP-NAME
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-15
CREATE TABLE STAFF FOR PROJECT_DB.OFFICE-REC COLUMN OFFICE IS OFFICE-REC.OFF-NAME COLUMN EMPLOYEE IS EMPLOYEE-REC.EMP-LNAME
CREATE TABLE ACTIVITIES FOR PROJECT_DB.TASK-REC COLUMN TASK_NAME IS TASK-REC.TASK-NAME COLUMN ACT1 IS TASK-REC.TASK-ACTIVITY(1) COLUMN ACT2 IS TASK-REC.TASK-ACTIVITY(2) COLUMN ACT3 IS TASK-REC.TASK-ACTIVITY(3) COLUMN ACT4 IS TASK-REC.TASK-ACTIVITY(4)
CREATE TABLE INSURED_DOWN FOR PROJECT_DB.OFFICE-REC COLUMN OFF_NAME IS OFFICE-REC.OFF-NAME COLUMN EMP_NAME IS EMPLOYEE-REC.EMP-LNAME COLUMN DEP_NAME IS DEPENDANT-REC.DEP-NAME
CREATE TABLE INSURED_UP FOR PROJECT_DB.DEPENDANT-REC COLUMN OFF_NAME IS OFFICE-REC.OFF-NAME COLUMN EMP_NAME IS EMPLOYEE-REC.EMP-LNAME COLUMN DEP_NAME IS DEPENDANT-REC.DEP-NAME
CREATE TABLE ASSIGNMENTS_DOWN FOR PROJECT_DB.EMPLOYEE-REC COLUMN EMP_LNAME IS EMPLOYEE-REC.EMP-LNAME COLUMN TASK_NAME IS TASK-REC.TASK-NAME
CREATE TABLE ASSIGNMENTS_UP FOR PROJECT_DB.TASK-REC COLUMN EMP_LNAME IS EMPLOYEE-REC.EMP-LNAME COLUMN TASK_NAME IS TASK-REC.TASK-NAME
UAHS Database Definition
In relational environments, a database is a set of related data tables (and other relational objects) that are organized and presented to serve a specific purpose. Likewise, a UAHS database is a set of UAHS tables that are based on DMS records and sets. You can define one or more UAHS databases for your schema. Then, by specifying a database name in a table definition command, you designate a table to be a member of the given database. Defining more than one database for your schema allows you to create and group tables in ways that enforce confidentiality requirements, simplify access, and prevent ad hoc access from adversely affecting your system’s performance. If you currently use subschemas to logically partition your DMS schema, you will probably want to use multiple UAHS databases for the same functionality.
Release 10R3: October 31, 2005 14-16 UniAccess for OS 2200 System Administration Guide
The name you specify for a database is the name that will be used by client applications; it is the database name used in the UADriver Setup. The database name is sometimes referred to as the ODBC qualifier or catalog name as well.
All UAHS databases are based on the trivial subschema of your DMS schema. This is a UAHS requirement. To properly construct DMR requests, UAHS must have access to a subschema containing all entities that are in the schema. The subschema must specify a host language of UCS COBOL. But since UAHS is not compiled with the subschema, it does not have access to any entity names or attributes specified in the subschema DDL. Therefore, name substitutions or re-definitions specified in the subschema cannot be used to map entities. Only those names that are specified in the schema DDL can be used.
A UAHS database is defined with the TABLEDEF DEFINE DATABASE command as illustrated:
DEFINE DATABASE PROJECT_DB DMS SCHEMA IS PROJECT DMS SUBSCHEMA IS UCOBSUB01 DMS QUALIFIER IS UAHS DMS FILE IS SAMPLE
This example defines the UAHS database named PROJECT_DB to be based on the DMS schema PROJECT contained in the file, UAHS*SAMPLE. The trivial subschema UCOBSUB01 provides UAHS with the details it needs to access the DMS data.
UAHS Table Definition
UAHS tables are built from one or more DMS records related by DMS sets. Fields from the selected records become columns in the table. You can have simple, one-to-one mappings of records-to-tables for cases like stand-alone DMS CALC records. Or mappings can be more complicated, involving up to 5 DMS records. Because of the essential differences in hierarchical and relational structures and the complexity of the DMS environment, the way you define tables can greatly affect UAHS performance. Also, seemingly slight variations in table definitions can produce widely different results for client applications.
A simple table example is a stand-alone CALC record type (i.e., one that doesn’t participate as owner or member of any sets) that would most likely be mapped to a single UAHS table, with each record field mapped to a column in the table.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-17
A slightly more complicated example is the mapping of a simple DMS set comprised of a CALC owner and single member record type. Here, you would map fields from both the owner and member into columns in the same UAHS table. The set relationship would be used by UAHS at run time to pair owner and member record fields to build the table rows.
UAHS imposes the following restrictions on the DMS records used:
• UAHS supports all record location modes. It does not, however, provide any means for using page and record numbers for Direct records. Direct records will only be accessed using an area search or as part of a set traversal.
• Only the DMS system-supplied routines are supported for CALC and Index Sequential record access.
• UAHS cannot handle record types that are stored in more than 13 areas.
• Records may not use implicitly defined data names for areas. The area names must be explicitly defined in the Data Name Section of the schema DDL.
Single-Level Tables
The simplest UAHS table definition is based on a single DMS record. You can define this type of table for any supported record type in your schema. You may choose some or all of the record fields for table columns. If the underlying DMS record is accessible using a key, by including the key items as table columns, you will allow UAHS to use the key to most efficiently access the records. If the record is accessible by set only, all UAHS requests will require area searches (see the discussion of Area Searches on page 14-32).
Here are two examples of single-level tables based on our sample schema.
CREATE TABLE TASK FOR PROJECT_DB.TASK-REC COLUMN TASK_ID IS TASK-REC.TASK-ID COLUMN TASK_NAME IS TASK-REC.TASK-NAME
CREATE TABLE DEPENDANT FOR PROJECT_DB.DEPENDANT-REC COLUMN DEP_NAME IS DEPENDANT-REC.DEP-NAME
Release 10R3: October 31, 2005 14-18 UniAccess for OS 2200 System Administration Guide
In the first example, if the search condition compares TASK_ID to a single value or discrete set of values, then UAHS can fetch the TASK-REC using the TASK-ID CALC key. Otherwise, a search of the entire area, TASK-AREA, is necessary to process the query. In the second example, an area search is always needed because the DEPENDANT-REC has no key.
The TASK and DEPENDANT tables resulting from the above definition statements are shown in Figures 14-4 and 14-5 below.
Row TASK_ID TASK_NAME
1 T0000001 Analysis 2 T0000002 Coding 3 T0000003 Presentation 4 T0000004 Accounting 5 T0000005 Clerical 6 T0000006 Cleaning
Figure 14-4: Single-Level Table — TASK
Row DEP_NAME Row DEP_NAME
1 Carol 9 Anne 2 David 10 Mary 3 Stanley 11 Thomas 4 Mary 12 Marie 5 John 13 Patrick 6 Shirley 14 Anne 7 Elizabeth 15 Joseph 8 Linda 16 Jon
Figure 14-5: Single-Level Table — DEPENDANT
Note that the above tables consist of one row for each DMS record, with the columns in the order specified in the table definition. You will generally find that single-record tables are
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-19
not very meaningful for records whose access mode is via set. Those records depend on their relationship with, and sometimes fields in, related records to be useful. In those cases you need to map the DMS set relationships into your table definitions.
Set Mapping
The majority of tables you will define for UAHS will be multi-level. Multi-level UAHS tables are those that project DMS set hierarchies into a relational form. DMS set relationships are the basis for combining records into tables. You may include up to 5 DMS records in a single UAHS table definition. The records involved must lie in a straight-line hierarchy in the schema. In other words, the records must relate directly to each other as parent, child, grandchild, etc. You may not skip levels (generations) in the hierarchy when defining your tables.
As an example, consider a three-level hierarchy shown in the schema diagram in Figure 14-6.
Record Type 1 Record Type 2
Record Type 3 Record Type 4
Record Type 5
Figure 14-6: Allowable Combinations for UAHS Tables
The allowable combinations for UAHS tables are:
Record 1 and Record 3 Record 1 and Record 4 Record 1, Record 4 and Record 5 Record 2 and Record 4 Record 2, Record 4 and Record 5.
Release 10R3: October 31, 2005 14-20 UniAccess for OS 2200 System Administration Guide
When defining a multi-level table, you must select one record to be the root for your table. It must be at either the lowest or highest level in the set hierarchy spanned by the table. The root record designates the starting point for the DMS access path used by UAHS. Implications of the root record you select are covered in the topic, Root Records on page 14-21
A root record is named in the main clause of the CREATE TABLE command. The other records that comprise the table definition are included implicitly, by mapping items from those records to columns with COLUMN IS clauses.
You will notice also that the mapping of a set relationship into a table is implicit. A set becomes part of a table’s definition because you include related records in the specification. The UAHS utility, TABLEDEF, will check the schema to ensure there is a set that relates the records. If more than one such set exists, UAHS will use the first one listed textually in the SET SECTION of the schema DDL.
The following example illustrates a simple two-level table definition.
CREATE TABLE STAFF FOR PROJECT_DB.OFFICE-REC COLUMN OFFICE IS OFFICE-REC.OFF-NAME COLUMN EMPLOYEE IS EMPLOYEE-REC.EMP-LNAME
In this example, the STAFF table is built from the DMS records OFFICE-REC and EMPLOYEE-REC. OFFICE-REC is the root. Queries can specify the OFFICE column in the selection criteria to allow UAHS to perform a keyed fetch of the OFFICE-REC. Because OFF-NAME is an indexed sequential key, this is true for all comparisons other than inequality (<>, not equal to). The STAFF table would contain the following rows.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-21
Row OFFICE EMPLOYEE
1 Accounting Johnson 2 Accounting Watson 3 Accounting Eastgate 4 Engineering Graves 5 Engineering Yeats 6 Engineering Keating 7 Marketing Matthews 8 Marketing Finney 9 Marketing Rooney 10 Sales Blimps NULL 11 Sales Jets Rich 12 Sales Jets Ward 13 Sales Jets Goodman
Figure 14-7: Two-Level Table — STAFF
Note that the table rows are the owner-member pairs of OFFICEs and EMPLOYEEs, with the OFFICE-REC information repeated for each EMPLOYEE-REC it owns. A row is included for the OFFICE Sales Blimps (the OFFICE-REC that does not have any member EMPLOYEE-RECs), and the EMPLOYEE column for this row is NULL.
Root Records
As stated previously, the root record of a UAHS table is the first one specified in the table definition. The choice of a root record can affect the performance of UAHS as well as the rows it derives for the table. Generally, an application’s requirements will dictate the choice of a root record.
The record you choose for the root must be at the highest or lowest level in the set hierarchy involved by the table. For example, for a three-level table involving a DMS parent, child, and grandchild, only the parent or the grandchild record may be the root (see Figure 14-8).
Release 10R3: October 31, 2005 14-22 UniAccess for OS 2200 System Administration Guide
Root -- owner-driven Parent
Child
Grandchild Root -- member-driven
Figure 14-8: Root Record Selection
We refer to tables with superior root records as owner-driven style tables; those with subordinate root records are called member-driven. You might think of owner-driven tables being accessed from the top of the table hierarchy down and member-driven tables as being accessed from the bottom of the table hierarchy up.
The root record governs the rows that are included in a table when empty sets are involved. For owner-driven tables, the owners of empty sets are always included as table rows, with the member-based columns returned as NULL (assuming, of course, that all other conditions involved in a query are met). In member-driven definitions, owners of empty sets are never included in the table rows. Additionally, if you choose a manual-set member for a table root, unowned members will appear with NULLs in the owner-based columns. For a further discussion of manual set mappings and examples, see the topic, Manual Sets on page 14-25.
The choice of a root record can also have a potentially major impact on performance of queries. For example, choosing a subordinate record for the root of a table would be desirable when the ratio of members to owners is small and the application is interested in data contained in the member record. In this situation, area searches would need only traverse the smaller number of member records, versus the large number of owners that would be traversed if the table were defined as owner-driven.
As an example, consider a three-level table that incorporates our sample OFFICE-REC, EMPLOYEE-REC, and DEPENDANT-REC. The choices for the root are the OFFICE- REC and DEPENDANT-REC. Two possible table definitions are:
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-23
CREATE TABLE INSURED_DOWN FOR PROJECT_DB.OFFICE-REC COLUMN OFF_NAME IS OFFICE-REC.OFF-NAME COLUMN EMP_NAME IS EMPLOYEE-REC.EMP-LNAME COLUMN DEP_NAME IS DEPENDANT-REC.DEP-NAME
CREATE TABLE INSURED_UP FOR PROJECT_DB.DEPENDANT-REC COLUMN OFF_NAME IS OFFICE-REC.OFF-NAME COLUMN EMP_NAME IS EMPLOYEE-REC.EMP-LNAME COLUMN DEP_NAME IS DEPENDANT-REC.DEP-NAME
Figure 14-9 illustrates the resulting INSURED_DOWN table where OFFICE-REC is the root record.
Row OFF_NAME EMP_NAME DEP_NAME
1 Accounting Johnson Carol 2 Accounting Johnson David 3 Accounting Johnson Stanley 4 Accounting Watson NULL 5 Accounting Eastgate Mary 6 Accounting Eastgate John 7 Engineering Graves Shirley 8 Engineering Yates Elizabeth 9 Engineering Yates Linda 10 Engineering Yates Anne 11 Engineering Keating NULL 12 Marketing Matthews NULL 13 Marketing Finney Mary 14 Marketing Finney Thomas 15 Marketing Rooney Marie 16 Marketing Rooney Patrick 17 Sales Blimps NULL NULL 18 Sales Jets Rich Anne 19 Sales Jets Rich Jospeh
Release 10R3: October 31, 2005 14-24 UniAccess for OS 2200 System Administration Guide
Row OFF_NAME EMP_NAME DEP_NAME
20 Sales Jets Ward Jon 21 Sales Jets Goodman NULL
Figure 14-9: Owner-Driven Set Mapping — INSURED_DOWN
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.
Figure 14-10 illustrates the resulting INSURED_UP table where DEPENDANT-REC is the root record.
Row OFF_NAME EMP_NAME DEP_NAME
1 Accounting Johnson Carol 2 Accounting Johnson David 3 Accounting Johnson Stanley 4 Accounting Eastgate Mary 5 Accounting Eastgate John 6 Engineering Graves Shirley 7 Engineering Yates Elizabeth 8 Engineering Yates Linda 9 Engineering Yates Anne 10 Marketing Finney Mary 11 Marketing Finney Thomas 12 Marketing Rooney Marie 13 Marketing Rooney Patrick 14 Sales Jets Rich Anne 15 Sales Jets Rich Joseph 16 Sales Jets Ward Jon
Figure 14-10: Member-Driven Set Mapping — INSURED_UP
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-25
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 owner-driven version are excluded from the member-driven version.
Manual Sets
UAHS allows manual set relationships to be the basis for table definitions. (Manual sets are subordinate records that can exist without owners.) With respect to empty sets and NULL columns, tables will behave the same as with automatic sets. Additionally, when manual sets are mapped as member-driven tables, un-owned members will appear as rows with NULL in the owner-based columns.
The following are definitions of a two-level table based on the manual set EMP-TASK- SET in the sample schema. The first table designates the owner EMPLOYEE-REC as the root; the second designates the manual member TASK-REC as the root.
CREATE TABLE ASSIGNMENTS_DOWN FOR PROJECT_DB.EMPLOYEE-REC COLUMN EMP_LNAME IS EMPLOYEE-REC.EMP-LNAME COLUMN TASK_NAME IS TASK-REC.TASK-NAME
CREATE TABLE ASSIGNMENTS_UP FOR PROJECT_DB.TASK-REC COLUMN EMP_LNAME IS EMPLOYEE-REC.EMP-LNAME COLUMN TASK_NAME IS TASK-REC.TASK-NAME
Figure 14-11 and Figure 14-12 illustrate the resulting tables.
Release 10R3: October 31, 2005 14-26 UniAccess for OS 2200 System Administration Guide
Row EMP_LNAME TASK_NAME
1 Johnson Accounting 2 Watson NULL 3 Eastgate NULL 4 Graves Analysis 5 Graves Coding 6 Yeats NULL 7 Keating NULL 8 Matthews NULL 9 Finney NULL 10 Rooney Presentation 11 Rich NULL 12 Ward NULL 13 Goodman NULL
Figure 14-11: Owner-Driven Manual Set Mapping — ASSIGNMENTS_DOWN
Notice that in the owner-driven version, the resulting table rows would be the same if the EMP-TASK-SET were an automatic set.
Row EMP_LNAME TASK_NAME
1 Graves Analysis 2 Graves Coding 3 Rooney Presentation 4 Johnson Accounting 5 NULL Clerical 6 NULL Cleaning
Figure 14-12: Member-Driven Manual Set Mapping — ASSIGNMENTS_UP
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-27
Notice that NULL is returned in the EMP-LNAME column where the TASK-REC is unowned in the sample data (shown in Figure 14-3 on page 14-14).
Column Definition
UAHS table columns are defined with COLUMN…IS clauses of the CREATE TABLE command. This clause maps DMS record fields to UAHS table columns. The following rules apply to UAHS table columns:
• You may include some or all fields from a record as table columns.
• Columns will be ordered in the sequence used on the CREATE TABLE statement.
• UAHS table columns inherit their ODBC datatype based on the type of the DMS item defined by its PICTURE and/or USAGE clauses. For specifics, see Chapter 9 of the UniAccess for OS 2200 Client Guide.
• UAHS does not support items that are defined as Exact Binary (PIC 1), Long Character (DISPLAY-2), Edited (PIC editing symbols), or Fieldata (DISPLAY-1, COMP-4).
• The maximum length of an item that can be mapped to a UAHS table column is 255 characters.
• Because group items are not valid relational constructs, the fields you specify must be elementary items in your schema.
• Subscripted items (referred to as arrays, tables, occurs items) are not valid relational entities, either. You must map each array entry to an individual table column by specifying the entry and its subscript.
• As with non-subscripted items, you may choose to map only some of an array’s entries in a table.
• Array entries need not be mapped in sequential order.
• UAHS support for arrays is limited to a single dimension, or subscript.
Release 10R3: October 31, 2005 14-28 UniAccess for OS 2200 System Administration Guide
The behavior of character columns is governed by UniAccess configuration. Configuration options control the disposition of trailing spaces, embedded special characters, and the conversion of DMS fixed-point binary values. These are configurable on the host system through the UniAccess Configuration File and on the client through the UADriver Setup/ UAHS Setup Options dialog. Refer to Chapter 16, (HIERSRV and UAUSER statements) and Chapter 5 of the UniAccess for OS 2200 Client Guide for details.
The following example illustrates column definitions that include array items:
CREATE TABLE ACTIVITIES FOR PROJECT_DB.TASK-REC COLUMN TASK_NAME IS TASK-REC.TASK-NAME COLUMN ACT1 IS TASK-REC.TASK-ACTIVITY(1) COLUMN ACT2 IS TASK-REC.TASK-ACTIVITY(2) COLUMN ACT3 IS TASK-REC.TASK-ACTIVITY(3) COLUMN ACT4 IS TASK-REC.TASK-ACTIVITY(4)
The ACTIVITIES table would contain the following data.
Row TASK_NAME ACT1 ACT2 ACT3 ACT4
1 Analysis Design Review 2 Coding Prototype Construct Test Optimize 3 Presentation Demo Meeting 4 Accounting Budget Payroll 5 Clerical WP Admin 6 Cleaning Windows Floors Trash
Figure 14-13: Array Mapping — ACTIVITIES
Notice that we chose to include all four occurrences of the TASK-ACTIVITY array item in the table. In several rows, the third and fourth columns are blank because the items are not used (spaces) in the record.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-29
NULLs
As illustrated above, UAHS uses the concept of NULL in the DMS environment. NULL is used for columns that have no corresponding DMS record in certain empty and manual set situations. In the previous discussions, we showed two instances where UAHS returns columns as NULL:
• Empty sets where the owner is the table root
• Un-owned manual members where the member is the table root.
Extending the concept, UAHS supports the use of the IS [NOT] NULL predicate of the SQL SELECT statement. The NULL predicate provides for specification of NULL columns in the search condition. For a UAHS client, this translates into the ability to select data based on the existence or non-existence of owners or members.
In our sample, a UAHS client can select all offices that don’t have any employees by issuing
SELECT OFF_NAME FROM INSURED_DOWN WHERE EMP_LNAME IS NULL
and the result set would be the single row:
Sales Blimps
Another example would be to find all unassigned tasks with
SELECT * FROM ASSIGNMENTS_UP WHERE EMP_LNAME IS NULL
and the result set would be:
NULL Clerical NULL Cleaning
Release 10R3: October 31, 2005 14-30 UniAccess for OS 2200 System Administration Guide
Retrieval Methods
UAHS can retrieve DMS data either by using record keys or by searching DMS areas. The retrieval method to be used is determined by a combination of the location mode of a table’s underlying DMS records and the search criteria supplied in a query. This section describes the specific conditions for each method used by UAHS. It also explains the circumstances under which area searches are performed and how to limit or prevent their use to avoid potential performance impact.
Keyed Fetches
In the UAHS meta database, the UAHS utilities SCHEMADEF and TABLEDEF identify the CALC and index sequential key(s) for each DMS record and the columns that are mapped to those keys. UAHS uses this information to allow queries to take advantage of those keys. Client applications can use ODBC catalog functions to find out which table columns are key items.
When a key-based column value is supplied in a search condition, UAHS fetches the underlying DMS records using the keys. Set relationships are then used to obtain other related records that are involved in the table, if necessary. For example, the command
SELECT * FROM INSURED_DOWN WHERE OFF_NAME = ‘Accounting’
causes UAHS to fetch the OFFICE-REC using the key, OFF-NAME with a value of Accounting. The set OFF-EMP is traversed to get the member EMPLOYEE-RECs. For each of those records, the set EMP-DEP is traversed to get member DEPENDANT-RECs.
Note that subordinate record keys are also be used by UAHS, when they are available and specified in the search criteria. In such cases, UAHS fetches the subordinate record with the key and then fetches the owner record via set.
The degree to which UAHS can take advantage of DMS record keys depends on the access mode of the records and the type of expression used in a query. Note that UAHS attempts to optimize access when different record types and expressions are involved. It has some minimal intelligence to determine if there is a criterion for a keyed record fetch anywhere in the search condition. It will perform the keyed fetch and use set relationships to obtain related records, if necessary.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-31
For both CALC and index sequential records, UAHS uses a keyed fetch when the selection criteria specifies a value or discrete set of values for the key item (comparison operator =). Any duplicates that may exist for the key value are also fetched. UAHS checks all areas where the record is stored to handle situations where the same key value can be stored in more than one area.
Index sequential range keys may be used, but in the case where a range key is comprised of more than one DMS record item, UAHS supplies the DMR with the most significant components of the key. However, supplying only some of the range key is an efficiency consideration since the number of records accessed to satisfy the search criteria affects the overall search path.
Queries that involve only via set records, or that don’t supply any record keys in the search criteria, do not allow UAHS to use any type of keyed access. In these situations, area searching is necessary.
The following table summarizes the circumstances under which keyed access can be used by UAHS for all possible combinations of data items and expressions.
Table 14-2: Keyed Access and Area Search Criteria
DMS Item Type in Expression Type WHERE Clause = not = (<>) Others (<, >, <=, >=)
CALC Key Keyed Access Area Search Area Search Index Sequential Key Keyed Access Area Search Area Search Index Sequential Range Key Keyed Access1 Area Search Area Search Non-key (or no WHERE clause) Area Search Area Search Area Search
1 The most significant portion specified will be used.
Release 10R3: October 31, 2005 14-32 UniAccess for OS 2200 System Administration Guide
Area Searches
Area searching, as the name indicates, is the ability for UAHS to traverse entire DMS areas to find the record(s) it needs. Area searches are needed when a SELECT statement’s WHERE clause does not include columns and conditions to identify a unique CALC or Index Sequential fetch condition. Area searches are not necessarily limited to a single area, but may span all areas that contain the records UAHS is looking for. UAHS must perform area searches in the following situations:
• No search condition (WHERE clause) is specified for a SELECT statement.
• The records involved in a query are accessible via set only.
• The search criteria specify non-key items only.
UAHS may also require an area search when keys are specified in the search criteria, but the expressions do not use equality. Table 14-2 in the previous section summarizes the situations. For example, the statement
SELECT * FROM TASK
requires UAHS to traverse the area, TASK-AREA, to get all the records to satisfy the query.
The statement,
SELECT * FROM INSURED_UP WHERE DEP_NAME = ‘John’
causes UAHS to traverse the DEP-AREA, searching for DEPENDANT-RECs where the field DEP-NAME has a value of John. The sets EMP-DEP and OFF-EMP are used to obtain the corresponding owner EMPLOYEE-REC and OFFICE-REC fields.
AREASEARCH Configuration Setting
We recommend that you limit the availability of area searches wherever possible because they can have a significant impact on your system. This is a particular consideration when you use ODBC tools that provide ad-hoc data access. You can limit some searches by defining tables that include unique record keys.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-33
The ability for UAHS to perform an area search is governed by UniAccess configuration, both on the host system and in the ODBC data source. On the host, the HIERSRV AREASEARCH parameter governs area searching at the highest level, the UAHS service level. When this parameter setting is YES, area searches are permitted for UAHS transactions. The UAUSER AREASEARCH parameter can override the HIERSRV entry and allow or deny area searches for individual users. On the workstation, the UniAccess ODBC Drive set up for a UAHS data source has a setup option, Perform area search, that may override the host settings. You can prohibit such overrides in the host configuration. (For more information on host configuration and overrides, see Chapter 16, UniAccess Source Configuration Statement Reference. The UniAccess ODBC Driver settings are covered in Chapter 5 of the UniAccess for OS 2200 Client Guide.)
If UAHS receives a query that it determines cannot be satisfied without an area search, it verifies the setting of the AREASEARCH parameter. If it is not set to allow such searches, the query is rejected.
Security
The UniAccess System, including UAHS, co-exists with any of the Unisys Security Options with or without TIP session control. The UniAccess System provides some additional facilities for security as well. Security in the UniAccess System is discussed in Chapter 9. Issues specific to DMS Security are discussed here.
UAHS Mapping Techniques
A simple but effective way of preventing UAHS clients from accessing sensitive DMS data is to exclude those records from table definitions in UAHS databases. You can define multiple UAHS databases, including in each one only mappings of those DMS records that the users of that database are permitted access. The UniAccess host configuration items HIERSRV SCHEMAH and UAUSER SCHEMAH can then be used to restrict the UAHS databases that users can access (see Chapter 16).
Similarly, you can exclude selected record fields from mappings to table columns, protecting sensitive data at the individual item level.
Release 10R3: October 31, 2005 14-34 UniAccess for OS 2200 System Administration Guide
Note The DMS security mechanisms govern UAHS access to data only. Access to catalog information (in the UAHS meta database) can only be restricted by limiting user access to databases, as just described.
DMS Security Support
With respect to database security options supplied by DMS, the following table summarizes UAHS support for the various options available in the DDL/SDDL syntax.
Table 14-3: UAHS Support for DDL/SDDL Syntax
DDL/SDDL Mechanism UAHS Support
Subschema LOCK FOR INVOKE IS literal Not supported. UAHS is not compiled with the subschema, so LOCK FOR INVOKE is not enforced. ACCESS CONTROL LOCK IS literal Not supported. UAHS incurs an access control violation. ACCESS CONTROL LOCK IS PROCEDURE Supported at all levels. Optional ACCESS db-procedure CONTROL KEY IS data-name cannot be used. ACCESS CONTROL LOCK IS ACR-NAME Supported at all levels. acr-name
Notice that UAHS can interoperate with the schema ACCESS CONTROL LOCK specification at all levels available in DMS (schema, area, record, item, set, and set member), provided the controls use database procedures or access control records. It does not support ACCESS CONTROL LOCK entries that specify literals or data names. If UAHS attempts to access an item protected this way, an access control violation will occur.
Note TIP session control must be configured in order for ACR-NAME locks to function correctly, or if site-supplied database procedures depend upon a userid.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-35
UAHS Guidelines and Restrictions The following is a summary of guidelines and restrictions for using UAHS, presented here for ease of reference. It highlights many of the important points about UAHS support for DMS 2200 that were detailed previously in the chapter.
As administrator, you should also be aware of the functionality available to client tools and programs that will be using UAHS to access DMS 2200. Those points are highlighted here as well. (Details of UAHS client operations are covered in Chapter 9 of the UniAccess for OS 2200 Client Guide.)
Table 14-4: UAHS Functionality
Issue Reference
1 UAHS provides ODBC-like access to DMS data. page 14-2 page 14-9 2 UAHS access is read-only. page 14-2 3 UAHS restricts access to simple selections based on comparisons, with limited page 14-2 sorting and summarizing. 4 UAHS supports both ODBC and Open Client APIs. page 14-2
Table 14-5: DMS Schema/Subschema Support
Issue Reference
1 UAHS can support one schema per OS 2200 application group. page 14-7 2 UAHS requires a trivial UCS COBOL subschema; but is not aware of entities page 14-16 or attributes defined in the SDDL, including access control items. 3 Schema changes must always be propagated to the UAHS Meta Database. page 14-8
Release 10R3: October 31, 2005 14-36 UniAccess for OS 2200 System Administration Guide
Table 14-6: Restrictions on Schema Entities
Issue Reference
1 UAHS does not support implicitly defined database data names. page 14-17 2 UAHS does not support accessing records directly (using database keys). page 14-17 3 UAHS supports only DMS-supplied CALC and Index Sequential routines. User page 14-17 routines are not supported. 4 UAHS does not support records defined with MODE FIELDATA 5 UAHS has a 13-area limit for multi-area DMS records. page 14-17 6 The maximum length of a UAHS table column is 255 characters. page 14-27 7 Only elementary DMS record items can be mapped to UAHS table columns. page 14-27 8 DMS OCCURS items must be individually mapped to columns. page 14-27 9 UAHS supports only single-dimension (subscript) OCCURS items. page 14-27 10 UAHS does not support exact binary (BIT) items. page 14-27 11 UAHS can use only 10 or fewer items for a multi-item DMS record key. 12 UAHS cannot access entities that specify an ACCESS CONTROL LOCK literal. page 14-31 13 UAHS cannot access entities that specify the optional ACCESS CONTROL KEY for page 14-31 ACCESS CONTROL LOCK procedures.
Note Unsupported entities can exist in the schema used by UAHS, provided the entities themselves are not used by UAHS.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-37
Table 14-7: Relational Mapping Guidelines
Issue Reference
1 A UAHS table mapping is limited to 5 DMS records. page 14-19 2 All records in a table mapping must lie on a straight-line hierarchical path in the schema. page 14-19 3 UAHS uses the first set listed in the SET SECTION to relate records in a table page 14-20 mapping. 4 Empty sets can be a source of NULL column values. page 14-29 5 Table mappings should include record keys whenever possible. page 14-32 page 14-30
Table 14-8: SQL Syntax Rules
Issue*
1 UAHS supports only the SQL SELECT verb. 2 SELECT statement syntax is limited to a subset of ODBC SQL Minimum Grammar. 3 Join operations are limited to 3 tables. 4 Select lists are limited to 255 columns. 5 Select list columns cannot be aliased using AS. 6 Arithmetic operations are not permitted. 7 Parentheses are not permitted. 8 Single quotes must be used to delineate literal strings. 9 Delimited identifiers are not supported. 10 The DISTINCT modifier can only be used with a single column. 11 The ORDER BY clause is limited to a single column. 12 The IN, BETWEEN, and EXISTS predicates are not available. 13 The ESCAPE clause of the LIKE predicate is not available. 14 The GROUP BY and HAVING clauses are not available. * All of the issues listed in this table are discussed in Chapter 9 of the UniAccess for OS 2200 Client Guide.
Release 10R3: October 31, 2005 14-38 UniAccess for OS 2200 System Administration Guide
Issue*
15 SQL built-in functions (MIN, MAX, DATE, USER etc.) are not available. 16 Subqueries are not permitted. 17 The set UNION operation is not available. 18 NULLs in the UAHS environment are non-existent DMS records. * All of the issues listed in this table are discussed in Chapter 9 of the UniAccess for OS 2200 Client Guide.
SCHEMADEF and TABLEDEF Reference This section details the execution syntax for the SCHEMADEF and TABLEDEF utilities and describes the format of the TABLEDEF data definition commands.
SCHEMADEF
SCHEMADEF is the UniAccess System utility that translates DMS schema information into the UAHS Meta Database. Input to the program is the TIP file number of the Meta Database, followed by the symbolic schema definition commands (DDL). Usually, the schema symbolic is the same source that was input to the DDL processor to create the existing DMS schema.
The utility builds the UAHS internal tables and writes the structures to the TIP file. It lists execution results and can produce reports of the schema information stored in the TIP file.
SCHEMADEF is executed as follows:
@xqt,options qual*file.SCHEMADEF Enter Tip file number: [TIP-file-number] TIP file nn will be initialized. Re-enter file number to confirm: [TIP-file-number verification] [schema symbolic] @eof
where:
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-39
options are one or more of the following:
H display SCHEMADEF help and version information.
I initialize the Meta Database file and input a DMS schema definition. This is the only SCHEMADEF option that writes to the TIP file. It requires an input schema symbolic.
Specifying this option will erase the existing schema definition and relational mappings from the UAHS Meta Database.
L produce the most comprehensive listing.
M produce a map of the UAHS Meta Database.
N produce no listing.
R produce a schema report.
S produce a short listing.
qual*file is the name of the file where the SCHEMADEF utility is located. For a production mode install, the default file name is SYS$LIB$*UAUTIL; for a test mode install, the default file name is SYS$LIB$*UAUTILT.
[TIP-file-number] is the TIP file number of the UAHS Meta Database. This TIP file should have been created previously by the system administrator (see UAHS Meta Database Procedures on page 14-4).
[TIP-file-number-verification] is the same number as the TIP-file-number. The utility prompts for this number when the ‘I’ option is used as a safeguard against unintentionally re-initializing a Meta Database file.
Release 10R3: October 31, 2005 14-40 UniAccess for OS 2200 System Administration Guide
schema symbolic is the DDL script representing the schema. Typically, this will be an @ADD of the DMS schema source. This item is only used in conjunction with the ‘I’ option.
@eof terminates SCHEMADEF input scan.
SCHEMADEF Example
The following commands are an example of running SCHEMADEF:
@XQT,IN SYS$LIB$*UAUTIL.SCHEMADEF UAHS Schema Definition Utility (SCHEMADEF) 10R3-0 Enter Tip file number of the UAHS meta database: 24 TIP file: 24 will be initialized. Re-enter file number to confirm: 24 @ADD PRODUCTION*SCHEMAS.PAYROLL TIP file: 24 initialized @EOF END SCHEMADEF. ERRORS 0
In this example, SCHEMADEF will process the DDL contained in the element PAYROLL of the file PRODUCTION*SCHEMAS. The schema information will be written to TIP file #24. No listing will be output. Notice that the SCHEMADEF program is found in the default file for a production UniAccess installation, SYS$LIB$*UAUTIL. The above commands can be run in either demand or batch.
TABLEDEF
TABLEDEF is the UniAccess System utility used to define relational-type representations of a DMS schema. It is executed after SCHEMADEF to update the UAHS Meta Database with this information. Input to the program is the Meta Database TIP file number, followed by database and table definition entries (and related item drop commands).
The utility writes (or removes) the relational entries to (from) the file. It lists execution results and can produce reports of the relational mappings stored in the file. The TABLEDEF utility verifies that data definition commands follow the syntax and rules
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-41
presented in this section. If the utility finds an error, a message is displayed on the terminal executing the program. (Error messages returned by the TABLEDEF utility are documented in Appendix D, beginning on page D-60.) In general, if there are errors in the definition of a database or table, all updates made for the errant item are rolled back and the item’s definition is dropped.
TABLEDEF is executed as follows:
@xqt,options qual*file.TABLEDEF Enter Tip file number: [TIP-file-number] [data definition entries] @eof
where:
options are one or more of the following:
H display TABLEDEF help and version information.
L produce the most comprehensive listing.
N produce no listing.
R produce a record/table report.
S produce a short listing.
qual*file is the name of the file where the TABLEDEF utility is located. For the production mode install, the default file name is SYS$LIB$*UAUTIL; for the test mode install, the default file name is SYS$LIB$*UAUTILT.
[TIP-file-number] is the TIP file number of the UAHS Meta Database. This TIP file must have been created by the system administrator (see UAHS Meta Database Procedures on page 14-4) and have had the DMS DDL information entered by the SCHEMADEF utility.
Release 10R3: October 31, 2005 14-42 UniAccess for OS 2200 System Administration Guide
data definition entries are commands that map a DMS schema to databases, tables, and columns needed by UAHS to process SQL requests. Typically, the entries are maintained in a symbolic element and @ADDed here. The format of entries is summarized below and detailed in the next section:
DEFINE DATABASE db_name DMS SCHEMA[IS] schema-name DMS SUBSCHEMA[IS] subschema-name [DMS QUALIFIER[IS] qualifier] DMS [TIP] FILE[IS] {filename | TIP file number}
CREATE TABLE table_name [FOR] db_name.root-record COLUMN column_name1[IS] data-record1.data-item1[(i)] COLUMN column_name2[IS] data-record1.data-item2[(i)] COLUMN column_name3[IS] data-record2.data-item1[(i)] . . . COLUMN column_namen [IS] data-record5.data-itemn[(i)] ( where i is subscript value for occurs item)
DROP TABLE db_name.table_name
DROP ALL TABLES[IN] db_name
DROP DATABASEdb_name
Note A set of DEFINE/CREATE commands may be repeated for each UAHS database you wish to define, based on a single DMS schema.
@eof terminates TABLEDEF input scan.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-43
TABLEDEF Data Definition Entries The commands discussed in this section are used to define the relational-type items that will be accessible to client applications using the UAHS service. The commands essentially map DMS hierarchical entities to relational counterparts.
The following rules apply to TABLEDEF entries:
• Each input image (line) is limited to 80 characters.
• Any amount of white space is permitted where the syntax shows one or more spaces.
• The words DEFINE, CREATE, and DROP are considered TABLEDEF keywords.
• An entry is terminated when a new keyword is encountered or TABLEDEF is terminated.
• Each keyword should begin on a new input line.
• The items db_name, table_name, and column_name are considered TABLEDEF identifiers.
• Keywords and identifiers are case-insensitive.
• The maximum length of an identifier is 30 characters.
• The order of the clauses in an entry should be as presented here.
• Identifiers must conform to standard SQL naming conventions, and may not be SQL reserved words or TABLEDEF keywords. (TABLEDEF reserved words are listed on page 14-48.)
Valid SQL names are from 1 to 30 characters, with the first character an alphabetic (a—z, A—Z). The remaining characters can include letters, digits, or the underscore ( _ ) symbol. No other symbols, special characters, or embedded spaces are allowed. Although lower case letters are permitted in names, UAHS and its utilities are case-insensitive.
Release 10R3: October 31, 2005 14-44 UniAccess for OS 2200 System Administration Guide
Database Definition Entry
The database definition entry provides UAHS with the location of DMS schema and subschema information. It maps a UAHS database name to that information. A UAHS database must be defined before any tables can be mapped to DMS records.
Format
DEFINE DATABASE db_name DMS SCHEMA [IS] schema-name DMS SUBSCHEMA [IS] subschema-name [DMS QUALIFIER [IS] qualifier] DMS [TIP] FILE [IS] {filename | TIP file number}
where:
db_name is the UAHS database name. The name must be a valid SQL name. This becomes the ODBC qualifier name (or catalog name) used by client applications.
schema-name is the name of the DMS schema absolute. To ensure integrity, the absolute must have been built from the same symbolic that was input to the SCHEMADEF utility (see the previous section).
subschema-name is the name of the subschema absolute that will be used by UAHS to access the DMS data. It must be a trivial UCS COBOL subschema of the given schema.
qualifier, filename are the qualifier and filename of the file containing the DMS schema and subschema absolutes. These items are not used with TIP files.
TIP file number is the TIP file number where the schema and subschema elements are found when the optional [TIP] entry is used in the syntax.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-45
Example
DEFINE DATABASE UAHSDB DMS SCHEMA IS PAYROLL DMS SUBSCHEMA IS PAYSUB DMS TIP FILE IS 24
In the example, the information contained in the PAYROLL schema, contained in TIP file number 24, will be available as a UAHS database named UAHSDB. The trivial subschema PAYSUB will be used to access the DMS data.
Table Definition Entry
Table definition entries are used to map DMS records to UAHS tables. The fields of DMS records are mapped to columns in UAHS tables. Up to 5 DMS record types can be defined to be a single UAHS table. The records must lie in a straight-line hierarchical path in the DMS schema.
Format
CREATE TABLE table_name [FOR] db_name.root-record COLUMN column_name1 [IS] data-record1.data-item[(i)] COLUMN column_name2 [IS] data-record1.data-item[(i)] COLUMN column_name3 [IS] data-record2.data-item[(i)] . . . COLUMN column_namen [IS] data-record5.data-itemn[(i)]
where:
table_name is the name being assigned to the table being defined. The name must be a valid SQL name. This is the name that will be used by client applications.
db_name is the UAHS database to which the table belongs. This must be a database previously defined with the DEFINE DATABASE entry as discussed in the previous section.
Release 10R3: October 31, 2005 14-46 UniAccess for OS 2200 System Administration Guide
column_name1…column_namen are the names being assigned to the columns of the table. They must be valid SQL names. These are the names available to client applications.
root-record The DMS record used by UAHS to determine the DMS access path to the records involved in the table. This record must be superior or subordinate to all other records named in the table definition. (Refer to the section Root Records on page 14-21 for implications of your root record selection.)
data-record1…data-recordn are the names of DMS records in the schema mapped by db_name. These are the records to be mapped to this table. They must lie in a straight-line path in the schema. The root-record may be included as a data-record here.
data-item[(i)] are the names of record fields to be mapped to table columns. The fields must exist as elementary items within the specified data record.
(i) is the subscript value for the data-item, when it is defined with an OCCURS clause in the schema. n must be within the allowable range for the subscript. Currently only one dimensional arrays are supported.
Example
CREATE TABLE EMPLOYEE FOR UAHSDB.EMPLOYEE-REC COLUMN START_DATE IS EMPLOYEE-REC.EMP-START-DATE COLUMN SSN IS EMPLOYEE-REC.EMP-SSN COLUMN FIRST_NAME IS EMPLOYEE-REC.EMP-FIRST-NAME COLUMN LAST_NAME IS EMPLOYEE-REC.EMP-LAST-NAME COLUMN DEPARTMENT IS DEPARTMENT-REC.DEPT-NO
In this example, a table, EMPLOYEE, is defined to consist of fields from two different DMS records, EMPLOYEE-REC and DEPARTMENT-REC. Note that those records must be related by a set in the DMS schema, and that the database UAHSDB must have been previously defined using the DEFINE DATABASE entry.
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-47
Deleting Mappings
The DROP commands are available for removing mappings from the UAHS Meta Database. When you want to change the mapping of a database or table, you must first DROP its definition and then use updated DEFINE and/or CREATE entries for the item. As with the CREATE commands, the DROP commands do not affect the underlying DMS schema or data.
When using an ASCII file as input script to TABLEDEF, it is often desirable to precede each CREATE entry with its corresponding DROP command.
Syntax
DROP DATABASE db_name This command removes the definition for the database named db_name from the UAHS Meta Database. All table definitions that are part of that database are deleted as well.
DROP TABLE db_name.table_name This command deletes the definition of the table, table_name, from the database, db_name.
DROP ALL TABLES IN db_name This command deletes the definition of all tables defined in the database named db_name.
Drop Examples
The following examples assume that a database mydb has been defined and two tables, mytable1 and mytable2, have been created. Each example below would achieve the same result.
a. DROP TABLE mydb.mytable1 DROP TABLE mydb.mytable2 DROP DATABASE mydb
b. DROP ALL TABLES IN mydb DROP DATABASE mydb
c. DROP DATABASE mydb
Release 10R3: October 31, 2005 14-48 UniAccess for OS 2200 System Administration Guide
TABLEDEF Reserved Words
This is a list of TABLEDEF reserved words. These words have special meaning to the TABLEDEF utility, because they are either TABLEDEF keywords (verbs like DEFINE, CREATE) or SQL reserved words. You cannot use these words as TABLEDEF identifiers (UAHS entity names) in data definition commands.
Table 14-9: TABLEDEF Reserved Word List
A-D D-I I-R R-Y
ABSOLUTE DECLARE IS ROWS ACTION DEFAULT ISOLATION SCHEMA ADA DEFERRABLE JOIN SCROLL ADD DEFINE KEY SECOND ALL DERERRED LANGUAGE SECTION ALLOCATE DELETE LAST SELECT ALTER DESC LEADING SEQUENCE AND DESCRIBE LEFT SESSION ANY DESCRIPTOR LEVEL SESSION-USER ARE DIAGNOSTICS LIKE SET AS DISCONNECT LOCAL SIZE ASC DISTINCT LOWER SMALLINT ASSERTION DMS MATCH SOME AT DOMAIN MAX SPACE AUTHORIZATION DOUBLE MIN SQL AV G DROP MINUTE SQLCA BEGIN ELSE MODULE SQLCODE BETWEEN END MONTH SQLERROR BIT END-EXEC MUMPS SQLSTATE BIT_LENGTH ESCAPE NAMES SQLWARNING BOTH EXCEPT NATIONAL SUBSCHEMA BY EXCEPTION NATURAL SUBSTRING
Release 10R3: October 31, 2005 UniAccess Hierarchical Service 14-49
A-D D-I I-R R-Y
CASCADE EXEC NCHAR SUM CASCADED EXECUTE NEXT SYSTEM_USER CASE EXISTS NO TABLE CAST EXTERNAL NONE TEMPORARY CATALOG EXTRACT NOT THEN CHAR FALSE NULL TIME CHAR_LENGTH FETCH NULLIF TIMESTAMP CHARACTER FILE NUMERIC TIMEZONE_HOUR CHARACTER_LENGTH FIRST OCTET_LENGTH TIMEZONE_MINUTE CHECK FLOAT OF TIP CLOSE FOR ON TO COALESCE FOREIGN ONLY TRAILING COBOL FORTRAN OPEN TRANSACTION COLLATE FOUND OPTION TRANSLATE COLLATION FROM OR TRANSLATION COLUMN FULL ORDER TRIM COMMIT GET OUTER TRUE CONNECT GLOBAL OUTPUT UNION CONNECTION GO OVERLAPS UNIQUE CONSTRAINT GOTO PAD UNKNOWN CONSTRAINTS GRANT PARTIAL UPDATE CONTINUE GROUP PASCAL UPPER CONVERT HAVING PLI USAGE CORRESPONDING HOUR POSITION USER COUNT IDENTITY PRECISION USING CREATE IMMEDIATE PREPARE VA L U E CROSS IN PRESERVE VALUES CURRENT INCLUDE PRIMARY VARCHAR
Release 10R3: October 31, 2005 14-50 UniAccess for OS 2200 System Administration Guide
A-D D-I I-R R-Y
CURRENT_DATE INDEX PRIOR VA RY I N G CURRENT_TIME INDICATOR PRIVILEGES VIEW CURRENT_TIMESTAMP INITALLY PROCEDURE WHEN CURRENT_USER INNER PUBLIC WHENEVER CURSOR INPUT QUALIFIER WHERE DATE INSENSITIVE REFERENCES WITH DAY INSERT RELATIVE WORK DATABASE INTEGER RESTRICT YEAR DEALLOCATE INTERSECT REVOKE DEC INTERVAL RIGHT DECIMAL INTO ROLLBACK
Release 10R3: October 31, 2005 15 UADTC 15 UniAccess Distributed Transaction Coordinator
This chapter provides an overview of UniAccess support for distributed transactions, including information on recovering participating transactions. It also defines the syntax of command lines to execute the UniAccess Integrated Recovery Utility (UAIR), and explains how to use UAIR in interactive mode.
Topics Page
Distributed Transaction Support 15-1 Recovery 15-3 Standard OS 2200 Recovery 15-6 Application Group Recovery Procedures 15-7 Executing UAIR 15-10 UAIR in Interactive Mode 15-11
Distributed Transaction Support 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.
Distributed transactions are transactions that update data on two or more networked servers, known as resource managers. The management of the transaction must be coordinated between the resource managers by a server component called a transaction
Release 10R3: October 31, 2005 15-2 UniAccess for OS 2200 System Administration Guide
manager. UniAccess on the OS 2200 can operate as a resource manager in distributed transactions coordinated by the Microsoft transaction manager—Microsoft Distributed Transaction Coordinator (MS DTC), in conjunction with the UniAccess transaction manager—UniAccess Distributed Transaction Coordinator (UADTC). MS DTC is the primary or root transaction manager. UADTC performs as a secondary transaction manager (see Figure 15-1).
Windows 2000 (or later) Secondary Transaction Manager Transaction Internet Protocol
MS DTC COM+ Environment UADTC Primary COM+ Transaction Manager Component using TDS UADriver
O D B C /T D MS SQL Server S OS 2200 (or other data (UniAccess source) data source) Resource Manager Resource UACS Manager
TIP Environment
SQL Data UDS/ UASL TIP FCSS Transaction Data
Figure 15-1: UniAccess Distributed Transaction Processing
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-3
When distributed transactions complete normally, they follow a two-phase commit (2PC) protocol. The first commit phase of a distributed transaction is a PREPARED state (ready to commit). The second commit phase is to either commit or abort (rollback) the transaction. In the Microsoft/UniAccess implementation, MS DTC is responsible for issuing the prepare, commit and abort commands. UADTC relays these requests to UACS.
Note For more information on distributed transactions and the UniAccess/Microsoft implementation of distributed transaction processing, see Chapter 13 of the UniAccess for OS 2200 Client Guide. For Microsoft references, see Appendix G.
Recovery In the UniAccess environment, Server-Library transactions that are not participating in a distributed transaction (non-participating transactions) are recoverable if they have reached a commit point. Server-Library transactions that are participating in a distributed transaction (participating transactions) are recoverable if they have reached either a ready state (PREPARED) or a commit point. Recovery of both participating and non- participating transactions is dependent upon OS 2200 recovery of the application group. Some potential problems, which would require OS 2200 recovery are:
• An operating system failure, which initiates a reboot of the OS 2200 environment
• A hardware failure, which initiates a reboot of the OS 2200 environment
• A software failure, which requires recovery of the application group
• A hardware failure, which requires recovery of the application group.
OS 2200 and application group recovery are discussed in the following sub-sections.
Release 10R3: October 31, 2005 15-4 UniAccess for OS 2200 System Administration Guide
Note Database locks held by distributed transactions, and database updates applied by distributed transactions, persist until the distributed transaction is either committed or aborted. These locks and updates persist even if a participating transaction is no longer active on the system (e.g., the transaction terminated without committing or omitting its updates, or the transaction state was recovered by OS 2200 recovery.)
Following a successful OS 2200 recovery, the transaction managers (MS DTC and UADTC) are responsible for issuing the final commit or abort request. In some rare instances, recovery of a participating transaction may require manual intervention. Some potential situations that may require manual intervention are:
• Recovery failure. This situation may result if either the OS 2200 or MS DTC environment (see Figure 15-2) encounters an error indicating that the transaction cannot be restored to a prepared state (e.g., the OS 2200 recoverable environment is initialized and not recovered). UADTC should be notified of the change in status.
• Previous manual intervention. Manual intervention (e.g., manually rolling back or committing prepared steps to prevent a deadlock) will most likely lead to the need for additional manual intervention. In this circumstance, UADTC should be notified of the change in status.
• Persistent communications problems between the MS DTC and UADTC (In Doubt state). UADTC should be used to manually commit or abort the transaction.
• Persistent communications problems between UADTC and UACS (Cannot Notify Committed and Cannot Notify Aborted states). This situation can be handled by manually committing or rolling back the transaction using the UniAccess Integrated Recovery Utility (UAIR) and using the UADTC administrator to update the status.
Always attempt to use UADTC to perform any recovery action prior to executing UAIR. For information about manually resolving transactions and UADTC administration, see Chapter 13 of the UniAccess for OS 2200 Client Guide. Information on executing UAIR is provided later in this chapter.
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-5
Windows 2000 UADTC Communications (or later) Problems
MS DTC COM+ Environment UADTC
COM+ Component using MS DTC Environment UADriver Problems
MS SQL Server OS 2200 (or other data OS 2200 Environment (UniAccess source) Problems data source)
Resource UACS Manager UAIR
TIP Environment
SQL Data UDS/ UASL TIP FCSS Transaction Data
Figure 15-2: Situations Requiring Manual Intervention to Recover a Participating Transaction
Release 10R3: October 31, 2005 15-6 UniAccess for OS 2200 System Administration Guide
Standard OS 2200 Recovery
Server-Library transactions that participate in distributed transactions utilize standard Unisys software to ensure recoverability. The specific Unisys software involved in ensuring recoverability are components of the OS 2200 operating system, IRU, and UDS Control, defined below.
The components of the OS 2200 operating system involved in recovery are Step control, Audit control, and TIP file control.
Step control synchronizes database and message recovery activities for transaction, batch, and demand programs associated with a particular application group. Step control also provides central control information for the application group’s integrated recovery software components so that appropriate recovery actions can take place.
Audit control initializes, creates, maintains, and controls access to an application group’s audit trail. Audit control also manages audit trail recoveries and audit trail keyins.
TIP file control is the EXEC component that provides specialized high- performance application group record management. For recovery purposes, TIP file control interacts with step control and audit control. TIP file control handles the input and output for TIP files, coordinates locking of TIP files, and other tasks.
IRU (Integrated Recovery Utility) is the standard OS 2200 processor that coordinates or performs all aspects of OS 200 Application Group recovery.
UDS (Universal Data System) is a group of software products that forms a comprehensive and unified system for database management, data record processing, and database application development. UDS Control (UDSC) works with several system control software components and database software products to form an integrated environment for control, maintenance, and recovery of user databases.
Step Control’s Role in Recovery
Step control facilitates recovery from various scenarios that arise in the day-to-day operating environment. Step control uses an internal structure known as a queue item to
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-7
track the progress of a transaction from initiation to completion. The queue item state is maintained by Step control and accurately reflects the state of a transaction as it steps through its processing. The queue item step ID is a unique identifier that is also used by UniAccess as the unique distributed transaction ID.
At a given time, a program step is in one of the following states:
Active—The transaction has been started.
Ready—The transaction has reached a recovery state and all its database updates have been secured (applies only to participating transactions). This is equivalent to a distributed transaction in the prepared state.
Commit-in-progress—The transaction has reached a recovery state and all its database updates have been secured.
Audit control, in conjunction with Step control, secures any change in queue item state that must be recoverable. For example, when a queue item state changes from active to commit-in-progress or ready the queue item and information required to recover database updates are written to the audit trail.
IRU’s Role in Recovery
The operating system components recover the queue items. The IRU (Integrated Recovery Utility) uses the queue items, during short recovery, to restore the databases. Transactions with a queue item state of active will have any database modifications rolled back. Transactions with a queue item state of commit-in-progress will have any database modifications rolled forward. Transactions with a queue item state of ready will be recovered and returned to the ready state.
In addition to short recovery, the IRU provides other recovery methods. For additional information, please see the Unisys OS 2200 Integrated Recovery Conceptual Overview.
Application Group Recovery Procedures
Application group recovery is required after an application group failure, a system reboot, or a manual change in the state of the application group. In the distributed transaction processing environment, application group recovery is performed in three steps. The first
Release 10R3: October 31, 2005 15-8 UniAccess for OS 2200 System Administration Guide
step is recovery of active queue items by the operating system. The second step is recovering updates by the IRU. The third step is to COMMIT or ABORT any recovered transactions in the ready state.
Recovering Active Queue Items
When the application group status is changed to UP, the operating system will solicit the system administrator to determine whether to initialize the queue items, or how to recover them. The possible responses are:
PANIC: EXEC to Recover queue items from panic dump & audit trail. REBUILD: EXEC to Recover queue items from Periodic Save File & audit trail. SUTIL: IRU to Recover queue items from Periodic Save File & audit trail. INIT: EXEC to delete all queue items! DOWN: Leave the application group in the down (inaccessible) state. DEFER: Defer recovery to a later time, the application group is inaccessible.
If PANIC, REBUILD or SUTIL options are exercised, all queue items, including those in the ready state will be recovered. If INIT is chosen, all the queue items are deleted and recovery is at risk. When the operating system solicits the operator for the type of recovery, the valid responses are listed with the least costly recovery option first (e.g., PANIC/ REBUILD/SUTIL/INIT/DOWN/DEFER).
Note Choosing INIT when bringing up an application group is extremely risky and should only be done with the consequences known before hand. Database updates for both commit-in-progress and ready states may be lost.
If the INIT option is used, all queue items are deleted. This means that any queue items in the prepared state are lost and neither UADTC nor UAIR has the ability to address them.
INIT is the least desirable recovery option and must be exercised with great caution. For additional information, please see the Unisys OS 2200 Integrated Recovery Conceptual Overview.
INIT is valid when the system has been shut down with no active transactions. A common use of INIT is when changing operating system parameters.
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-9
Recovering Updates by IRU
The second part of bringing the application group is to run IRU short recovery. When IRU short recovery is run, UDSC is called to commit, roll backward or reestablish database updates/locks for the recovered queue items. After short recovery, UDSC has reestablished the environment for queue items in the ready state just as if the transaction were still active.
COMMIT or ABORT any Recovered Transactions
After IRU short recovery completes, UADTC has the ability to COMMIT or ABORT queue items in the ready state. If UADTC issues the COMMIT or ABORT for a recovered queue item, the system behaves normally as if the transaction were still active and issuing the COMMIT/ABORT. In this case, the COMMIT or ABORT request will be issued by UACS, which acts on behalf of the lost transaction. If for some reason, the system has been unable to respond to UADTC for some period of time and UADTC has given up trying to COMMIT or ABORT a transaction, manual intervention is required to perform the COMMIT or ABORT of the recovered queue item. The UAIR processor provides this capability. The system administrator must track the origin of the UniAccess transaction that is participating in the distributed transaction and determine if that transaction completed successfully or not. If the participating transaction completed successfully, UAIR must be used to complete the transaction normally, otherwise UAIR must be used to roll back the transaction.
Note If a participating transaction has reached the prepared state (queue item state is ready) and the transaction is terminated for some reason (operator key-in, system stop, application group abort, etc.), the database locks associated with the transaction remain active. For normal operation of a participating transaction, the UADTC commands will function to minimize the time between the PREPARE and the COMMIT/ABORT requests, even across a system crash.
Warning Prior to running any IRU recovery, other than short recovery, please see the Unisys OS 2200 Integrated Recovery Conceptual Overview. There are numerous recovery scenarios that are dependent upon the type of updates being performed (i.e., DEFERRED or QUICKLOOKS).
Release 10R3: October 31, 2005 15-10 UniAccess for OS 2200 System Administration Guide
Executing UAIR The UniAccess Integrated Recovery Utility (UAIR) provides the system administrator with the capability to resolve (COMMIT or OMIT) participating transactions that may have been left in the PREPARED state by a system failure. (The UAIR command OMIT is the equivalent of an ABORT.)
Note UAIR should only be used on PREPARED transactions, which are no longer active on the system (i.e., not visible in a TP T keyin).
UAIR operates as a processor and exercises the following algorithm:
• If the ‘H’ option is specified (the only meaningful option), the Help text is displayed (see below).
• If the ‘H’ option is not specified, UAIR reads the specified UniAccess Configuration File to validate and extract application group information for all application groups that have an associated UDS BDI configured (see the APPINF UDSBDI configuration parameter on page 16-11).
• If only one application group exists that has an associated UDS BDI, UAIR examines that application and retrieves all recovered PREPARED transactions IDs.
• If more than one application group exists, UAIR solicits the system administrator to select an application group in which to retrieve all recovered PREPARED transactions IDs.
• UAIR displays all PREPARED transactions IDs for the selected application group and solicits the system administrator to select a transaction ID and the type of operation to be performed (COMMIT or OMIT).
• UAIR repeats the above step until no more PREPARED transactions are found or the system administrator terminates UAIR.
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-11
UAIR is executed as an OS 2200 processor and accepts command line parameters. You can execute the UAIR utility using the following format:
@qual*file.UAIR,options spec1
where:
qual*file is the name of the file where the UAIR utility is located. For the production mode install, the default file name is SYS$LIB$*UAUTIL; for the test mode install, the default file name is SYS$LIB$*UAUTILT.
options currently, only the ‘H’ option is supported:
H Display Help text (see below).
spec1 is the binary UniAccess Configuration File. If this spec 1 field is not specified and UAIR is executed from the production mode installation file, the default name of UNIACCESS*CONFIG. is used. Otherwise, this field is required.
UAIR in Interactive Mode
Although UAIR is a processor, it acts in interactive mode; in other words once activated, the system administrator directs the actions that UAIR performs. UAIR can accept input from an @ADD stream, but prudence dictates that it be exercised in demand mode.
There are three basic prompts used by UAIR. The prompts are: application group, transaction id, and command. Each of the prompts displays a menu of items for the system administrator to chose. Figure 15-3 illustrates the general sequence of UAIR prompts. If the administrator responds to any prompt with a value that is not on the menu, UAIR will terminate.
Release 10R3: October 31, 2005 15-12 UniAccess for OS 2200 System Administration Guide
Prompt for Application Group
No Any PREPARED Terminate transactions?
Yes
Prompt for Transaction id
Prompt for Command
Figure 15-3: General Sequence of UAIR Prompts
Prompt for Application Group
UAIR will prompt the system administrator to select the application group when the configuration file specified in spec1 includes more than one application group with an APPINF UDSBDI parameter. Only the application groups that include the UDSBDI parameter will be included in the menu.
UniAccess Integrated Recovery Utility (UAIR) v7R2 Executed on: Mon Apr 10 02:18:45 2002 UAIR: Select Application Group to Process Index Application Group Name UDSBDI ======1 APPONE 400604 2 APPTWO 402453 3 UDSSRC 400753 ======Choose 1 - 3, or illegal choice to terminate
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-13
Response to Option 3
UAIR: Application Group: UDSSRC, UDS BDI: 400753 will be processed
After displaying the response, UAIR will proceed to the prompt for transaction ID.
Prompt for Transaction ID
Appl Group: UDSSRC, Total RECOVERED PREPARED Transactions: 6 Index PREPARED Transaction Id Year-MM-DD HH:MM:SS Sequence-Step ======1 2002-03-05 00:59:11 01372370-0000 2 2002-03-05 00:59:09 01372360-0000 3 2002-03-05 00:59:15 01372423-0000 4 2002-03-05 00:59:13 01372404-0000 5 2002-03-05 00:59:14 01372414-0000 6 2002-03-05 00:59:14 01372413-0000 ======Select index for PREPARED transaction id to process Choose 1 - 6, or illegal choice to terminate
Response to Option 1
Selected PREPARED transaction id is: 2002-03-05 00:59:14 01372413-0000
After displaying the response, UAIR will proceed to the prompt for command.
Prompt for Command
Enter command for PREPARED transaction id: 2002-03-05 00:59:15 01372423-0000 1: COMMIT 2: OMIT
Release 10R3: October 31, 2005 15-14 UniAccess for OS 2200 System Administration Guide
Response to Option 1
PREPARED transaction id: 2002-03-05 00:59:14 01372413-0000 will be COMMITted PREPARED transaction id: 2002-03-05 00:59:14 01372413-0000 has been successfully COMMITted
After displaying the response, UAIR will determine if there are any other PREPARED transactions and if so, proceed to the prompt for transaction ID.
Response to Option 2
PREPARED transaction id: 2002-03-05 00:59:15 01372423-0000 will be OMITted PREPARED transaction id: 2002-03-05 00:59:15 01372423-0000 has been successfully OMITted
After displaying the response, UAIR will determine if there are any other PREPARED transactions and if so, proceed to the prompt for transaction ID.
The UAIR processor generates any necessary error messages and returns them to the system administrator. These error messages concern problems with either the system administrator input or the UAIR environment. UAIR error messages cause UAIR to terminate abnormally. Appendix D contains a list of possible UAIR error messages.
The following examples illustrate how an interactive dialog using UAIR proceeds.
Example 1: ‘H’ option
In this example, UAIR is invoked with the ‘H’ (help) option. UAIR responds by displaying the help text and then terminating.
@UAIR.UAIR,H UniAccess Integrated Recovery Utility (UAIR) v7R2 Executed on: Mon Apr 10 02:18:45 2002 usage: uair,h [configfile] options: h - display uacf help and version information parameters: configfile - UniAccess configuration file UAIR: normal termination
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-15
Example 2: Commit and Omit of PREPARED transactions
In this example, UAIR processes an alternative UniAccess Configuration File (AIS*CONFIG) and determines that three application groups have been defined which have associated APPINF UDSBDI parameters. The three application groups are displayed and the system administrator is solicited to choose the application group for UAIR to process. UAIR displays a list of PREPARED transactions and solicits the system administrator to select a PREPARED transaction and specify whether that transaction should be committed or omitted.
Note Application groups without an associated APPINF UDSBDI parameter are not displayed. The UniAccess distributed transaction processing environment is only available to application groups that contain the UniAccess configuration parameter APPINF USDBDI.
@UAIR.UAIR AIS*CONFIG. UniAccess Integrated Recovery Utility (UAIR) v7R2 Executed on: Mon Apr 10 02:18:45 2002 UAIR: Select Application Group to Process Index Application Group Name UDSBDI ======1 APPONE 400604 2 APPTWO 402453 3 UDSSRC 400753 ======Choose 1 - 3, or illegal choice to terminate
>3
------
UAIR: Application Group: UDSSRC, UDS BDI: 400753 will be processed
Release 10R3: October 31, 2005 15-16 UniAccess for OS 2200 System Administration Guide
Appl Group: UDSSRC, Total RECOVERED PREPARED Transactions: 6 Index PREPARED Transaction Id Year-MM-DD HH:MM:SS Sequence-Step ======1 2002-03-05 00:59:11 01372370-0000 2 2002-03-05 00:59:09 01372360-0000 3 2002-03-05 00:59:15 01372423-0000 4 2002-03-05 00:59:13 01372404-0000 5 2002-03-05 00:59:14 01372414-0000 6 2002-03-05 00:59:14 01372413-0000 ======Select index for PREPARED transaction id to process Choose 1 - 6, or illegal choice to terminate
>6
------
Selected PREPARED transaction id is: 2002-03-05 00:59:14 01372413-0000
Enter command for PREPARED transaction id: 2002-03-05 00:59:14 01372413-0000 1: COMMIT 2: OMIT
>1
PREPARED transaction id: 2002-03-05 00:59:14 01372413-0000 will be COMMITted PREPARED transaction id: 2002-03-05 00:59:14 01372413-0000 has been successfully COMMITted
------
Appl Group: UDSSRC, Total RECOVERED PREPARED Transactions: 5 Index PREPARED Transaction Id Year-MM-DD HH:MM:SS Sequence-Step ======1 2002-03-05 00:59:11 01372370-0000 2 2002-03-05 00:59:09 01372360-0000 3 2002-03-05 00:59:15 01372423-0000
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-17
4 2002-03-05 00:59:13 01372404-0000 5 2002-03-05 00:59:14 01372414-0000 ======Select index for PREPARED transaction id to process Choose 1 - 5, or illegal choice to terminate
>3
------Selected PREPARED transaction id is: 2002-03-05 00:59:15 01372423-0000 Enter command for PREPARED transaction id: 2002-03-05 00:59:15 01372423-0000 1: COMMIT 2: OMIT
>2
PREPARED transaction id: 2002-03-05 00:59:15 01372423-0000 will be OMITted PREPARED transaction id: 2002-03-05 00:59:15 01372423-0000 has been successfully OMITted
------
Appl Group: UDSSRC, Total RECOVERED PREPARED Transactions: 4 Index PREPARED Transaction Id Year-MM-DD HH:MM:SS Sequence-Step ======1 2002-03-05 00:59:11 01372370-0000 2 2002-03-05 00:59:09 01372360-0000 3 2002-03-05 00:59:13 01372404-0000 4 2002-03-05 00:59:14 01372414-0000 ======Select index for PREPARED transaction id to process Choose 1 -4, or illegal choice to terminate
Example 3: Large number of PREPARED transactions
This example shows how UAIR handles the display when more than 15 transactions are in a PREPARED state, which is extremely rare. In this case there are 34 prepared transactions.
@UAIR.UAIR AIS*CONFIG.
Release 10R3: October 31, 2005 15-18 UniAccess for OS 2200 System Administration Guide
UniAccess Integrated Recovery Utility (UAIR) v7R2 Executed on: Mon Apr 10 02:18:45 2002 UAIR: Select Application Group to Process Index Application Group Name UDSBDI ======1 APPONE 400604 2 APPTWO 402453 3 UDSSRC 400753 ======Choose 1 - 3, or illegal choice to terminate
>3
------
UAIR: Application Group: UDSSRC, UDS BDI: 400753 will be processed
Appl Group: UDSSRC, Total RECOVERED PREPARED Transactions:34 Index PREPARED Transaction Id Year-MM-DD HH:MM:SS Sequence-Step ======1 2002-06-21 11:53:18 00000001-0001 2 2002-06-21 11:53:28 00000002-0001 3 2002-06-21 11:53:38 00000003-0001 4 2002-06-21 11:53:48 00000004-0001 5 2002-06-21 11:53:58 00000005-0001 6 2002-06-21 11:54:08 00000006-0001 7 2002-06-21 11:54:18 00000007-0001 8 2002-06-21 11:54:28 00000010-0001 9 2002-06-21 11:54:38 00000011-0001 10 2002-06-21 11:54:48 00000012-0001 11 2002-06-21 11:54:58 00000013-0001 12 2002-06-21 11:55:08 00000014-0001 13 2002-06-21 11:55:18 00000015-0001 14 2002-06-21 11:55:28 00000016-0001 15 2002-06-21 11:55:38 00000017-0001 ======Select index for PREPARED transaction id to process Choose 1 - 15, N for next screen or illegal choice to terminate
Release 10R3: October 31, 2005 UniAccess Distributed Transaction Coordinator 15-19
>N
------
Appl Group: UDSSRC, Total RECOVERED PREPARED Transactions:34 Index PREPARED Transaction Id Year-MM-DD HH:MM:SS Sequence-Step ======16 2002-06-21 11:55:48 00000020-0001 17 2002-06-21 11:55:58 00000021-0001 18 2002-06-21 11:56:08 00000022-0001 19 2002-06-21 11:56:18 00000023-0001 20 2002-06-21 11:56:28 00000024-0001 21 2002-06-21 11:56:38 00000025-0001 22 2002-06-21 11:56:48 00000026-0001 23 2002-06-21 11:56:58 00000027-0001 24 2002-06-21 11:57:08 00000030-0001 25 2002-06-21 11:57:18 00000031-0001 26 2002-06-21 11:57:28 00000032-0001 27 2002-06-21 11:57:38 00000033-0001 28 2002-06-21 11:57:48 00000034-0001 29 2002-06-21 11:57:58 00000035-0001 30 2002-06-21 11:58:08 00000036-0001 ======Select index for PREPARED transaction id to process Choose 16 - 30, N for next screen or illegal choice to terminate
Release 10R3: October 31, 2005 15-20 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 V Config & Ops References Part V ...... Configuration and Operations References
Chapter 16: UniAccess Source Configuration Statement Reference
Chapter 17: UniAccess System Processor Execution Statements
Chapter 18: UniAccess Reconfiguration Procedures
Chapter 19: UACS Operations Reference
16 Config Statements 16 UniAccess Source Configuration Statement Reference
This chapter describes the format and use of the configuration statements needed to configure all host components of the UniAccess System.
Topics Page
Overview of UniAccess Configuration Statements 16-2 Format of UniAccess Configuration Statements 16-2 Syntax Rules 16-2 Notation Conventions 16-7 UniAccess Configuration Statements 16-8 Source Configuration Files 16-9 APPINF 16-10 CABNUM 16-13 CHARSET 16-14 COMSRV 16-16 HIERSRV 16-36 LOCALE 16-42 OSPARM 16-44 RELSRV 16-50 RPCMAP 16-60 SERVER 16-65 UAMESG 16-68 UAMM 16-70 UAMMAP 16-73 UASLCS 16-76 UAUSER 16-78 Summary of Configuration Statement Requirements 16-94
Release 10R3: October 31, 2005 16-2 UniAccess for OS 2200 System Administration Guide
Overview of UniAccess Configuration Statements UniAccess configuration statements are the means by which the system administrator can select and define the communications options available through the UniAccess System. They define the environment in which the UniAccess System operates on the OS 2200 system and they specify its operational characteristics. They also contain definitions of users, messages, and remote server connections. These configuration statements are maintained in two source configurations, which can be either data files or symbolic elements in a program file.
This chapter should be used when you initially write UniAccess configuration statements to build the Site Information File (see Chapter 6). It will also be useful in analyzing or changing existing statements in the Site Information File or the UA Information File.
The first section of this chapter explains the required syntax and standard conventions for writing configuration statements. The second section provides information about each configuration statement including its purpose, its parameters, an example of its use, and the names of other configuration statements to which it is related.
Format of UniAccess Configuration Statements Configuration statements are system data format (SDF) ASCII images maintained in the source configuration files. You can create and edit the configuration statements in an ASCII file using any text editor that creates SDF images, including most OS 2200 editors. Configuration statements follow the syntax rules described in this section.
Syntax Rules
The configuration statement example in Figure 16-1 illustrates the syntax rules that apply to UniAccess configuration statements.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference 16-3
Field 1 Field 2 Comment
Subfield 1 Subfield 2 Subfield 3 (parameter) (variable) (optional variable)
continuation character (;)
spaces comma comma space
RELSRV ROWLIMIT,uars-rowlimit,USEROVERRIDEON ; . max number of rows returned SCHEMA,uars-schema-name,USEROVERRIDEOFF ; . default RDMS schema STRIPCTRL,YES,USEROVERRIDEON ; . convert control characters WORKSIZE,10000 . RSA worksize
period Field 5 (introduces comment)
Field 4
Field 3
Figure 16-1: Example of Syntax Rules for UniAccess Configuration Statements
Basic Configuration Statement Structure
The basic structure of a configuration statement is as follows:
• Each configuration statement is comprised of one or more fields, separated by one or more spaces.
• Each field consists of one or more subfields, separated by commas.
Release 10R3: October 31, 2005 16-4 UniAccess for OS 2200 System Administration Guide
First Field (Statement Type)
The first field of a configuration statement identifies the overall statement. It consists of a keyword indicating the statement type (for example, APPINF, CHARSET, or COMSRV). To write a statement, you may use the following characters from the ASCII set:
•Letters
•Digits
• All special characters, except the following:
— Comma (,)
— Accent (')
— Quote (")
— Backslash (\)
— Masterspace (@)
— Plus sign (+)
— Equal sign (=)
— Semicolon (;)
The UniAccess System considers the following character pairs as equivalent:
• { and ?
• : and \
• } and !
• ~ and ^
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference 16-5
Second and Subsequent Fields (Parameters)
The second and subsequent fields of a configuration statement are parameters that provide specific information about the entity you are defining. Each field consists of the following subfields:
• The first subfield is a keyword indicating the parameter type (for example PROCNAM, PROCPSWD, and LISTENPRT of the COMSRV statement).
• The subsequent subfields (if any) are variables—names, numbers, or keywords that provide specific information about the entity you are defining. These variables must be presented in the order they appear in this manual.
Continuing Configuration Statements on Another Line
Theoretically, the UniAccess System can accept lines of a configuration statement that are up to 200 characters long. However, the practical limit is 80 characters per line, given the standard width of terminal screens.
To continue a configuration statement on the next line, use the continuation character— a semicolon (;)—at the end of a line. All characters between the semicolon and the end of the line are ignored. The first non-blank character on the next line becomes the next character of the continued configuration statement and is considered as follows:
...then the first non-blank character on If the semicolon follows the next line is considered to be ______, ______.
a space the beginning of the next field a comma the beginning of the next subfield of the same field any other character a continuation of the same subfield
To continue a message text variable or character set definition on the next line, use a backslash (\). All characters between the backslash and the end of the line will be ignored. For example:
"Columns specified in an ORDER BY list must \ be unique (RDMS: %s)"
Release 10R3: October 31, 2005 16-6 UniAccess for OS 2200 System Administration Guide
Inserting Comments
You can include comments in your UniAccess System source configuration in the following ways:
• After a space-period-space sequence on a statement
• On a separate line, where a period-space sequence is in columns 1 and 2
• After a semicolon continuation character.
Character Interpretation
The UACF processor treats all characters as text, except the comma (,) and the semicolon (;). It treats the period character (.) as text except where it is used to mark a comment. The UACF processor interprets the space-period-character sequence and the character-period- space sequence as text and does not stop the scan of the line. The period-space in columns 1 and 2 and the space-period in the last two columns of a line stop the scan of the image.
Message Text Variables
Message text is a string of characters that relay error information to the user, for example, "String is too long (RDMS: %s)." Message text variables are unique because they can contain embedded spaces. These variables must be delimited with double quotes (").
Character Set Definition
A character set definition contains a list of character pairs, separated by commas, that defines how one set of ASCII characters is translated to another set of ASCII characters. The character pairs are defined as two fixed-length, two-byte hexadecimal values separated by a hyphen (-). The character being translated from is on the left of the hyphen and the character being translated to is on the right of the hyphen. Spaces are not allowed between character pairs. The entire set of comma-separated character pairs is enclosed in parenthesis. The following example would translate lowercase a, b and c to uppercase A, B and C.
(61-41,62-42,63-43)
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference 16-7
Notation Conventions
The following conventions are used to represent the configuration statement formats in this manual:
UPPERCASE If a keyword or variable is in uppercase letters, you must enter the value exactly as shown. lowercase If a variable is in lowercase italics, the value is either user-defined italic or one of a set of standard options.
[ ] Brackets enclose optional fields or subfields.
{ } Braces enclose two or more fields or subfields and indicate that you must select one of the fields or subfields shown.
[{ }] Braces within brackets indicate that the fields or subfields are optional, and if you include one, you cannot include any others.
Format Example
UAMMAP CODE,message-code ; (1) [FATAL,{ YES | NO } ;] (2) FLAG,flag ; [MAPCODE,map-code ;] (3) [SEVERITY,severity ;] [STATE,state ]
Notes on the Format Example
1. The CODE,message-code parameter is required. You must enter the keyword CODE exactly as shown. The term message-code is a variable and is required. The FLAG,flag parameter is also required.
2. The FATAL parameter is optional. If you include it, you must specify either YES or NO.
3. The MAPCODE,map-code, SEVERITY,severity, and STATE,state parameters are optional.
Release 10R3: October 31, 2005 16-8 UniAccess for OS 2200 System Administration Guide
UniAccess Configuration Statements Table 16-1 provides a quick reference to UniAccess configuration statement names and their purposes. The alphabetical listing of configuration statements that follows gives a more detailed description of each. Related configurations are noted within the description of each parameter. For a complete reference of configuration relationships, see Appendix B.
Table 16-1: UniAccess Configuration Statements
Statement Name Purpose
APPINF Application group definition
CABNUM Machine model (cabinet number) definition
CHARSET Character set definition
COMSRV UniAccess Communication Server definition
HIERSRV UniAccess Hierarchical Service definition
LOCALE Localization definition
OSPARM Operating System definition
RELSRV UniAccess Relational Service definition
RPCMAP Maps RPC names to their appropriate transaction codes
SERVER Remote server definitions
UAMESG Message text information
UAMM UniAccess Message Manager configuration information
UAMMAP Detailed message information
UASLCS Character set translation definition for UASL
UAUSER User definitions
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference 16-9
Source Configuration Files
In order to simplify configuration file management, configuration records supplied by AIS (RPCMAP, UAMESG, UAMMAP) have been placed in a separate source configuration file. This file is called the UA Information File and is located in SYS$LIB$*UAUTIL.UNIACCESS/INC (or SYS$LIB$*UAUTILT.UNIACCESS/INC for test mode installations). System administrators may use this file to change the text of UAMESG records and the mapping of UAMMAP records.
Site-specific configuration statements, which can include site-defined RPCMAP, UAMESG, and UAMMAP records, are placed in the Site Information File. This file includes the majority of the UniAccess configuration statements. It initially takes the form of a template. AIS provides four template options in SYS$LIB$*UAUTIL (SYS$LIB$*UAUTILT for test mode installations) (see page 5-1 for an explanation of these templates). After the template has been modified by the system administrator to reflect that site’s desired configuration, it should be saved in a locally selected file to avoid being over written by subsequent installations.
The table below indicates which UniAccess configuration statements are contained in which source file.
Table 16-2: Source Configuration File Assignments
Source Configuration File Configuration Statements
Site Information File All records: APPINF RELSRV CHARSET SERVER COMSRV UAMM HIERSRV UASLCS LOCALE UAUSER OSPARM Customer-written records: RPCMAP UAMESG UAMMAP UA Information File AIS-written records: CABNUM RPCMAP UAMESG UAMMAP
Release 10R3: October 31, 2005 16-10 APPINF UniAccess for OS 2200 System Administration Guide
APPINF
Purpose
This statement defines the application group characteristics for each application group that UniAccess products will use. A maximum of 16 APPINF statements may be configured.
Syntax
APPINF APPNAME,application-name ; APPNUM,application-number ; MCBBDI,mcb-bank-descriptor-index ; [UAHSTIPF,tip-file-number ] ; [UDSBDI,uds-bank-descriptor-index]
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
APPINF required required required n/a APPNAME required required required n/a APPNUM required required required n/a MCBBDI required required required n/a UAHSTIPF n/a n/a required n/a UDSBDI optional optional n/a n/a
Parameters
APPNAME,application-name The application group name for the application group defined by the APPNUM parameter. Range 1 to 6 characters.
This parameter must match the MCB APNAME, the UDS APPL-NAME, and the EXEC APPLICATION NAME statement variables.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference APPINF 16-11
APPNUM,application-number The application group for which characteristics are being defined. Range 1 to 16.
This parameter must match the UniAccess COMSRV APPNUM, the UDS APPL-GROUP-NUMBER, the MCB APNUMBER, the (TIP) VALTAB AUD, and the EXEC STEPCONTROL statement variables.
MCBBDI,mcb-bank-descriptor-index The bank descriptor index (BDI) for the MCB bank in the application group defined by the APPNUM parameter. This is the six digit octal BDI for the MCB interface bank (MCBBNK). Range 0400000 to 0407777.
This parameter must match the MCB MCBBDI and the UDS MCB-MSG-BANK-BDI statement variables.
UAHSTIPF,tip-file-number The number of the TIP file that holds the meta-schema information of DMS databases. This file, termed the UAHS Meta Database, holds tables describing the DMS schemas to be accessed by the UniAccess System. This value must be a number within the range of 12—TIPMEF, where TIPMEF is an EXEC system generation parameter specifying the maximum number of EXEC files that may be registered with TIP.
UDSBDI,uds-bank-descriptor-index The bank descriptor index (BDI) for the UDS thread control ICR bank in the application group defined by the APPNUM parameter. This is a six digit octal BDI. This value is used by UASL, UARS, and the UAIR utility to facilitate distributed transaction processing. Range 0400000 to 0407777.
This parameter must match the BDI assigned to the installed TICRI bank for this application group. (The TICRI bank is in the UDS$TCLCDICR absolute element.) Each UDS application group has a TICRI bank. This value may be obtained from SYS$DATA$.CO$INSTALL$/COMUS$. The image in SYS$DATA$.CO$INSTALL$/COMUS$ will look like:
CBD,0400753,UDS$$SRC*ABSLIB$(7),UDS$TCLCDICR,TICRI,DYNAMIC,''TS QUEUING'',;
Release 10R3: October 31, 2005 16-12 APPINF UniAccess for OS 2200 System Administration Guide
For more information about TICRI (table control intercept and connect routine), see the Unisys OS 2200 Universal Data System Control (UDS Control) Conceptual Overview and the Unisys OS 2200 Universal Data System (UDS) Configuration Guide.
Note In some distributed transaction recovery situations, UACS will issue thread commands through the UDSBDI. To avoid a potential deadlock, the UDS configuration attribute, MAX-THREADS, should be set to a value that will ensure that UACS can open a thread.
You can ensure that a batch thread can begin by configuring the UDS attribute MAX-THREADS to a value less than the maximum number of concurrent transactions allowed in the application group.
The maximum number of concurrent transactions in an application group is the smaller of the EXEC configured parameter TIPTPS or of the maximum number of transactions allowed on the SYSTEM node of the STEPCONTROL NODE system generation statement for the application group. These EXEC configuration parameters may be overridden by and EXEC console keyin.
For additional information, see the Unisys Repository Manager (UREP) Programming Reference Manual and the Unisys OS 2200 EXEC System Software Installation and Configuration Guide.
Example
APPINF APPNUM,3 ; APPNAME,UDSSRC ; MCBBDI,0400400 ; UAHSTIPF,50 ; UDSBDI,0400753
Related UniAccess Configuration Statements
The COMSRV APPNUM parameter.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference CABNUM 16-13
CABNUM
Purpose
This statement defines machine model numbers (cabinet numbers) that are used when processing product keys. This statement cannot be modified and should only reside in the UA Information File. This statement is not currently used.
Syntax
CABNUM ID,cabnum-id ; VALUE,cabnum-value
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
CABNUM n/a n/a n/a n/a ID n/a n/a n/a n/a VA LU E n/a n/a n/a n/a
Parameters
CABNUM,cabnum-id The cabinet number ID. Range 1 to 32767. Not currently used.
VALUE,cabnum-value The cabinet number value. Range 1 to 8 characters. Not currently used.
Example
CABNUM ID,1 ; VALUE, 4801-1
Related UniAccess Configuration Statements
None.
Release 10R3: October 31, 2005 16-14 CHARSET UniAccess for OS 2200 System Administration Guide
CHARSET
Purpose
This statement defines character set definitions. The fully qualified filename and any keys should be specified. A maximum of 10 CHARSET statements may be configured. [Currently, only the ISO 8859/1 (Latin-1) character set, named iso_1, is supported.]
Syntax
CHARSET FILE,charset-filename ; NAME,charset-name
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
CHARSET n/a n/a n/a optional1 FILE n/a n/a n/a optional NAME n/a n/a n/a optional
1 The CHARSET statement included with the Site Information File template is required for UACL. Optionally, additional CHARSET statements may be defined by the customer.
Parameters
FILE,charset-filename The name of the OS 2200 file containing the character set. Range 1 to 70 characters.
NAME,charset-name The name of the character set. Range 1 to 30 characters.
This parameter is related to the UniAccess LOCALE CHARSET parameter.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference CHARSET 16-15
Example
CHARSET NAME,iso_1 ; FILE,SYS$LIB$*ISO-1
Related UniAccess Configuration Statements
The LOCALE CHARSET parameter.
Release 10R3: October 31, 2005 16-16 COMSRV UniAccess for OS 2200 System Administration Guide
COMSRV
Purpose
This statement defines UniAccess Communication Server (UACS) operational characteristics. A maximum of 100 COMSRV statements may be configured.
Syntax
COMSRV APPNUM,application-number ; [BADPIDTIMOUT,badpid-timeout ;] [BLKPIDTIMOUT,blk-timeout ;] [CHARTRUN,{ YES | NO } ;] [CMSNUM,cms-number ;] [CONFIRMTERM,{ YES | NO } ;] [CONTIMOUT,connection-timeout ;] DFLTTRAN, { UAHSTRAN [,UARS] [,UASL] | UARSTRAN [,UAHS] [,UASL] | USERTRAN [,UAHS] [,UARS] | NONE [,UAHS] [,UARS] } ; [KEEPALIVES,{ YES | NO } ;] [KEEPALIVINT,keepaliveint ;] [LISTENPRT,listen-port ;] [LNGASGATTR,lanuage-file-asg-attributes ;] [LNGFNAME,language-filename ;] [LNGTRACE,{ YES | NO };] [LOGOFFTRAN,logoff-transaction ;] [LOGONTRAN,logon-transaction ;] [MAXSENDS,maxsends ;] [MULTIIP,{ YES | NO } ;] [NWRTIMOUT,network-read-timeout ;] [NWWTIMOUT,network-write-timeout ;] PIDCNT,pid-count ; PIDSTART,pid-start ; [PRIORITY,switching-priority-level ;] PROCNAM,process-name ; PROCPSWD,process-password ; [SENDDATABYT,{ YES | NO } ;]
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-17
[SYSLOG,{ON | OFF} ;] [SYSLOGTYPE,type ;] [TIMOUTWAIT,timeout-wait ;] [TIPQCNT,tipq-task-count ;] [TIPQSIZE,tipq-entries ;] [TRCASGATTR,trace-file-asg-attributes ;] [TRCFNAME,trace-filename ;] [TRCLEVEL,{ OFF | LOW | MEDIUM | HIGH } ;] [TSAMCNT,tsam-task-count ;] [UACSTYPE,{UATC | UATS | UATC/UATS} ;] [UAHSTRAN,UAHS-transaction ;] [UAINTRAN,UAINFO-transaction ;] [UARSTRAN,UARS-transaction ;] [UARSTRAN2,UARS-transaction-2 ;] [UARSTRAN3,UARS-transaction-3 ;] [UARSTRAN4,UARS-transaction-4 ;] [USERTRAN,user-language-transaction ;] [USEUAUSER,{ YES | NO } ;] [WAITTIME,routing-queue-poll-time ]
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
COMSRV required required required required APPNUM required required required n/a1 BADPIDTIMOUT optional optional optional n/a BLKPIDTIMOUT optional optional optional n/a CHARTRUN optional optional optional n/a CMSNUM optional optional optional n/a CONFIRMTERM optional optional optional optional
1 The COMSRV UACSTYPE parameter should be set to UATC if UACS will be servicing only UACL programs. Setting COMSRV UACSTYPE to UATC will make the COMSRV APPNUM parameter not be required by the UACF processor.
Release 10R3: October 31, 2005 16-18 COMSRV UniAccess for OS 2200 System Administration Guide
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
CONTIMOUT optional optional optional n/a DFLTTRAN optional optional optional n/a KEEPALIVES optional optional optional n/a KEEPALIVINT optional optional optional n/a LISTENPRT optional optional optional n/a LNGASGATTR optional optional optional n/a LNGFNAME optional optional optional n/a LNGTRACE optional optional optional n/a LOGOFFTRAN optional optional optional n/a LOGONTRAN optional optional optional n/a MAXSENDS optional optional optional n/a MULTIIP optional optional optional optional NWRTIMOUT optional optional optional optional NWWTIMOUT optional optional optional optional PIDCNT required required required required PIDSTART required required required required PRIORITY optional optional optional optional PROCNAM required required required required PROCPSWD required required required required SENDDATABYT optional optional optional n/a SYSLOG optional optional optional optional SYSLOGTYPE optional optional optional optional TIMOUTWAIT optional optional optional optional TIPQCNT optional optional optional optional TIPQSIZE optional optional optional n/a
1 The COMSRV UACSTYPE parameter should be set to UATC if UACS will be servicing only UACL programs. Setting COMSRV UACSTYPE to UATC will make the COMSRV APPNUM parameter not be required by the UACF processor.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-19
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
TRCASGATTR optional optional optional optional TRCFNAME optional optional optional optional TRCLEVEL optional optional optional optional TSAMCNT optional optional optional optional UACSTYPE optional optional optional optional1 UAHSTRAN optional optional optional n/a UAINTRAN optional optional optional n/a UARSTRAN optional optional optional n/a UARSTRAN2 optional optional optional n/a UARSTRAN3 optional optional optional n/a UARSTRAN4 optional optional optional n/a USERTRAN optional optional optional n/a USEUAUSER optional optional optional n/a WAITTIME optional optional optional optional
1 The COMSRV UACSTYPE parameter should be set to UATC if UACS will be servicing only UACL programs. Setting COMSRV UACSTYPE to UATC will make the COMSRV APPNUM parameter not be required by the UACF processor.
Parameters
APPNUM,application-number The application group number that UACS supports. Range 1 to 16.
This parameter must be configured to the UniAccess APPINF APPNUM, the MCB APNUMBER, the (TIP) VALTAB AUD statement, the UDS APP-GROUP-NUMBER, and the EXEC STEPCONTROL variables.
If the COMSRV UACSTYPE parameter is set to UATC, the COMSRV APPNUM parameter is not required.
Release 10R3: October 31, 2005 16-20 COMSRV UniAccess for OS 2200 System Administration Guide
BADPIDTIMOUT,badpid-timeout The time in seconds UACS will allow a PID to remain in a bad state before it frees the PID and allows it to be reused by the system. A bad PID is one which has been marked in error and should, under normal circumstances, be cleaned up by UACS. However, for some undetermined reason, UACS has not been able to successfully release the bad PID. This parameter supplements the other timeout parameters and is not a replacement for them. Zero indicates that no timeout checking will be performed. Range 0, 60 to 262143. Defaults to 0.
BLKPIDTIMOUT,blk-timeout The time in seconds that UACS will allow the PID for a server transaction to remain in a blocked state before it terminates the transaction. A transaction is placed in a blocked state when OS 2200 is unable to deliver the transaction’s output to the client due to either communications problems or problems at the client end. OS 2200 will periodically poll the client to determine when it is able to receive output again. When it receives acknowledgement that output may be sent again, it notifies UACS. UACS sends the transaction’s output and, if successful, reactivates the server transaction. This parameter supplements the other timeout parameters and is not a replacement for them. Zero indicates that no blocked PID checking will be performed. Range 0, 60 to 262143. Defaults to 0. Note Some applications may be seriously impacted if the server transaction remains blocked for a prolonged period of time.
The BLKPIDTIMOUT parameter does not apply to PIDs used by UADTC.
CHARTRUN,{ YES | NO } Indicates whether or not character columns will be truncated. YES indicates that character columns longer than 255 characters should be truncated. NO indicates that an error should be generated for character columns longer than 255. Defaults to YES.
This setting may be overridden by the RELSRV/UAUSER LONGCHAR setting.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-21
CMSNUM,cms-number This parameter defines a unique CMS number for the MCB interface. If this parameter is not specified or if 99 is specified, UACS will automatically select an unused CMS number. Range 0 to 61 and 99. Defaults to automatic selection.
CONFIRMTERM,{ YES | NO } This parameter indicates whether or not UACS should confirm unsolicited TERM keyin requests. YES indicates that UACS should request confirmation of the requested termination action with the console message:
"ARE YOU SURE
NO indicates that UACS should proceed with the requested termination action without operator confirmation. Defaults to YES.
CONTIMOUT,connection-timeout The time in seconds that a connection is allowed to remain idle. This parameter does not apply for clients using extended session. Zero indicates that connections should never be terminated. Range 0 to 262143. Defaults to 0. Note The CONTIMOUT parameter does not apply to PIDs used by UADTC.
DFLTTRAN, { UAHSTRAN [,UARS] [,UASL] | UARSTRAN [,UAHS] [,UASL] | USERTRAN [,UAHS] [,UARS] | NONE [,UAHS] [,UARS] } Specifies the default language transaction and services that will be used for connections opened using a pre-9R1 UniAccess ODBC Driver or an Open Client application. The 9R1 and later versions of the UniAccess ODBC Driver allow this information to be configured as part of the DSN or passed at connection time.
UAHSTRAN indicates that the COMSRV UAHSTRAN parameter will designate the default language transaction. This value also indicates that the UAHS service may be accessed by the connection. The additional options UARS and UASL may be specified indicating that the corresponding UARS or UASL service may also be accessed by the connection.
Release 10R3: October 31, 2005 16-22 COMSRV UniAccess for OS 2200 System Administration Guide
UARSTRAN indicates that the COMSRV UARSTRAN parameter will designate the default language transaction. This value also indicates that the UARS service may be accessed by the connection. The additional options UAHS and UASL may be specified indicating that the corresponding UAHS or UASL service may also be accessed by the connection.
USERTRAN indicates that the COMSRV USERTRAN parameter will designate the default language transaction. This value also indicates that the UASL service may be accessed by the connection. The additional options UAHS and UARS may be specified indicating that the corresponding UAHS or UARS service may also be accessed by the connection.
NONE indicates that there is no default language transaction. This value also indicates that the UASL service may be accessed by the connection. The additional options UAHS and UARS may be specified indicating that the corresponding UAHS or UARS service may also be accessed by the connection. If the UAHS and/or UARS service is specified, requests to these services must be in the form of RPCs.
The default value will be determined in the following manner:
— If the default language transaction specified by DFLTTRAN is not compatible with the product keys (UAHSPRODKEY, UARSPRODKEY, and/or UASLPRODKEY of the OSPARM configuration statement), UACF will select as the default language transaction the first language transaction that is compatible with the supplied product keys in the following sequence: UARSTRAN, UAHSTRAN, and NONE. In such a case, a warning message will be issued.
— If an optional service specified by DFLTTRAN is not compatible with the product keys (UAHSPRODKEY, UARSPRODKEY, and/or UASLPRODKEY of the OSPARM configuration statement), UACF will remove the optional service. In such a case, a warning message will be issued.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-23
— If the UACSTYPE for this COMSRV is UACL, the DFLTTRAN will be set to NONE. Note When a connection is opened using a pre-9R1 UniAccess ODBC Driver or an Open Client application, the number of active concurrent connections for each service will be updated based on the services configured using the DFLTTRAN parameter.
KEEPALIVES,{ YES | NO } Indicates whether or not UACS will use the TSAM keep-alives option. YES causes CMS or CPComm to send an are-you-alive packet to client connections. If a client connection does not respond within the time defined by the COMSRV KEEPALIVINT parameter, the connection is assumed to be dead. This option will help with situations where a UASL, UARS, or UAHS client terminate abnormally and CMS or CPComm do not detect the termination. NO indicates that the TSAM keep-alives option is not used and that the KEEPALIVINT, MAXSENDS, and SENDDATABYT parameters of the COMSRV statement are ignored. Defaults to NO.
If YES is selected, the COMSRV KEEPALIVINT, MAXSENDS, and SENDDATABYT parameters should also be configured.
Consult the Unisys OS 2200 Communications Management System (CMS 1100) Programming Reference Manual or the Unisys Cooperative Processing Communications Platform (CPComm) Programming Reference Manual for further details on the keep-alives settings.
KEEPALIVINT,keepaliveint The time in minutes between the sending of keep-alives probes. Range 1 to 870. Defaults to 120 minutes.
LISTENPRT,listen-port The port upon which UACS will listen for connections. Zero indicates that UACS should automatically select an unused port. Range 1 to 65535. Defaults to 2768.
Release 10R3: October 31, 2005 16-24 COMSRV UniAccess for OS 2200 System Administration Guide
Specifying a listen-port value of 0 may require that the client configuration be modified whenever UACS is restarted. This value must match the appropriate client parameter:
Client Parameter
UADriver Port (on the General tab of the UADriver Setup dialog) Open Client Port portion of the IP address in the sql.ini file
LNGASGATTR,language-file-asg-attributes Defines the @ASG options for the language trace file. Range 1 to 80 characters. Defaults to F///256.
LNGFNAME,language-filename The name of the language trace file. Range 1 to 70 characters. The language-filename must be a valid OS 2200 filename. Defaults to UNIACCESS*XXXXXX$LANG, where XXXXXX is the COMSRV PROCNAM value.
LNGTRACE,{ YES | NO } Indicates whether or not language tracing will be on initially and a trace file generated. YES means tracing is on; NO means tracing is not on. (For more information about tracing, see the LANGUAGE console command on page 19-7) Defaults to NO.
LOGOFFTRAN,logoff-transaction This parameter defines the TIP transaction code of the logoff transaction. Range 1 to 6 characters. Defaults to NULL. This parameter must match the (TIP) VALTAB ACT statement variable. If the LOGOFFTRAN parameter is defined, the LOGONTRAN parameter must also be defined.
(See Chapter 11 for details about the logoff transaction.)
LOGONTRAN,logon-transaction This parameter defines the TIP transaction code of the logon transaction. Range 1 to 6 characters. Defaults to NULL.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-25
This parameter must match the (TIP) VALTAB ACT statement variable. If the LOGOFFTRAN parameter is defined, the LOGONTRAN parameter must also be defined.
(See Chapter 11 for details about the logon transaction.)
MAXSENDS,maxsends The number of times CMS or CPComm will send a keep-alives probe before closing a connection if there is no response. Range 1 to 256, where 256 indicates that an infinite number of probes are sent. Defaults to 256. Note The keep-alives probe will be sent until the send count becomes zero. Each time keep-alives probes are not acknowledged by the client’s TCP/IP stack, CMS or CPComm decrements the send count. For example, if MAXSENDS is set to 1, two keep-alives probes will be sent before the connection is aborted.
MULTIIP,{ YES | NO } Indicates whether or not multiple Internet addresses will be supported by UACS. YES indicates that multiple addresses will be supported. NO indicates that only one Internet address will be supported. Defaults to NO.
When using CMS 1100, Internet addresses must be configured in the INTERNET-ADR statement of the CMS 1100 configuration file. When using CPComm, Internet addresses must be configured in the IP statement of the CPComm configuration file.
NWRTIMOUT,network-read-timeout The time in seconds UACS will attempt to read input from the network. NWRTIMOUT applies in the following circumstances:
For UACL connections, a network read time out will occur when: — The time between a logon request and the response to the logon request exceeds NWRTIMOUT — The time between sending an RPC request to a remote system and receiving a response exceeds NWRTIMOUT
Release 10R3: October 31, 2005 16-26 COMSRV UniAccess for OS 2200 System Administration Guide
— A UACL request waits more than NWRTIMOUT seconds for an input buffer.
For UASL connections, a network read time out will occur when: — The time between UACS receiving the buffers of a logon packet exceeds NWRTIMOUT — The time between UACS receiving the buffers associated with the submission of an RPC request exceeds NWRTIMOUT — If a distributed transaction is being executed on the connection and the time between the transaction calling TDCOMPLETE and UACS receiving the PREPARE or ROLLBACK request exceeds NWRTIMOUT.
This parameter is not applicable if the PID is suspended, nor for PIDs used by UADTC to communicate changes in the transaction state. Zero indicates that connections should never be timed out. Range 0 to 262143. Defaults to 0.
NWWTIMOUT,network-write-timeout The time in seconds UACS will attempt to write results received from the RPC back to the client (including a UACL client). This parameter will free up the client and mark the PID in ERROR. The PID will be released when the RPC is notified of the error condition (next UASL call). The parameter is not applicable if the PID is suspended, for remote servers, or for a client communicating through a remote server. Zero indicates that the write should retry forever. Range 0 to 262143. Defaults to 0. Note The NWWTIMOUT parameter does not apply to PIDs used by UADTC.
PIDCNT,pid-count The number of consecutive PIDs. Because there is a one-to-one relationship between PIDs and connections, this field indicates the maximum number of concurrent connections that will be supported. Range 1 to 65,000. The PID ranges among COMSRV records may not overlap; that is, each UACS must be assigned a unique range of PIDs.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-27
Note The number of the starting PID plus the count minus 1 must be less than or equal to 262143.
starting PID + count - 1 < 262143
Note The number of current connections supported by a UACS execution is the smaller of the COMSRV PIDCNT parameter, the UAMM PROCCNT parameter, or the sum of concurrent connections supported by the product keys (the UACLPRODKEY, UAHSPRODKEY, UARSPRODKEY, and UASLPRODKEY parameters of the OSPARM statement).
This parameter is related to the UniAccess COMSRV PIDSTART parameter. The range of PIDs defined by the PIDCNT and PIDSTART parameters must be within the range of PIDs configured by the MCB P$ID configuration statement. These PIDs must not be in use by CMS or MAPPER. If you use the UniAccess Security API (see Chapter 11), these PIDs must not be configured for input or output message control.
PIDSTART,pid-start The first PID of a group of consecutive, configured PIDs. Range 1 to 262143.
This parameter is related to the UniAccess COMSRV PIDCNT parameter. The range of PIDs defined by the PIDCNT and PIDSTART paramenters must be within the range of PIDs configured by the MCB P$ID configuration statement. These PIDs must not be in use by CMS or MAPPER. If you use the UniAccess Security API (see Chapter 11), these PIDs must not be configured for input or output message control.
PRIORITY,switching-priority-level This parameter defines the switching priority level (real-time-level) for UACS. Range 2 to 35. Defaults to 35.
Release 10R3: October 31, 2005 16-28 COMSRV UniAccess for OS 2200 System Administration Guide
PROCNAM,process-name The process name to be used by this COMSRV record. The UACS processor uses the process name to identify a COMSRV record. Range 1 to 6 characters. Note The process name must begin with an alpha character.
This parameter must match the UniAccess UAUSER COMSRV and CMS 1100 or CPComm PROCESS statement variables. Note If the process name is explicitly assigned to one or more IP addresses in the CPComm configuration, the process name must also be explicitly assigned to a LOOPBACK LINK with the IP address 127.0.0.1. UACS uses the 127.0.0.1 address during termination.
PROCPSWD,process-password The password for the process specified in the PROCNAM parameter. Range 1 to 32 characters. This parameter must match the PASSWORD parameter on the PROCESS statement in the CMS or CPComm configuration file.
SENDDATABYT,{ YES | NO } Indicates whether or not CMS or CPComm should send an arbitrary byte of data with a keep-alives probe. Some TCP/IP implementations do not respond to keep-alives probe segments unless data is included. YES indicates that an arbitrary byte of data will be sent with the keep-alives probe; NO indicates that the arbitrary byte will not be sent. Defaults to NO.
SYSLOG,{ ON | OFF } Indicates whether or not system logging will initially occur. ON means system logging is on; OFF means system logging is off. (System logging can also be controled by the UACS SYSLOG console command described on page 19-23.) Defaults to OFF.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-29
SYSLOGTYPE,type The UACS system log type identifier. (For more information about system logging, see UACS Security Logging on page 19-33.) Range is 50000 to 2500000. Defaults to 59999. Note The UACS system log subtype will default to the number of the UACS Trace File message (msgcode) being logged.
TIMOUTWAIT,timeout-wait The time in seconds UACS will wait before checking for timeout conditions. This value should be used by a site to optimize the frequency of the timeout checks performed by UACS. Range 3 to 262143. Defaults to 3.
TIPQCNT,tipq-task-count Defines the number of UAMM output tasks to start at boot time. Range 1 to 20. Defaults to 1.
TIPQSIZE,tipq-entries The maximum number of entries on the output routing queue. Range 100 to 32000. Defaults to 4096.
TRCASGATTR,trace-file-asg-attributes Defines the @ASG options for the trace file. Range 1 to 80 characters. Defaults to F///256. Note The trace file must be placed on fixed mass-storage.
TRCFNAME,trace-filename The name of the UACS trace file. Range 1 to 70 characters. The trace-filename must be a valid OS 2200 filename. Defaults to UNIACCESS*XXXXXX$TRACE, where XXXXXX is the COMSRV PROCNAM value.
Release 10R3: October 31, 2005 16-30 COMSRV UniAccess for OS 2200 System Administration Guide
TRCLEVEL,{ OFF | LOW | MEDIUM | HIGH } Defines the initial level of trace activity captured in the trace file. Options are OFF, LOW, MEDIUM, HIGH. Tracing at a LOW level provides error messages; tracing at a MEDIUM level provides error and warning messages; and tracing at a HIGH level provides error, warning, and informational messages. (For more information about tracing, see the TRACE console command on page 19-27.) Defaults to LOW.
TSAMCNT,tsam-task-count Defines the number of TSAM tasks to start at boot time. Range 1 to 20. Defaults to 1.
UACSTYPE,{UATC | UATS | UATC/UATS } Indicates whether or not UACS will only be available to process UniAccess Transaction Client (UATC), UniAccess Transaction Server (UATS), or UniAccess Transaction Client and Transaction Server (UATC/UATS) requests. In the case of this parameter, UniAccess ODBC Server for RDMS 2200 and UniAccess ODBC Server for DMS 2200 are included in the term UATS. This value should correspond with the product package purchased at a site. (For instance, if UniAccess Transaction Server was purchased, the value should be UATS.) Note If this value does not match the value for the product package purchased, (which is reflected in one or more of the OSPARM product key values) a warning message will be generated and the operational characteristics of UACS will automatically be modified during initialization to reflect the product key value characteristics. UATC corresponds with the OSPARM UACLPRODKEY value. UATS corresponds the OSPARM UAHSPRODKEY, OSPARM UARSPRODKEY, and/or OSPARM UASLPRODKEY values.
UAHSTRAN,UAHS-transaction Defines the TIP transaction code of the hierarchical service language transaction. Range 1 to 6 characters. Defaults to NULL.
This parameter must match the (TIP) VALTAB ACT statement variable.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-31
UAINTRAN,UAINFO-transaction Defines the TIP transaction code to which UACS will map UAINFO requests. UAINFO requests are issued by the UniAccess ODBC Driver when the User Language Transaction/No Language Transaction configuration option is selected. They may also be issued by Open Client applications in an environment where neither UARS nor UAHS are installed. Range 1 to 6 characters. Defaults to NULL.
This parameter is only meaningful if a UARSTRAN or UAHSTRAN parameter is not configured.
This parameter must match the (TIP) VALTAB ACT statement variable.
UARSTRAN,UARS-transaction This parameter defines the TIP transaction code of the relational service language transaction for the 1st through 63rd concurrent copies. (The maximum number of concurrent copies of a transaction are controlled by the COP VALTAB setting, which has a maximum value of 63.) Range 1 to 6 characters. Defaults to NULL.
This parameter must match the (TIP) VALTAB ACT statement variable.
UARSTRAN2,UARS-transaction-2 Defines the TIP transaction code of the relational service language transaction for the 64th through 126th concurrent copies. This transaction code will only be scheduled after the maximum number of concurrent copies of the transaction defined in UARSTRAN are active. (The maximum number of current copies of a transaction are controlled by the COP VALTAB setting, which has a maximum value of 63.) Range 1 to 6 characters. Defaults to NULL.
If this parameter is defined, UARSTRAN must also be defined and the transaction code configured in UARSTRAN must be set for 63 copies.
This parameter must match the (TIP) VALTAB ACT statement variable.
Release 10R3: October 31, 2005 16-32 COMSRV UniAccess for OS 2200 System Administration Guide
UARSTRAN3,UARS-transaction-3 Defines the TIP transaction code of the relational service language transaction for the 127th through 189th concurrent copies. This transaction code will only be scheduled after the maximum number of concurrent copies of the transaction defined in UARSTRAN and UARSTRAN2 are active. (The maximum number of current copies of a transaction are controlled by the COP VALTAB setting, which has a maximum value of 63.) Range 1 to 6 characters. Defaults to NULL.
If this parameter is defined, UARSTRAN and UARSTRAN2 must also be defined and the transaction codes configured in UARSTRAN and UARSTRAN2 must be set for 63 copies.
This parameter must match the (TIP) VALTAB ACT statement variable.
UARSTRAN4,UARS-transaction-4 Defines the TIP transaction code of the relational service language transaction for the 190th through 252nd concurrent copies. This transaction code will only be scheduled after the maximum number of concurrent copies of the transaction defined in UARSTRAN, UARSTRAN2, and UARSTRAN3 are active. (The maximum number of current copies of a transaction are controlled by the COP VALTAB setting, which has a maximum value of 63.) Range 1 to 6 characters. Defaults to NULL. If this parameter is defined, UARSTRAN, UARSTRAN2 and UARSTRAN3 must also be defined and the transaction codes configured in UARSTRAN, UARSTRAN2, and UARSTRAN3 must be set for 63 copies.
This parameter must match the (TIP) VALTAB ACT statement variable.
USERTRAN,user-language-transaction Defines the TIP transaction code of a user-written language transaction. Range 1 to 6 characters. Defaults to NULL.
This parameter must match the (TIP) VALTAB ACT statement variable.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-33
Note If you wish to use the user-language transaction in conjunction with UADriver, you should install the UAINFO transaction (see page 4-14) and configure the COMSRV UAINFO parameter.
USEUAUSER,{ YES | NO } Indicates whether or not UACS will validate the userid contained in the login packet against the list maintained in UADT. This field is used by UASL, UARS, and UAHS only. YES means that UACS will validate userids. NO means that UACS will skip the validation step. Defaults to YES.
TIP session control validation is independent of UACS validation. (TIP session control is indicated on the OSPARM statement.) Note If COMSRV USEUAUSER is YES, a UAUSER entry must exist for UASL, UARS, and UAHS users. If COMSRV UAUSER is NO, the UAUSER USERID parameter must be “@@@@@@@@@@@@”, which serves as default userid for users who not are assigned a UAUSER record (see page 16-79).
WAITTIME,routing-queue-poll-time The time in milliseconds between checking the TIP output routing queues for output to be processed by UACS. Range 1 to 1000 milliseconds. Defaults to 100.
Example
COMSRV PROCNAM,UACS ; APPNUM,3 ; BADPIDTIMOUT,0 ; CHARTRUN,YES ; CMSNUM,99 ; CONFIRMTERM,YES ; CONTIMOUT,1800 ;
Release 10R3: October 31, 2005 16-34 COMSRV UniAccess for OS 2200 System Administration Guide
DFLTTRAN,UARSTRAN ; KEEPALIVES,YES ; KEEPALIVINT,15 ; LISTENPRT,2768 ; LNGASGATTR,F///256 ; LNGFNAME,UNIACCESS*LANG ; LNGTRACE,NO ; LOGOFFTRAN,SECON ; LOGONTRAN,SECOFF ; MAXSENDS,1 ; MULTIIP,NO ; NWRTIMOUT,30 ; NWWTIMOUT,10 ; PIDCNT,50 ; PIDSTART,400 ; PRIORITY,35 ; PROCPSWD,PASSWORD ; SENDDATABYT,YES ; SYSLOG,YES ; SYSLOGID,59999 ; TIMOUTWAIT,3 ; TIPQCNT,3 ; TIPQSIZE,4096 ; TRCASGATTR,F///256 ; TRCFNAME,UNIACCESS*TRACE ; TRCLEVEL,LOW ; TSAMCNT,3 ; UACSTYPE,UATC/UATS ; UAHSTRAN,UAHS ; UAINTRAN,UAIN ; UARSTRAN,UARS ; UARSTRAN2,UARS2 ; UARSTRAN3,UARS3 ; UARSTRAN4,UARS4 ; USERTRAN,USER ; USEUAUSER,YES ; WAITTIME,100
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference COMSRV 16-35
Related UniAccess Configuration Statements
The APPINF APPNUM parameter.
For UACL, the UAUSER COMSRV parameter.
The UACLPRODKEY, UAHSPRODKEY, UARSPRODKEY, and UASLPRODKEY parameters of the OSPARM statement.
Release 10R3: October 31, 2005 16-36 HIERSRV UniAccess for OS 2200 System Administration Guide
HIERSRV
Purpose
This statement defines operational characteristics for the UniAccess Hierarchical Service. The system administrator can use this statement to define default settings for the UAUSER records, rather than having to define each parameter of a UAUSER record individually. The values of UAUSER parameters that are shared with the HIERSRV statement automatically default to the values assigned here.
Most parameters of the HIERSRV statement may be set to be client-side configurable; that is, they can allow client applications to override the parameter’s default setting. These parameters correspond to required and optional settings for ODBC and Open Client applications. ODBC clients set these options through the UADriver Setup dialog boxes or through connection string attribute names. Open Clients may set these options through UAHS SET commands. The relationship between the overrideable HIERSRV parameters and their client options is described in Table 16-3.
Table 16-3: HIERSRV Parameter/ Client Option Correspondences
HIERSRV Parameter UADriver Setup Option1 UAHS Command2
AREASEARCH Perform area search SET AREASRCH DEBUG Activate host debugging SET DEBUG ROWLIMIT Rowlimit SET ROWLIMIT SCHEMAH Database none SPACETRIMH Remove trailing spaces from SET SPACETRIM character columns STRIPCTRLH Remove control characters from SET STRIPCTRL literal strings TRANSACTIVEH Activate Translation SET TRANSACTIVE TRANSOPTIONH Translation Option SET TRANSOPTION
1 For descriptions of ODBC options and commands, see Chapter 5 of the UniAccess for OS 2200 Client Guide. 2 For descriptions of UAHS commands, see Chapter 10 of the UniAccess for OS 2200 Client Guide.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference HIERSRV 16-37
Syntax
HIERSRV [AREASEARCH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [DEBUG,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [ROWLIMITH,rowlimit [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] SCHEMAH,schema-name [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ; [SPACETRIMH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [STRIPCTRLH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [TRANSACTIVEH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [TRANSOPTIONH,{ NONE | LETSJ | SJIS } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [WAITTIME,receive-waittime ]
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
HIERSRV n/a n/a required n/a AREASEARCH n/a n/a optional n/a DEBUG n/a n/a optional n/a ROWLIMITH n/a n/a optional n/a SCHEMAH n/a n/a optional n/a SPACETRIMH n/a n/a optional n/a STRIPCTRLH n/a n/a optional n/a TRANSACTIVEH n/a n/a optional n/a TRANSOPTIONH n/a n/a optional n/a WAITTIME n/a n/a optional n/a
Release 10R3: October 31, 2005 16-38 HIERSRV UniAccess for OS 2200 System Administration Guide
Parameters
AREASEARCH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UAHS will search an entire database area if the WHERE clause of the SELECT command being processed does not contain sufficient information to FETCH the DMS data through its primary location mode (see page 14-32). Since this type of search may have a significant impact on the system, the administrator can either allow or disallow the capability. YES indicates that area search is on; NO indicates that area search is off. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the AREASEARCH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
DEBUG,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether debug tracing of SQL requests is on or off. 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.
YES indicates that debug is on; NO indicates that debug is off. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the DEBUG YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
ROWLIMITH,rowlimit,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the maximum number of rows that UAHS returns to a single SELECT request. If the value is set to 0, UAHS does not limit the number of rows returned. If the number of rows generated by a SELECT request exceeds the ROWLIMIT defined value, UAHS stops generating rows. Range 0 to 2147483647. Defaults to 0.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference HIERSRV 16-39
USEROVERRIDEON indicates that the client application can override the ROWLIMITH,rowlimit setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the rowlimit setting. Defaults to USEROVERRIDEOFF.
SCHEMAH,schema-name,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default DMS 2200 schema for UAHS. Range 1 to 30 characters.
USEROVERRIDEON indicates that the client application can override the SCHEMAH,schema-name setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the schema-name setting. Defaults to USEROVERRIDEOFF.
SPACETRIMH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not trailing spaces will be truncated. NO indicates that UAHS will not trim trailing spaces from character fields before retuning them to the user. YES indicates that trailing spaces will be trimmed. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the SPACETRIMH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
STRIPCTRLH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UAHS should convert control characters (values ranging from 0x01 to 0x1F) in request command buffers to spaces (value 0x20). 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. Defaults to YES.
USEROVERRIDEON indicates that the client application can override the STRIPCTRLH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 16-40 HIERSRV UniAccess for OS 2200 System Administration Guide
TRANSACTIVEH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not the user-supplied translation routines should be called by UAHS. NO indicates that UAHS will not call the user-supplied translation routines. YES indicates that UAHS will call the user-supplied translation routines. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the TRANSACTIVEH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
TRANSOPTIONH,{ NONE | LETSJ | SJIS },{USEROVERRIDEON | USEROVERRIDEOFF} Specifies a value to be passed to the user-supplied translation routine if UAHS calls the translation routine (that is, if TRANSACTIVE is YES). NONE indicates that the value ua_no_xlate should be passed to the user- supplied translation routine. LETSJ indicates that the value ua_letsj should be passed to the translation routine. SJIS indicates that the value ua_sjis should be passed to the translation routine. Defaults to NONE.
USEROVERRIDEON indicates that the client application can override the TRANSOPTIONH NONE | LETSJ | SJIS setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the NONE | LETSJ | SJIS setting. Defaults to USEROVERRIDEOFF.
WAITTIME,receive-waittime The time in seconds the UAHS transaction will wait for a request before terminating. Range 0 to 262143. Defaults to 0.
Example
HIERSRV AREASEARCH,YES,USEROVERRIDEON ; DEBUG,YES ; ROWLIMITH,5000,USEROVERRIDEON ; SCHEMAH,UADMS ; SPACETRIMH,YES ; STRIPCTRLH,NO ;
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference HIERSRV 16-41
TRANSACTIVEH, NO ; TRANSOPTIONH, NONE ; WAITTIME,0
Related UniAccess Configuration Statements
The UAUSER statement.
Release 10R3: October 31, 2005 16-42 LOCALE UniAccess for OS 2200 System Administration Guide
LOCALE
Purpose
This statement defines localization information. A maximum of 10 LOCALE statements may be configured. (Currently, only the English language is supported.)
Syntax
LOCALE CHARSET,character-set ; FILE,locale-filename ; LANGUAGE,language ; NAME,locale-name ; [SORTORDER,sort-order ]
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
LOCALE n/a n/a n/a optional1 CHARSET n/a n/a n/a optional FILE n/a n/a n/a optional LANGUAGE n/a n/a n/a optional NAME n/a n/a n/a optional SORTORDER n/a n/a n/a optional
1 The LOCALE statement included with the Site Information File template is required for UACL. Additional LOCALE statements may be defined by the customer.
Parameters
CHARSET,character-set The name of the character set for this set of localizations files. This parameter must match a NAME parameter on a CHARSET statement entry. Range 1 to 30 characters.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference LOCALE 16-43
FILE,file-name The name of the OS 2200 file containing the character set. Range 1 to 70 characters. The file-name must be a valid OS 2200 filename.
LANGUAGE,language The name of the language for this set of localization files. Range 1 to 30 characters.
NAME,locale-name The name of the LOCALE statement associated with this set of localization files. The name is case sensitive. Range 1 to 30 characters. Note UACL internally uses the LOCAL statement included with the Site Information File template. This LOCALE statement defines a LOCALE name of DEFAULT.
SORTORDER,sort-order The name of sort order for this set of localization files. Range 1 to 30 characters. Currently, binary is the only option supported.
Example
LOCALE NAME,default ; CHARSET,iso_1 ; FILE,SYS$LIB$*ENGL$ISO-1 ; LANGUAGE,us_english ; SORTORDER,binary
Related UniAccess Configuration Statements
The CHARSET statement.
Release 10R3: October 31, 2005 16-44 OSPARM UniAccess for OS 2200 System Administration Guide
OSPARM
Purpose
This statement defines operating system characteristics. Currently, three groups of operating characteristics are defined: 1) UniAccess licensing is specified via the product keys, which determine which UniAccess features were purchased and are available for use; 2) TIP session control configuration, which indicates whether or not TIP session control is on and defines values for site-specific operating system modifications; and 3) the default handling of RPC requests that are not explicitly mapped to either UASL or RDMS.
Product Keys
UniAccess provides product keys for each separately orderable component. Each product key corresponds to a parameter of the OSPARM configuration statement. The four UniAccess product keys are:
• The UACLPRODKEY controls the use of the UniAccess Transaction Client components, including UniAccess Client-Library.
• The UAHSPRODKEY controls the use of the UniAccess ODBC Server for DMS components, including the UniAccess Hierarchical Service.
• The UARSPRODKEY controls the use of the UniAccess ODBC Server for RDMS components, including the UniAccess Relational Service.
• The UASLPRODKEY controls the use of the UniAccess Transaction Server components, including UniAccess Server-Library.
Each of the product keys embed the Manufacture Control Number (MCN) of the system it was created for along with the level of UniAccess it was created for and the maximum number of concurrent threads of the product permitted under the customer’s license of UniAccess.
Permanent UniAccess product keys are only valid on the specific system and the level of UniAccess for which they were generated. If your site has multiple systems, or a disaster recovery system, you will need separate UniAccess product keys for each system.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference OSPARM 16-45
The UniAccess product keys will enforce the licensing limits when a single instance of UniAccess is installed on a system. When a limited UniAccess license is being used, the maximum number of concurrent threads of a product are the licensing limits for the system, regardless of whether the system is partitioned, or multiple UniAccess fixed-gate subsystems are installed. When a system with a limited UniAccess product license is partitioned, or installs multiple UniAccess subsystems, the site should take steps to prevent exceeding the license limits on concurrent threads. For example, a site with a limited license permitting a maximum of 10 concurrent threads using the UniAccess ODBC Service for RDMS and partitioning the system into production and test partitions could limit that UARS transaction to 7 copies on the production partition via the VALTAB COPIES (COP) property and 3 copies on the test partition.
Minimizing RPC Mapping
While the RPCMAP statement is the definitive way RPC requests are routed, the OSPARM DFLTPROCENV value is the default mechanism for routing RPCs for which there is no RPCMAP statement. Using the DFLTPROCENV parameter, the system administrator may select to have all RPCs routed to Server-Library transactions or to RDMS 2200 stored procedures. This mechanism may be used to minimize the amount of mapping required for certain processing environments.
• UniAccess ODBC Server for RDMS 2200 customers may set DFLTPROCENV to RDMS and not bother creating any RPCMAP statements. All RPC requests will be routed through UARS to RDMS automatically.
• UniAccess Transaction Server customers (who either don’t have UniAccess ODBC Server for RDMS 2200 or don’t use RDMS stored procedures) may set DFLTPROCENV to UATS and not bother creating any RPCMAP statements. All RPCs will be routed to UASL transactions automatically, using the 1st 6 characters of the RPC name as the VALTAB. (Here, however, administrators may prefer to use the RPCMAP statement because it allows mapping RPC names of up to 30 characters to their appropriate VALTAB transaction codes.)
• UniAccess ODBC Server for RDMS 2200 and UniAccess Transaction Server customers who use both Server-Library transactions and RDMS stored procedures should either map all requests using the RPCMAP statement or set the OSPARM DFLTPROCENV parameter to minimize the amount of mapping
Release 10R3: October 31, 2005 16-46 OSPARM UniAccess for OS 2200 System Administration Guide
to be performed. For example, if the majority of RPC requests are to RDMS stored procedures, set DFLTPROCENV to RDMS and only map the UASL requests. Conversely, if the majority of RPC requests are to Server-Library transactions, you might set DFLTPROCENV to UATS and only map RDMS stored procedure requests.
Syntax
OSPARM [DFLTPROCENV,{ RDMS | UATS } ;] [NEWPWDPRMPT,new-password-prompt ;] SESSCTRL,{ YES | NO } ; [SYSTEMPRMPT,system-prompt ;] [UACLPRODKEY,uacl-prodkey-key ;] [UAHSPRODKEY,uahs-prodkey-key ;] [UARSPRODKEY,uars-prodkey-key ;] [UASLPRODKEY,uasl-prodkey-key ;] [UIDPWDPRMPT,userid-password-prompt ]
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
OSPARM required required required required DFLTPROCENV optional optional n/a n/a NEWPWDPRMPT optional optional optional n/a SESSCTRL optional1 optional1 optional1 n/a SYSTEMPRMPT optional optional optional n/a UACLPRODKEY optional optional optional required UAHSPRODKEY optional optional required optional UARSPRODKEY optional required optional optional UASLPRODKEY required optional optional optional UIDPWDPRMPT optional optional optional n/a
1 If TIP session control is active, the SESSCTRL parameter is required and must be set to YES.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference OSPARM 16-47
Parameters
DFLTPROCENV,{ RDMS | UATS } Determines the default processing environment for unmapped RPCs sent to the UniAccess System. This parameter is particularly useful when RPCs are sent to both Server-Library transactions and RDMS stored procedures (for other uses, see the discussion under Purpose above).
RDMS indicates that unmapped RPC requests will be routed through UARS to RDMS 2200 to be processed by an RDMS stored procedure. UATS indicates that unmapped RPCs will be sent to the UniAccess Transaction Server to be processed by a Server-Library transaction. The first six characters of the RPC name are used as the transaction code (VALTAB) when RPCs are submitted to a Server-Library transaction (see the RPCMAP statement). Defaults to UATS. Note See Chapter 6 of the UniAccess for OS 2200 Client Guide for information about how sp_procedures and sp_procedure_columns catalog information is returned when duplicated RDMS procedure and Server-Library transaction names are encountered.
NEWPWDPRMPT,new-password-prompt Defines the value of the TIP session control new password prompt. When TIP session control is configured, this value can be used to provide UniAccess with site-specific operating system modifications to this prompt. Defaults to Enter your new password: .
SESSCTRL,{ YES | NO } Indicates whether or not TIP session control is configured. NO indicates that TIP session control is not configured. YES indicates that TIP session control is configured. Defaults to NO.
If OSPARM SESSCTRL is YES, you must configure the maximum number of sessions and the session file in the EXEC configuration using STEPCONTROL SGSs.
Release 10R3: October 31, 2005 16-48 OSPARM UniAccess for OS 2200 System Administration Guide
SYSTEMPRMPT,system-prompt Defines the value of the TIP session control system message prompt. When TIP session control is configured, this value can be used to provide UniAccess with site-specific operating system modifications to this prompt. Defaults to Unisys 1100 transaction system: .
UACLPRODKEY,uacl-prodkey-key Defines the product features of UniAccess for OS 2200 specific to UACL that were purchased and are available for use. If the product was shipped directly to you by AIS and the UACL product feature was purchased, the UACL product key is included with the shipment of the product. However, if the product was shipped by Unisys, see page 5-4 for details about obtaining your product key. This parameter is required to use UACL product features.
UAHSPRODKEY,uahs-prodkey-key Defines the product features of UniAccess for OS 2200 specific to UAHS that were purchased and are available for use. If the product was shipped directly to you by AIS and the UAHS product feature was purchased, the UAHS product key is included with the shipment of the product. However, if the product was shipped by Unisys, see page 5-4 for details about obtaining your product key. This parameter is required to use UAHS product features.
UARSPRODKEY,uars-prodkey-key Defines the product features of UniAccess for OS 2200 specific to UARS that were purchased and are available for use. If the product was shipped directly to you by AIS and the UARS product feature was purchased, the UARS product key is included with the shipment of the product. However, if the product was shipped by Unisys, see page 5-4 for details about obtaining your product key. This parameter is required to use UARS product features.
UASLPRODKEY,uasl-prodkey-key Defines the product features of UniAccess for OS 2200 specific to UASL that were purchased and are available for use. If the product was shipped directly to you by AIS and the UASL product feature was purchased, the UASL product key is included with the shipment of the product. However,
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference OSPARM 16-49
if the product was shipped by Unisys, see page 5-4 for details about obtaining your product key. This parameter is required to use UASL product features.
UIDPWDPRMPT,userid-password-prompt Defines the value of the TIP session control userid/password prompt. When TIP session control is configured, this value can be used to provide UniAccess with site-specific operating system modifications to this prompt. Defaults to Enter your user-id/password and clearance level: .
Example
OSPARM DFLTPROCENV,RDMS ; NEWPWDPRMPT,"Enter you new password:" ; SESSCTRL,NO ; SYSTEMPRMPT,"Unisys 1100 transaction system:" ; UACLPRODKEY,12345678-12345678-12345678-12345678 ; UAHSPRODKEY,12345678-12345678-12345678-12345678 ; UARSPRODKEY,12345678-12345678-12345678-12345678 ; UASLPRODKEY,12345678-12345678-12345678-12345678 ; UIDPWDPRMPT,"Enter your user-id/password:"
Related UniAccess Configuration Statements
The RPCMAP statement.
Release 10R3: October 31, 2005 16-50 RELSRV UniAccess for OS 2200 System Administration Guide
RELSRV
Purpose
This statement defines operational characteristics for the UniAccess Relational Service. The system administrator can use this statement to define default settings for the corresponding parameters in the UAUSER records, rather than having to define each parameter of a UAUSER record individually. The values of UAUSER parameters that are shared with the RELSRV statement automatically default to the values assigned here.
Most parameters of the RELSRV statement may be set to be client-side configurable; that is, they can allow client applications to override the parameter’s default setting. These parameters correspond to required and optional settings for ODBC and Open Client applications. ODBC clients set these options through the UADriver Setup dialog boxes or through connection string attribute names. Open Clients may set these options through UARS SET commands. The relationship between the overrideable RELSRV parameters and their client options is described in Table 16-4.
Table 16-4: RELSRV Parameter/ Client Option Correspondences
RELSRV Parameter UADriver Setup Option1 UARS Command2
ACCESS Thread Access SET ACCESS DOUNICODE Support SQL_UNICODE SET UNICODE INTTOCHAR Convert integers to characters SET INTTOCHAR LONGCHAR Support SQL_LONGCHAR SET LONGCHAR MAXBLOBSIZE UARS Blobsize SET BLOBSIZE RECOVERY Thread Recovery SET RECOVERY ROWLIMIT Rowlimit SET ROWLIMIT SCHEMA Database none
1 For descriptions of ODBC options and commands, see Chapter 5 of the UniAccess for OS 2200 Client Guide. 2 For descriptions of UARS commands, see Chapter 7 of the UniAccess for OS 2200 Client Guide.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference RELSRV 16-51
RELSRV Parameter UADriver Setup Option1 UARS Command2
SPACETRIM Remove trailing spaces from SET SPACETRIM character columns STRIPCTRL Remove control characters from SET STRIPCTRL literal strings TRANSACTIVE Activate Translation SET TRANSACTIVE TRANSOPTION Translation Option SET TRANSOPTION WORKSIZE RSA Worksize SET WORKSIZE
1 For descriptions of ODBC options and commands, see Chapter 5 of the UniAccess for OS 2200 Client Guide. 2 For descriptions of UARS commands, see Chapter 7 of the UniAccess for OS 2200 Client Guide.
Syntax
RELSRV [ACCESS,{ READ | UPDATE | ACCESS } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [DOUNICODE,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [INTTOCHAR,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [LONGCHAR,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [MAXBLOBSIZE,blobsize [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [RECOVERY,{ NONE | COMMANDLOOKS | QUICKLOOKS | DEFERRED } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [ROWLIMIT,rowlimit [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [SCHEMA,schema-name [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [SPACETRIM,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [STRIPCTRL,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;]
Release 10R3: October 31, 2005 16-52 RELSRV UniAccess for OS 2200 System Administration Guide
[TRANSACTIVE,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [TRANSOPTION,{ NONE | LETSJ | SJIS } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [USERTRAN,{ YES | NO} [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [VERSION,version-name [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [WAITTIME,receive-waittime ;] [WORKSIZE,work-size [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ]
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
RELSRV n/a optional n/a n/a ACCESS n/a optional n/a n/a DOUNICODE n/a optional n/a n/a INTTOCHAR n/a optional n/a n/a LONGCHAR n/a optional n/a n/a MAXBLOBSIZE n/a optional n/a n/a RECOVERY n/a optional n/a n/a ROWLIMIT n/a optional n/a n/a SCHEMA n/a optional n/a n/a SPACETRIM n/a optional n/a n/a STRIPCTRL n/a optional n/a n/a TRANSACTIVE n/a optional n/a n/a TRANSOPTION n/a optional n/a n/a USERTRAN n/a optional n/a n/a VERSION n/a optional n/a n/a WAITTIME n/a optional n/a n/a WORKSIZE n/a optional n/a n/a
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference RELSRV 16-53
Parameters
ACCESS,{ READ | UPDATE | ACCESS },{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default UDS begin thread access mode for UARS. When READ is specified, the RECOVERY parameter in this statement is ignored. ACCESS is available to support features in RDMS 7R1 (SB6) and later releases; it should not be used with earlier RDMS versions. Defaults to UPDATE.
USEROVERRIDEON indicates that the client application can override the ACCESS,{ READ | UPDATE | ACCESS } setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the { READ | UPDATE | ACCESS } setting. Defaults to USEROVERRIDEOFF.
DOUNICODE,{YES | NO},{USEROVERRIDEON | USEROVERRIDEOFF} This parameter indicates how an RDMS 2200 NCHARACTER datatype column is presented to an ODBC client application by the UniAccess Relational Service. This parameter is only relevant when the UniAccess Relational Service is being used with ODBC clients.
If YES is specified, NCHARACTER columns are presented to the ODBC client application as SQL_UNICODE datatype columns; whereas, if NO is specified, NCHARACTER columns are treated as ODBC SQL_CHAR datatypes. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the DOUNICODE YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
INTTOCHAR,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UARS will convert RDMS 2200 SMALLINT and INT return columns to character strings. NO 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. YES indicates that UARS
Release 10R3: October 31, 2005 16-54 RELSRV UniAccess for OS 2200 System Administration Guide
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 INT columns have a precision of 12 and a scale of 0. Defaults to NO. Note Data contained in RDMS 2200 SMALLINT and INT columns that is greater than 32767 and 2147483647 respectively cannot be returned as fixed-point binary values. UARS will report conversion errors if this condition occurs. For maximum interoperability, RDMS 2200 administrators should ensure that data contained in SMALLINT and INT values can be contained in 16-bit and 32-bit fixed-point binary values.
USEROVERRIDEON indicates that the client application can override the INTTOCHAR YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
LONGCHAR,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Determines whether or not UARS will return long CHARACTER and NCHARACTER columns as ODBC SQL_LONGVARCHAR datatypes.
YES will cause UARS to return any CHARACTER column with a length greater than 255 characters as a TEXT column (ODBC SQL_LONGVARCHAR). YES will also cause UARS to return any NCHARACTER column with a length greater than 254 characters (precision of 127) as a TEXT column, if the RELSRV/UAUSER DOUNICODE parameter is set to NO. The COMSRV CHARTRUN setting is ignored.
NO will cause UARS to return CHARACTER columns as SQL_CHAR types; NCHARACTER columns will be returned as SQL_UNICODE types if the RELSRV/UAUSER DOUNICODE parameter is YES or as SQL_CHAR types if the RELSRV/UAUSER DOUNICODE parameter is
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference RELSRV 16-55
NO. Additionally, long CHARACTER and NCHARACTER columns will be truncated to 255 bytes and 254 bytes respectively, if the COMSRV CHARTRUN parameter is YES. Otherwise, UARS will return an error message. This functionality was supported by versions 6R1 and earlier of UniAccess.
Defaults to NO.
USEROVERRIDEON indicates that the client application can override the LONGCHAR YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
MAXBLOBSIZE,maxblobsize,{USEROVERRIDEON | USEROVERRIDEOFF} This parameter defines the maximum precision of a BLOB column that UARS returns to a single SELECT request. If the value is set to zero or is less than the BLOB column precision, then UARS does not allow retrieval of the BLOB column data and returns an error message indicating a MAXBLOBSIZE violation. Range 0 to 2147483647. Defaults to zero.
USEROVERRIDEON indicates that the client application can override the MAXBLOBSIZE setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override this setting. Defaults to USEROVERRIDEOFF.
RECOVERY,{ NONE | COMMANDLOOKS | QUICKLOOKS | DEFERRED },{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default UDS begin thread recovery options for users when update access has been specified. If the RELSRV ACCESS statement variable is READ or ACCESS, RECOVERY is ignored. Defaults to DEFERRED.
USEROVERRIDEON indicates that the client application can override the RECOVERY setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override this setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 16-56 RELSRV UniAccess for OS 2200 System Administration Guide
ROWLIMIT,rowlimit,{USEROVERRIDEON | USEROVERRIDEOFF} This parameter defines the maximum number of rows that UARS returns to a single SELECT request. If the value is set to zero, UARS does not limit the number of rows returned. If the number of rows generated by a SELECT request exceeds the ROWLIMIT defined value, UARS stops generating rows. Range 0 to 2147483647. Defaults to zero.
USEROVERRIDEON indicates that the client application can override the ROWLIMIT,rowlimit setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the rowlimit setting. Defaults to USEROVERRIDEOFF.
SCHEMA,schema-name,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default RDMS 2200 schema. Range 1 to 30 characters. Defaults to RDMS.
USEROVERRIDEON indicates that the client application can override the SCHEMA,schema-name setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the schema-name setting. Defaults to USEROVERRIDEOFF.
SPACETRIM,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not trailing spaces will be truncated. NO indicates that UARS will not trim trailing spaces from character fields before returning them to the user. YES indicates that trailing spaces will be truncated. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the SPACETRIM YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
STRIPCTRL,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UARS should convert control characters (values ranging from 0x01 to 0x1F) in request command buffers to spaces (value 0x20). 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. This is the functionality that was supported by versions
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference RELSRV 16-57
6R1 and earlier of UniAccess. If NO is specified, UARS will only convert control characters that are not part of a character literal to spaces. Defaults to YES.
USEROVERRIDEON indicates that the client application can override the STRIPCTRL YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
TRANSACTIVE,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not the user-supplied translation routines should be called by UARS. YES indicates that UARS will call the user-supplied translation routines. NO indicates that UARS will not call user-supplied translation routines. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the TRANSACTIVE YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
TRANSOPTION,{ NONE | LETSJ | SJIS },{USEROVERRIDEON | USEROVERRIDEOFF} This value serves two purposes. First, if TRANSACTIVE is YES, this value is passed to the user-supplied translation routine when called by UARS. Second, if this parameter is LETSJ or SJIS, UARS will also pass the value to RDMS. Based upon the value received, RDMS will determine the proper handling of Kanji identifiers.
NONE indicates that the value ua_no_xlate should be passed to the user- supplied translation routine if 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 translation routine if TRANSACTIVE is YES. It also indicates that RDMS should expect and return Kanji identifiers in LETS-J format. SJIS indicates that the value ua_sjis should be passed to the translation routine if TRANSACTIVE is YES. It also indicates that RDMS should expect and return Kanji identifiers in Shift-JIS format. Defaults to NONE.
Release 10R3: October 31, 2005 16-58 RELSRV UniAccess for OS 2200 System Administration Guide
USEROVERRIDEON indicates that the client application can override the TRANSOPTION NONE | LETSJ | SJIS setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the NONE | LETSJ | SJIS setting. Defaults to USEROVERRIDEOFF.
USERTRAN,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UARS will allow user-defined transactions to be initiated. YES indicates that UARS should process user-defined transaction requests (BEGIN TRAN). NO indicates that UARS should treat user- defined transaction requests as unrecognized commands. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the USERTRAN YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
VERSION,version-name,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default RDMS 2200 version for users. Range 1 to 30 characters. Defaults to PRODUCTION.
USEROVERRIDEON indicates that the client application can override the VERSION,version-name setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the version-name setting. Defaults to USEROVERRIDEOFF.
WAITTIME,receive-waittime The time in seconds the UARS transaction will wait for a request before terminating. Range 0 to 262143. Defaults to 0.
If RELSRV WAITTIME is set to a non-zero value, UARS simulates a resident transaction program by checking for input every 50 milliseconds. If an input is not received within the WAITTIME, the UARS transaction will terminate. Note A value of 0 causes UARS to terminate immediately after processing a request.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference RELSRV 16-59
WORKSIZE,work-size,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default RSA worksize. Range 2000 to 100000. Defaults to 10000.
USEROVERRIDEON indicates that the client application can override the WORKSIZE,work-size setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the work-size setting. Defaults to USEROVERRIDEOFF.
Example
RELSRV ACCESS,UPDATE,USEROVERRIDEOFF ; DOUNICODE,NO ; INTTOCHAR,NO ; LONCHAR,YES ; MAXBLOBSIZE,200000 ; RECOVERY,DEFERRED,USEROVERRIDEOFF ; ROWLIMIT,5000 ; SCHEMA,PAYROLL,USEROVERRIDEON ; SPACETRIM,YES ; STRIPCTRL,YES ; TRANSACTIVE, NO ; TRANSOPTION, NONE ; USERTRAN,NO ; VERSION,PRODUCTION ; WAITTIME,300 ; WORKSIZE,10000
Related UniAccess Configuration Statements
The UAUSER statement.
Release 10R3: October 31, 2005 16-60 RPCMAP UniAccess for OS 2200 System Administration Guide
RPCMAP
Purpose
This configuration statement maps RPC names of up to 30 characters to their appropriate VALTAB transaction codes (6 characters). The map record created by this statement is stored in UADT and used to map RPCs both to user-defined Server-Library transactions and to RDMS 2200 stored procedures. It is also used by UARS and UAHS to map UniAccess ODBC Driver catalog stored procedure requests (catalog RPCs) to the UARS or UAHS transaction respectively. (Table 16-5 describes how the RPCMAP statement is used by UniAccess services.)
The RPCMAP records used for Server-Library transactions and for RDMS stored procedures are defined by the System Administrator and should be placed in the Site Information configuration file (see page 16-9). These may be updated by the system administrator as necessary. The RPCMAP records used to support UADriver catalog RPCs are defined by AIS for UARS and UAHS are contained in the UA Information File. These records are required for proper UARS and UAHS functioning and should not be modified by the System Administrator.
Table 16-5: RPCMAP Record Usage
UniAccess Use of RPCMAP Author Location Service Record
UniAccess Maps RPCs to Server- System Administrator Site Information File Transaction Server Library transactions UniAccess ODBC Maps RPCs to RDMS System Administrator Site Information File Server for stored procedures RDMS 2200 Maps UADriver catalog AIS UA Information File RPCs to UARS UniAccess ODBC Maps UADriver catalog AIS UA Information File Server for DMS 2200 RPCs to UAHS
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference RPCMAP 16-61
The same RPC name can be used to access multiple VALTABs, either on an application group basis or a UACS basis:
• If an RPCMAP APPNUM value is configured, UACS will search for a match on the RPC name and the APPNUM value when looking for a mapped transaction code. To use this option, all UACSs in the same application group must use the same transaction codes for the RPC name, but can have different transaction codes for different application groups.
• If an RPCMAP COMSRV value is configured, UACS will search for a match on the RPC name and the COMSRV name when looking for a mapped transaction code. This requires an RPCMAP record for each UACS when multiple UACSs are running in the same application group; however, it provides more flexibility than the RPCMAP APPNUM option.
The system administrator may elect to have all unmapped RPCs routed to Server- Library transactions or to RDMS stored procedures using the OSPARM DFLTPROCENV parameter. This mechanism can help avoid difficulties created by having Server-Library transactions and RDMS stored procedures with the same name. The DFLTPROCENV parameter may also be used to minimize the amount of mapping required for certain processing environments (see page 16-44).
The RPCMAP statement is optional for UARS, UAHS, and UASL. If this statement is configured, the RPCNAME and TRANCODE parameters must be configured. If this statement is not configured, UACS will forward the RPC to the RDMS or UASL processing environment designated in the OSPARM DFLTPROCENV configuration parameter (see page 16-47). For Server-Library transactions, the first six characters of the RPC name will be assumed to be the TRANCODE; for RDMS stored procedures, a TRANCODE of %%UARS will be assigned.
A maximum of 30,000 RPCMAP statements may be configured.
Release 10R3: October 31, 2005 16-62 RPCMAP UniAccess for OS 2200 System Administration Guide
Syntax
RPCMAP [APPNUM,application-number ;] [COMSRV,communication-server ;] RPCNAME,rpcname ; TRANCODE,trancode
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
RPCMAP optional1 optional1 optional1 n/a APPNUM optional optional optional n/a COMSRV optional optional optional n/a RPCNAME optional optional optional n/a TRANCODE optional optional optional n/a
1 The RPCMAP statements included in the UA Information File are required for UASL, UARS, and UARS. Optionally, additional RPCMAP statements may be defined by the customer in the Site Information File.
Parameters
APPNUM,application-number Defines the application group in which this RPC is executed. The RPCMAP COMSRV parameter takes precedence over this parameter. This parameter and the COMSRV parameter are mutually exclusive. Range 1 to 16.
This parameter must match a COMSRV APPNUM parameter.
COMSRV,communication-server Defines the UniAccess Communication Server with which this RPC is associated. This parameter takes precedence over the RPCMAP APPNUM parameter. This parameter and the APPNUM parameter are mutually exclusive. Range 1 to 6 characters.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference RPCMAP 16-63
This parameter must match a COMSRV PROCNAM parameter.
RPCNAME,rpcname Defines user-created mappings for Server-Library transactions and RDMS stored procedures. Also defines UARS, UAHS, and the AIS-created catalog stored procedure mappings contained in the UA Information File. Range 1 to 30 characters.
TRANCODE,trancode Defines user-created transaction codes. This parameter must match the (TIP) VALTAB ACT statement. Range 1 to 6 characters.
Trancodes beginning with “%” are special values used to notify UACS that the actual trancode is defined by an associated COMSRV configuration statement. These values should not be modified.
RPCs are mapped to RDMS stored procedures by creating an RPCMAP statement with a TRANCODE of %%UARS. This transaction code causes UACS to forward the RPC to UARS and on to RDMS 2200 automatically.
Examples
RPCMAP RPCNAME,Update_customer_record ; TRANCODE,TRAN1
RPCMAP RPCNAME,Update_customer_record ; APPNUM,3 ; TRANCODE,TRAN2
RPCMAP RPCNAME,Update_customer_record ; COMSRV,UACS ; TRANCODE,TRAN3
In the examples above, if the Update_customer_record RPC request is received by the communication server named UACS, the TRAN3 transaction would be scheduled. If the Update_customer_record RPC request is received by a communication server other than UACS, but that transaction server is running in application group 3, the TRAN2 transaction would be scheduled. If the Update_customer_record RPC request is received by a communication server
Release 10R3: October 31, 2005 16-64 RPCMAP UniAccess for OS 2200 System Administration Guide
other than UACS, and that transaction server is running in an application group other than application group 3, the TRAN1 transaction would be scheduled.
Related UniAccess Configuration Statements
The APPNUM parameter of the COMSRV and APPINF statements.
The PROCNAM parameter of the COMSRV statement.
The UARSTRAN parameter of the COMSRV statement.
The DFLTPROCENV parameter of the OSPARM statement.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference SERVER 16-65
SERVER
Purpose
This statement defines servers to which UniAccess Client-Library programs may connect. Each statement defines one server. A maximum of 1,000 SERVER statements may be configured.
Syntax
SERVER [ADDR,internet-address ;] [HOSTNAME,host-name ;] [MSSQLSRVR,{ YES | NO } ;] NAME,server-name ; PORT,server-port
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
SERVER n/a n/a n/a required1 ADDR n/a n/a n/a optional2 HOSTNAME n/a n/a n/a optional MSSQLSRVR n/a n/a n/a optional NAME n/a n/a n/a required PORT n/a n/a n/a required
1 At least one SERVER statement is required to access a remote server from a UACL program. 2 This field is only optional if the HOSTNAME parameter is present. If the HOSTNAME parameter is not present, then the ADDR parameter is required.
Release 10R3: October 31, 2005 16-66 SERVER UniAccess for OS 2200 System Administration Guide
Parameters
ADDR,internet-address The Internet (IP) address of the server in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0-255 and at least one of the nnn values is non-zero.
This parameter is required if the HOSTNAME parameter is not present. The HOSTNAME parameter will override the ADDR parameter.
HOSTNAME,host-name The remote domain name of the server as defined in the CMS configuration. The HOSTNAME is translated to an IP address by UACS each time a connection to the server is opened. Range 1 to 210 characters.
The presence of the HOSTNAME parameter will cause UACS to query CMS 1100 or CPComm for an associated IP address that will override any specified ADDR parameter value. If both the ADDR and HOSTNAME parameters are present, then UACS will use the HOSTNAME to derive the Server remote IP.
— If CMS 1100 or CPComm returns success, then UACS will use the returned remote IP address as the Server IP address.
— If CMS 1100 or CPComm returns an error indicating a no-find condition (02), UACS will use the configured ADDR parameter IP address if present.
— Any other CMS 1100 or CPComm error will result in UACS refusing the connection request.
— If the HOSTNAME parameter is absent, UACS will use the ADDR parameter value as the Server IP address.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference SERVER 16-67
MSSQLSRVR,{ YES | NO} Indicates whether Microsoft SQL Server communications or standard UACS communications protocol should be used in communicating with the remote server. YES indicates that the remote server is Microsoft SQL Server version 7.0 or later and that UACS should observe standard Microsoft SQL Server communications protocol in conversing with the remote server. NO indicates that the remote server supports standard UACS communications protocol and that this should be used in conversing with the remote server. Defaults to NO.
NAME,server-name The name of the server. This is the name of the server that a UniAccess Client-Library program will specify during its connection sequence. Range 1 to 30 characters.
PORT,server-port The port of the server. Range 1 to 65535.
This parameter must match the port specified in the configuration of the server-name.
Example
SERVER NAME,MSSQL7 ; PORT,2025 ; HOSTNAME,AIS-RESTON ; MSSQLSRVR,YES
Related UniAccess Configuration Statements
None.
Release 10R3: October 31, 2005 16-68 UAMESG UniAccess for OS 2200 System Administration Guide
UAMESG
Purpose
This statement defines messages that may be returned to the client by various components of the UniAccess System. Each statement defines one message. A maximum of 1,000 UAMESG statements may be configured.
The UAMESG records defined by AIS for UniAccess System components are contained in the UA Information File (see page 16-9). The UAMESG records defined by the system administrator should be placed in the Site Information configuration file.
The UAMESG records, which are maintained by UADT, contain the message number and the actual text for each message. You may change the text of AIS- defined messages, but you may not change the numbers. The numbers are used internally as keys by UniAccess components. (See page 10-7 for more information on the message definitions and page D-69 for the list of the server program messages maintained by UADT.)
Syntax
UAMESG CODE,message-code ; TEXT,message-text
UniAccess System Requirements
UniAccess System Component Parameter UASL UARS UAHS UACL
UAMESG optional1 optional1 optional1 optional1 CODE optional optional optional optional TEXT optional optional optional optional
1 The UAMESG statements included in the UA Configuration File are required. Optionally, additional UAMESG statements may be defined by the customer in the Site Information File.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAMESG 16-69
Parameters
CODE,message-code SQL Server style message code. Range 1 to 99999.
This parameter is related to the UniAccess UAMMAP MAPCODE parameter.
TEXT,message-text SQL Server style message text. Range 1 to 100 characters.
Example
UAMESG CODE,103 ; TEXT,"String is too long (RDMS: %s)"
Related UniAccess Configuration Statements
The UAMMAP MAPCODE parameter.
Release 10R3: October 31, 2005 16-70 UAMM UniAccess for OS 2200 System Administration Guide
UAMM
Purpose
This statement defines how UniAccess Message Manager (UAMM) memory is allocated. Server-Library and Client-Library connections require a UAMM process slot. Each process slot requires one or more memory blocks to transfer message buffers between client and server applications. (See page 8-2 for details about UAMM optimization.)
Syntax
UAMM [BLOCKCNT,blockcount ;] [BLOCKSIZE,blocksize ;] [MAXBLKS,max-blocks ;] [PROCCNT,proc-count ]
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
UAMM optional optional optional optional BLOCKCNT optional optional optional optional BLOCKSIZE optional optional optional optional MAXBLKS optional optional optional optional PROCCNT optional optional optional optional
Parameters
BLOCKCNT,blockcount Defines the total number of UAMM memory blocks to allocate. Range 1 to 262143. Defaults to the PROCCNT value.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAMM 16-71
BLOCKSIZE,blocksize Defines the size in bytes of each UAMM memory block. This value limits the maximum size of a TDS buffer that can be requested by a client application. Valid values are 512, 1024, 2048, or 4096. Defaults to 512. Note BLOCKSIZE controls the buffer size. It does not limit the amount of data that can be transferred between the client and server applications.
MAXBLKS,max-blocks Defines the maximum number of UAMM memory blocks that will be allocated to a process. Buffer allocation requests will be suspended when this limit is reached and will remain suspended until the number of allocated memory blocks falls back to zero. This is to prevent unconstrained buffer overload. Range is 1 to the BLOCKCNT value. Defaults to 10. Note MAXBLKS controls the number of buffers that will be allocated to a process. It does not limit the amount of data that can be transferred between the client and server applications.
PROCCNT,proc-count Defines the number of process slots supported by UAMM for all UACSs. Range 1 to 65000. Defaults to the number of PIDs allocated among all COMSRVs. Note The number of current connections supported by a UACS execution is the smaller of the COMSRV PIDCNT parameter, the UAMM PROCCNT parameter, or the sum of concurrent connections supported by the product keys (the UACLPRODKEY, UAHSPRODKEY, UARSPRODKEY, and UASLPRODKEY parameters of the OSPARM statement).
Release 10R3: October 31, 2005 16-72 UAMM UniAccess for OS 2200 System Administration Guide
Example
UAMM BLOCKCNT,500 ; BLOCKSIZE,4096 ; MAXBLKS,5 ; PROCCNT,100
Related UniAccess Configuration Statements
None.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAMMAP 16-73
UAMMAP
Purpose
This statement serves two purposes: it maps RDMS 2200 error codes to SQL Server error codes, and it maintains detailed error information for all UAMESG message records. The UAMMAP records are maintained in UADT for use by the UARS transaction in receiving and returning RDMS 2200 error codes. (See page 10-5 for more information on the UAMMAP record; the list of messages generated from it begins on page D-69.) A maximum of 1,000 UAMMAP statements may be configured.
The UAMMAP records defined by AIS for UARS are contained in the UA Information File (see page 16-9). These records can be modified by the System Administrator. The UAMMAP records defined by the System Administrator should be placed in the Site Information File.
Syntax
UAMMAP CODE,message-code ; [FATAL,{ YES | NO } ;] FLAG,flag ; [MAPCODE,map-code ;] [SEVERITY,severity ;] [STATE,state ;]
Release 10R3: October 31, 2005 16-74 UAMMAP UniAccess for OS 2200 System Administration Guide
UniAccess System Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
UAMMAP optional1 optional1 optional1 optional1 CODE optional optional optional optional FATAL optional optional optional optional FLAG optional optional optional optional MAPCODE optional optional optional optional SEVERITY optional optional optional optional STATE optional optional optional optional
1 The UAMMAP statements included in the UA Information File are required. Optionally, additional UAMMAP statements may be defined by the customer in the Site Information File.
Parameters
CODE,message-code Defines the message code to be returned to the client application. Range 1 to 99999.
FATAL,{ YES | NO } Indicates whether or not a message is fatal. YES indicates the message is fatal. NO indicates the message is not fatal. Defaults to YES.
FLAG,flag Indicates the map flag for the error message.‘S’ indicates major RDMS 2200 error status codes; ‘M’ indicates minor RDMS 2200 error numbers; ‘U’ indicates UniAccess error codes.
MAPCODE,map-code An RDMS 2200 error code. RDMS 2200 error codes are either four digit major error statuses or five digit minor error numbers. Defaults to 0.
This parameter is related to the UniAccess UAMESG CODE parameter.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAMMAP 16-75
SEVERITY,severity Defines the severity of the message. Range 0 to 99. Defaults to 15.
STATE,state Defines the state of the message. Range 0 to 99. Defaults to 0.
Example
UAMMAP CODE,105 ; FATAL,YES ; FLAG,S ; MAPCODE,206 ; SEVERITY,15 ; STATE,0
Related UniAccess Configuration Statements
The CODE should have a corresponding UAMESG CODE entry.
Release 10R3: October 31, 2005 16-76 UASLCS UniAccess for OS 2200 System Administration Guide
UASLCS
Purpose
This statement defines the character set translation performed on incoming language requests, input character parameters, output character parameters, character result set columns, and return messages for all UASL transactions. Translations can be specified for incoming data, outgoing data, or both. If a translation is not specified for either incoming data or outgoing data, no translation will be performed for that data path. Only one UASLCS statement can be specified.
Syntax
UASLCS NAME,character-set-name ; [CTOS,client-to-server-translation ;] [STOC,server-to-client-translation ]
UniAccess System Requirements
UniAccess System Components Statement Parameters UASL UARS UAHS UACL
UASLCS optional optional optional n/a CTOS optional optional optional n/a NAME optional optional optional n/a STOC optional optional optional n/a
Parameters
CTOS,client-to-server-translation This parameter defines the client-to-server translation that will be performed on language requests processed by the language transaction, and on RPC input character parameters processed by UASL transactions. Characters with hexadecimal values from 00 to FF are valid. (See the
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UASLCS 16-77
Character Set Definition section on page 16-6 for further details about the format of this variable.)
NAME,character-set-name This parameter defines the name of the character set. It is not used by the UniAccess system and is strictly for documentation purposes. Range 1 to 30 characters.
STOC,server-to-client-translation This parameter defines the server-to-client translation that will be performed on RPC output character parameters, on character columns in result sets, and on messages returned by all UASL transactions. Characters with hexadecimal values from 00 to FF are valid. See the Character Set Definition section earlier in this chapter for further details about the format of this variable. Note This parameter will affect messages sent by all server programs including those messages defined by UAMESG statements.
Example
UASLCS NAME,Convert_To_UpperCase ; CTOS,(61-41,62-42,63-43,64-44,65-45,66-46,67-47, \ 68-48,69-49,6a-4a,6b-4b,6c-4c,6d-4d,6e-4e, \ 6f-4f,70-50,71-51,72-52,73-53,74-54,75-55, \ 76-56,77-57,78-58,79-59,7a-5a) ; STOC,(61-41,62-42,63-43,64-44,65-45,66-46,67-47, \ 68-48,69-49,6a-4a,6b-4b,6c-4c,6d-4d,6e-4e, \ 6f-4f,70-50,71-51,72-52,73-53,74-54,75-55, \ 76-56,77-57,78-58,79-59,7a-5a)
Related UniAccess Configuration Statements
None.
Release 10R3: October 31, 2005 16-78 UAUSER UniAccess for OS 2200 System Administration Guide
UAUSER
Purpose
This statement defines UniAccess System users. Each time a request is received by UACS, the login information packaged with the request is validated against the list of UAUSER records maintained in UADT. In addition UAUSER records perform the following functions:
• For UARS, the records define the RDMS 2200 initialization commands that UARS automatically executes for each client request. Defaults for UARS- specific parameters may be set in the RELSRV configuration statement.
• For UAHS, the records define the DMS 2200 initialization commands that UAHS automatically executes for each client request. Defaults for UAHS- specific parameters may be set in the HIERSRV configuration statement.
• For UACL programs, the COMSRV entry determines which UACS the client program will connect to.
(For information on user records as a component of UniAccess System security, see page 9-6.)
Most parameters relevant to UARS and UAHS may be set to be client-side configurable; that is, they can allow client applications to override the parameter’s setting in the UAUSER statement. These parameters correspond to required and optional settings for ODBC and Open Client applications. ODBC clients set these options through the UADriver Setup dialog boxes or through connection string attribute names. Open Clients may set these options through the UARS and UAHS SET commands. (See the Client Option Correspondence tables in the HIERSRV and RELSRV sections for a list of these relationships.)
Note In order to change a RELSRV or HIERSRV USEROVERRIDE value for a UAUSER record, you must also define the UAUSER parameter value. The UAUSER value will not default to the RELSRV or HIERSRV value if the USEROVERRIDE settings are different.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-79
A UAUSER record with a USERID of “@@@@@@@@@@@@” has special meanings to UARS and UAHS and to UACL. For UARS and UAHS, it serves as a default userid for users who are not required to be assigned a UAUSER record. That is, it sets up a possible default UAUSER record. For UACL, this record allows any Client-Library application to connect to the UACS specified in the record if the one specified by the client application is not configured. That is, the record sets up a default UACS for Client-Library applications.
A maximum of 20,000 UAUSER statements may be configured.
Syntax
UAUSER [ACCESS,{ READ | UPDATE | ACCESS } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [AREASEARCH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [COMSRV,communication-server ;] [DEBUG,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [DISTTRAN,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [DOUNICODE,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [INTTOCHAR,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [LONGCHAR,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [MAXBLOBSIZE,blobsize [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [RECOVERY,{ NONE | COMMANDLOOKS | QUICKLOOKS | DEFERRED } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [ROWLIMIT,uars-rowlimit [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [ROWLIMITH,uahs-rowlimit [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [SCHEMA,uars-schema-name [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;]
Release 10R3: October 31, 2005 16-80 UAUSER UniAccess for OS 2200 System Administration Guide
[SCHEMAH,uahs-schema-name [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [SPACETRIM,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [SPACETRIMH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [STRIPCTRL,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [STRIPCTRLH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [TRANSACTIVE,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [TRANSACTIVEH,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [TRANSOPTION,{ NONE | LETSJ | SJIS } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [TRANSOPTIONH,{ NONE | LETSJ | SJIS } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] USERID,user-id ; [USERTRAN,{ YES | NO } [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [VERSION,version-name [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ;] [WORKSIZE,work-size [ ,{USEROVERRIDEON | USEROVERRIDEOFF}] ]
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-81
UniAccess System Requirements
UniAccess System Components Statement Parameters UASL UARS UAHS UACL
UAUSER required1 required2 required required3 ACCESS n/a optional n/a n/a AREASEARCH n/a n/a optional n/a COMSRV n/a n/a n/a required DEBUG n/a n/a optional n/a DISTTRAN optional optional optional4 n/a DOUNICODE n/a optional n/a n/a INTTOCHAR n/a optional n/a n/a LONGCHAR n/a optional n/a n/a MAXBLOBSIZE n/a optional n/a n/a RECOVERY n/a optional n/a n/a ROWLIMIT n/a optional n/a n/a ROWLIMITH n/a n/a optional n/a SCHEMA n/a optional n/a n/a SCHEMAH n/a n/a optional n/a SPACETRIM n/a optional n/a n/a SPACETRIMH n/a n/a optional n/a STRIPCTRL n/a optional n/a n/a STRIPCTRLH n/a n/a optional n/a TRANSACTIVE n/a optional n/a n/a
1The UAUSER statement is not required for UASL if COMSRV USEUAUSER is set to NO. 2 A UAUSER statement is not required for each userid if a default UAUSER record is configured and if COMSRV USEUAUSER is set to NO. 3 A UAUSER statement is not required for each userid if a default UAUSER record is configured. 4 If UAHS is used for the UADriver Language Transaction Type and if UASL transactions are also present, this parameter is optional. This parameter is not applicable when UAHS is being used without UASL.
Release 10R3: October 31, 2005 16-82 UAUSER UniAccess for OS 2200 System Administration Guide
UniAccess System Components Statement Parameters UASL UARS UAHS UACL
TRANSACTIVEH n/a n/a optional n/a TRANSOPTION n/a optional n/a n/a TRANSOPTIONH n/a n/a optional n/a USERID required required required required USERTRAN n/a optional n/a n/a VERSION n/a optional n/a n/a WORKSIZE n/a optional n/a n/a
1The UAUSER statement is not required for UASL if COMSRV USEUAUSER is set to NO. 2 A UAUSER statement is not required for each userid if a default UAUSER record is configured and if COMSRV USEUAUSER is set to NO. 3 A UAUSER statement is not required for each userid if a default UAUSER record is configured. 4 If UAHS is used for the UADriver Language Transaction Type and if UASL transactions are also present, this parameter is optional. This parameter is not applicable when UAHS is being used without UASL.
Parameters
ACCESS,{ READ | UPDATE | ACCESS },{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default UDS begin thread access mode. This field is used by UARS only. When READ is specified, the RECOVERY parameter in this statement is ignored. ACCESS is available to support features in RDMS 7R1 (SB6) and later releases; it should not be used with earlier RDMS versions. Defaults to the RELSRV ACCESS value.
USEROVERRIDEON indicates that the client application can override the ACCESS setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override this setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-83
AREASEARCH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UAHS will search an entire database area if the WHERE clause of the SELECT command being processed does not contain sufficient information to FETCH the DMS data through its primary location mode. Since this type of search may have a significant impact on the system, the administrator can either allow or disallow the capability. This field is used by UAHS only.
YES indicates that area searches are allowed; NO indicates that they are not allowed. Defaults to the HIERSRV AREASEARCH value. USEROVERRIDEON indicates that the client application can override the AREASEARCH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
COMSRV,communication-server Defines the UniAccess Communication Server that a UniAccess Client- Library application will use when opening a connection to a remote server. This field is used by UACL only. Defaults to null.
This parameter is related to the UniAccess COMSRV PROCNAM and CMS 2200 1100 or CPComm PROCESS statement variables.
DEBUG,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UAHS will allow client applications to initiate debug tracing of SQL requests. The debug trace output will be in the UAHS transaction print file. It provides information about the path used to access the DMS data. Debug tracing increases system overhead. This field is used by UAHS only.
YES indicates that debug is allowed; NO indicates that it is not. Defaults to the HIERSRV DEBUG value.
USEROVERRIDEON indicates that the client application can override the DEBUG YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 16-84 UAUSER UniAccess for OS 2200 System Administration Guide
DISTTRAN,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not a client can participate in distributed transactions. NO indicates that the client may not participate in distributed transactions. YES indicates that the client may participate in distributed transactions. Defaults to NO.
USEROVERRIDEON indicates that the client application can override the DISTTRAN YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF. Note This parameter is not inherited: it cannot be specified on either a HIERSRV or RELSRV statement.
DOUNICODE,{YES | NO},{USEROVERRIDEON | USEROVERRIDEOFF} This parameter indicates how RDMS 2200 NCHARACTER datatype columns are presented to an ODBC client application by UARS. This parameter is only relevant when the UniAccess Relational Service is being used with ODBC clients.
If YES is specified, NCHARACTER columns are presented to the ODBC client application as SQL_UNICODE datatype columns; whereas, if NO is specified NCHARACTER columns are treated as ODBC SQL_CHAR datatypes. Defaults to the RELSRV DOUNICODE value.
USEROVERRIDEON indicates that the client application can override the DOUNICODE YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
INTTOCHAR,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UARS will convert RDMS 2200 SMALLINT and INT return columns to character strings. NO 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. YES indicates that UARS will convert SMALLINT and INT columns to zero-filled character strings
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-85
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 INT columns have a precision of 12 and a scale of 0. This field is used by UARS only. Defaults to the RELSRV INTTOCHAR value. Note Data contained in RDMS 2200 SMALLINT and INT columns that is greater than 32767 and 2147483647 respectively cannot be returned as fixed-point binary values. UARS will report conversion errors if this condition occurs. For maximum interoperability, RDMS 2200 administrators should ensure that data contained in SMALLINT and INT values can be contained in 16-bit and 32-bit fixed-point binary values.
USEROVERRIDEON indicates that the client application can override the INTTOCHAR YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
LONGCHAR,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Determines whether or not UARS will return long CHARACTER and NCHARACTER columns as ODBC SQL_LONGVARCHAR datatypes. YES will cause UARS to return any CHARACTER column with a greater length than 255 characters as a TEXT column (ODBC SQL_LONGVARCHAR). YES will also cause UARS to return any NCHARACTER column with a length greater than 254 characters (precision of 127) as a TEXT column, if the RELSRV/UAUSER DOUNICODE parameter is set to NO.
NO will cause UARS to return CHARACTER columns as SQL_CHAR types; NCHARACTER columns will be returned as SQL_UNICODE types if the RELSRV/UAUSER DOUNICODE parameter is YES or as SQL_CHAR types if the RELSRV/UAUSER DOUNICODE parameter is NO. Additionally, long CHARACTER and NCHARACTER columns will be truncated to 255 bytes and 254 bytes respectively, if the COMSRV CHARTRUN parameter is TRUE. Otherwise, UARS will return an error
Release 10R3: October 31, 2005 16-86 UAUSER UniAccess for OS 2200 System Administration Guide
message. This is the functionality that was supported by versions 6R1 and earlier of UniAccess.
This field is used by UARS only. Defaults to the RELSRV LONGCHAR value.
USEROVERRIDEON indicates that the client application can override the LONGCHAR YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
MAXBLOBSIZE,maxblobsize,{USEROVERRIDEON | USEROVERRIDEOFF} This parameter defines the maximum precision of a BLOB column that UARS returns to a single SELECT request. If the value is set to zero or is less than the BLOB column precision, then UARS does not allow retrieval of the BLOB column data and returns an error message indicating a maximum BLOB size violation. Range 0 to 2147483647. Defaults to zero.
USEROVERRIDEON indicates that the client application can override the MAXBLOBSIZE setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override this setting. This field is used by UARS only. Defaults to USEROVERRIDEOFF.
RECOVERY,{ NONE | COMMANDLOOKS | QUICKLOOKS | DEFERRED },{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default UDS begin thread recovery options for this user when update access has been specified. If the UAUSER ACCESS statement variable is READ or ACCESS, RECOVERY is ignored. This field is used by UARS only. Defaults to the RELSRV RECOVERY value.
USEROVERRIDEON indicates that the client application can override the RECOVERY setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override this setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-87
ROWLIMIT,uars-rowlimit,{USEROVERRIDEON | USEROVERRIDEOFF} This parameter defines the maximum number of rows that UARS returns to a single SELECT request. If the value is set to zero, UARS does not limit the number of rows returned. If the number of rows generated by a SELECT request exceeds the ROWLIMIT defined value, UARS stops generating rows. This field is used by UARS only. Range 0 to 2147483647. Defaults to the RELSRV ROWLIMIT value.
USEROVERRIDEON indicates that the client application can override the ROWLIMIT,uars-rowlimit setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the uars-rowlimit setting. Defaults to USEROVERRIDEOFF.
ROWLIMITH,uahs-rowlimit,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the maximum number of rows that UAHS returns to a single SELECT request. If the value is set to 0, UAHS does not limit the number of rows returned. If the number of rows generated by a SELECT request exceeds the ROWLIMIT defined value, UAHS stops generating rows. This field is used by UAHS only. Range 0 to 2147483647. Defaults to the HIERSRV ROWLIMITH value.
USEROVERRIDEON indicates that the client application can override the ROWLIMITH,uahs-rowlimit setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the uahs-rowlimit setting. Defaults to USEROVERRIDEOFF.
SCHEMA,uars-schema-name,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default RDMS 2200 schema for UARS. Range 1 to 30 characters. This field is used by UARS only. Defaults to the RELSRV SCHEMA value.
USEROVERRIDEON indicates that the client application can override the SCHEMA,schema-name setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the schema-name setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 16-88 UAUSER UniAccess for OS 2200 System Administration Guide
SCHEMAH,uahs-schema-name,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default UAHS database for UAHS. Range 1 to 30 characters. This field is used by UAHS only. Defaults to the HIERSRV SCHEMAH value.
USEROVERRIDEON indicates that the client application can override the SCHEMAH,uahs-schema-name setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the uahs-schema-name setting. Defaults to USEROVERRIDEOFF.
SPACETRIM,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not trailing spaces will be truncated. NO indicates that UARS will not trim trailing spaces from character fields before returning them to the user. YES indicates that trailing spaces will be truncated. This field is used by UARS only. Defaults to the RELSRV SPACETRIM value.
USEROVERRIDEON indicates that the client application can override the SPACETRIM YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
SPACETRIMH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not trailing spaces will be truncated. NO indicates that UAHS will not trim trailing spaces from character fields before retuning them to the user. YES indicates that trailing spaces will be trimmed. This field is used by UAHS only. Defaults to the HIERSRV SPACETRIMH value.
USEROVERRIDEON indicates that the client application can override the SPACETRIMH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-89
STRIPCTRL,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UARS should convert control characters (values ranging from 0x01 to 0x1F) in request command buffers to spaces (value 0x20). 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. This is the functionality that was supported by versions 6R1 and earlier of UniAccess. If NO is specified, UARS will only convert control characters that are not part of a character literal to spaces. This field is used by UARS only. Defaults to the RELSRV STRIPCTRL value.
USEROVERRIDEON indicates that the client application can override the STRIPCTRL YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF. STRIPCTRLH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UAHS should convert control characters (values ranging from 0x01 to 0x1F) in request command buffers to spaces (value 0x20). 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. This field is used by UAHS only. Defaults to the HIERSRV STRIPCTRLH value. USEROVERRIDEON indicates that the client application can override the STRIPCTRLH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
TRANSACTIVE,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not the user-supplied translation routines should be called by UARS. NO indicates that UARS will not call the user-supplied translation routines. YES indicates that UARS will call the user-supplied translation routines. Defaults to the RELSRV TRANSACTIVE value.
USEROVERRIDEON indicates that the client application can override the TRANSACTIVE YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 16-90 UAUSER UniAccess for OS 2200 System Administration Guide
TRANSACTIVEH,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not the user-supplied translation routines should be called by UAHS. NO indicates that UAHS will not call the user-supplied translation routines. YES indicates that UAHS will call the user-supplied translation routines. Defaults to the HIERSRV TRANSACTIVEH value.
USEROVERRIDEON indicates that the client application can override the TRANSACTIVEH YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
TRANSOPTION,{ NONE | LETSJ | SJIS },{USEROVERRIDEON | USEROVERRIDEOFF} This value serves two purposes. First, if TRANSACTIVE is YES, this value is passed to the user-supplied translation routine when called by UARS. Second, if this parameter is LETSJ or SJIS, UARS will also pass the value to RDMS. Based upon the value received, RDMS will determine the proper handling of Kanji identifiers.
NONE indicates that the value ua_no_xlate should be passed to the user- supplied translation routine if 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 translation routine if TRANSACTIVE is YES. It also indicates that RDMS should expect and return Kanji identifiers in LETS-J format. SJIS indicates that the value ua_sjis should be passed to the translation routine if TRANSACTIVE is YES. It also indicates that RDMS should expect and return Kanji identifiers in Shift-JIS format. Defaults to the RELSRV TRANSOPTION value.
USEROVERRIDEON indicates that the client application can override the TRANSOPTION NONE | LETSJ | SJIS setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the NONE | LETSJ | SJIS setting. Defaults to USEROVERRIDEOFF.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-91
TRANSOPTIONH,{ NONE | LETSJ | SJIS },{USEROVERRIDEON | USEROVERRIDEOFF} Specifies a value to be passed to the user-supplied translation routine if UAHS calls the translation routine (that is, if TRANSACTIVE is YES). NONE indicates that the value ua_no_xlate should be passed to the user- supplied translation routine. LETSJ indicates that the value ua_letsj should be passed to the translation routine. SJIS indicates that the value ua_sjis should be passed to the translation routine. Defaults to the HIERSRV TRANSOPTIONH value.
USEROVERRIDEON indicates that the client application can override the TRANSOPTIONH NONE | LETSJ | SJIS setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the NONE | LETSJ | SJIS setting. Defaults to USEROVERRIDEOFF.
USERID,user-id User identification string. Range 1 to 30 characters. If the COMSRV USEUAUSER parameter is set to YES, one userid must be assigned to each UASL, UAHS, or UARS user. The parameter is always required for Client-Library users. (These users must be configured with the same userid on both the UniAccess System and any remote server being accessed.)
When the COMSRV USEUAUSER option is set to NO, the system administrator must set up a default UAUSER record with a USERID of “@@@@@@@@@@@@.” This allows ODBC or Open Client applications that have not been configured in UADT to access UARS or UAHS, which require userid information. When client applications send language requests to UARS or UAHS, the language transaction searches for a unique userid and then for the “@@@@@@@@@@@@” userid. If both searches fail, an error message is returned to the client application. Note Note that the UACF processor will issue a warning if any COMSRV USEUAUSER option is set to NO and no UAUSER record has been configured with a USERID of “@@@@@@@@@@@@”. The net effect of the two configurations is that UACS tries to treat login userids as if the COMSRV USEUAUSER option were set to YES.
Release 10R3: October 31, 2005 16-92 UAUSER UniAccess for OS 2200 System Administration Guide
With UACL, the system administrator may set up a default UACS by creating a UAUSER record with a USERID of “@@@@@@@@@@@@.” If the userid specified in the Client-Library program is not defined in UADT, or if the UACS specified by the client application is not configured, the Client-Library program searches for the “@@@@@@@@@@@@” record to determine which UACS to use. If this search fails, an error is returned to the Client-Library application. If TIP session control is configured, the user-id must be a valid OS 2200 user. This requirement creates dependencies on the SIMAN configuration. The user must be allowed TIP access. The user must be configured in such a manner that the default response can be used for all session control input beyond USER-ID/PASSWORD.
USERTRAN,{ YES | NO },{USEROVERRIDEON | USEROVERRIDEOFF} Indicates whether or not UARS will allow user-defined transactions to be initiated. YES indicates that UARS should process user-defined transaction requests (BEGIN TRAN). NO indicates that UARS should treat user- defined transaction requests as unrecognized commands. This field is used by UARS only. Defaults to the RELSRV USERTRAN value.
USEROVERRIDEON indicates that the client application can override the USERTRAN YES | NO setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the YES | NO setting. Defaults to USEROVERRIDEOFF.
VERSION,version-name,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default RDMS 2200 version for this user. Range 1 to 30 characters. This field is used by UARS only. Defaults to the RELSRV VERSION value.
USEROVERRIDEON indicates that the client application can override the VERSION,version-name setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the version-name setting. Defaults to USEROVERRIDEOFF.
WORKSIZE,work-size,{USEROVERRIDEON | USEROVERRIDEOFF} Defines the default RSA worksize. Range 2000 to 100000. This field is used by UARS only. Defaults to the RELSRV WORKSIZE value.
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference UAUSER 16-93
USEROVERRIDEON indicates that the client application can override the WORKSIZE,work-size setting in the UniAccess Configuration File; USEROVERRIDEOFF indicates that the client application cannot override the work-size setting. Defaults to USEROVERRIDEOFF.
Example
UAUSER USERID,demouser1 ; ACCESS,UPDATE ; AREASEARCH,YES ; COMSRV,UACS ; DEBUG,YES ; DISTTRAN,YES ; DOUNICODE,NO ; INTTOCHAR,NO ; LONGCHAR,YES ; MAXBLOBSIZE,200000 ; RECOVERY,DEFERRED ; ROWLIMIT,5000 ; ROWLIMITH,5000 ; SCHEMA,UASAMPLE ; SCHEMAH,UADMS ; SPACETRIM,YES ; SPACETRIMH,YES ; STRIPCTRL,YES ; STRIPCTRLH,YES ; TRANSACTIVE,NO ; TRANSACTIVEH,NO ; TRANSOPTION,NONE ; TRANSOPTIONH,NONE ; USERTRAN,NO ; VERSION,PRODUCTION ; WORKSIZE,10000
Related UniAccess Configuration Statements
The HIERSRV statement. The RELSRV statement. The PROCNAM and USEUAUSER parameters of the COMSRV statement.
Release 10R3: October 31, 2005 16-94 Summary UniAccess for OS 2200 System Administration Guide
Summary of Configuration Statement Requirements
Table 16-6: Summary of Configuration Statement Requirements
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
APPINF required required required n/a APPNAME required required required n/a APPNUM required required required n/a MCBBDI required required required n/a UAHSTIPF n/a n/a required n/a UDSBDI optional optional n/a n/a CABNUM n/a n/a n/a n/a ID n/a n/a n/a n/a VA LU E n/a n/a n/a n/a CHARSET n/a n/a n/a optional1 FILE n/a n/a n/a optional NAME n/a n/a n/a optional COMSRV required required required required APPNUM required required required n/a2 BADPIDTIMOUT optional optional optional n/a BLKPIDTIMOUT optional optional optional n/a CHARTRUN optional optional optional n/a CMSNUM optional optional optional n/a CONFIRMTERM optional optional optional optional CONTIMOUT optional optional optional n/a DFLTTRAN optional optional optional n/a KEEPALIVES optional optional optional n/a KEEPALIVINT optional optional optional n/a LISTENPRT optional optional optional n/a
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference Summary 16-95
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
COMSRV LNGASGATTR optional optional optional n/a (continued) LNGFNAME optional optional optional n/a LNGTRACE optional optional optional n/a LOGOFFTRAN optional optional optional n/a LOGONTRAN optional optional optional n/a MAXSENDS optional optional optional n/a MULTIIP optional optional optional optional NWRTIMOUT optional optional optional optional NWWTIMOUT optional optional optional optional PIDCNT required required required required PIDSTART required required required required PRIORITY optional optional optional optional PROCNAM required required required required PROCPSWD required required required required SENDDATABYT optional optional optional n/a SYSLOG optional optional optional optional SYSLOGTYPE optional optional optional optional TIMOUTWAIT optional optional optional optional TIPQCNT optional optional optional optional TIPQSIZE optional optional optional n/a TRCASGATTR optional optional optional optional TRCFNAME optional optional optional optional TRCLEVEL optional optional optional optional TSAMCNT optional optional optional optional UACSTYPE optional optional optional optional2 UAHSTRAN optional optional optional n/a UAINTRAN optional optional optional n/a
Release 10R3: October 31, 2005 16-96 Summary UniAccess for OS 2200 System Administration Guide
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
COMSRV UARSTRAN optional optional optional n/a (continued) UARSTRAN2 optional optional optional n/a UARSTRAN3 optional optional optional n/a UARSTRAN4 optional optional optional n/a USERTRAN optional optional optional n/a USEUAUSER optional optional optional n/a WAITTIME optional optional optional optional HIERSRV n/a n/a required n/a AREASEARCH n/a n/a optional n/a DEBUG n/a n/a optional n/a ROWLIMITH n/a n/a optional n/a SCHEMAH n/a n/a required n/a SPACETRIMH n/a n/a optional n/a STRIPCTRLH n/a n/a optional n/a TRANSACTIVEH n/a n/a optional n/a TRANSOPTIONH n/a n/a optional n/a WAITTIME n/a n/a optional n/a LOCALE n/a n/a n/a optional3 CHARSET n/a n/a n/a optional FILE n/a n/a n/a optional LANGUAGE n/a n/a n/a optional NAME n/a n/a n/a optional SORTORDER n/a n/a n/a optional OSPARM required required required required DFLTPROCENV optional optional n/a n/a NEWPWDPRMPT optional optional optional n/a SESSCTRL optional4 optional4 optional4 n/a SYSTEMPRMPT optional optional optional n/a
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference Summary 16-97
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
OSPARM UACLPRODKEY optional optional optional required (continued) UAHSPRODKEY optional optional required optional UARSPRODKEY optional required optional optional UASLPRODKEY required optional optional optional UIDPWDPRMPT optional optional optional n/a RELSRV n/a optional n/a n/a ACCESS n/a optional n/a n/a DOUNICODE n/a optional n/a n/a INTTOCHAR n/a optional n/a n/a LONGCHAR n/a optional n/a n/a MAXBLOBSIZE n/a optional n/a n/a RECOVERY n/a optional n/a n/a ROWLIMIT n/a optional n/a n/a SCHEMA n/a optional n/a n/a SPACETRIM n/a optional n/a n/a STRIPCTRL n/a optional n/a n/a TRANSACTIVE n/a optional n/a n/a TRANSOPTION n/a optional n/a n/a USERTRAN n/a optional n/a n/a VERSION n/a optional n/a n/a WAITTIME n/a optional n/a n/a WORKSIZE n/a optional n/a n/a RPCMAP optional6 optional6 optional6 n/a APPNUM optional optional optional n/a COMSRV optional optional optional n/a RPCNAME optional optional optional n/a TRANCODE optional optional optional n/a
Release 10R3: October 31, 2005 16-98 UniAccess for OS 2200 System Administration Guide
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
SERVER n/a n/a n/a required7 ADDR n/a n/a n/a optional8 HOSTNAME n/a n/a n/a optional NAME n/a n/a n/a required PORT n/a n/a n/a required MSSQLSRVR n/a n/a n/a optional UAMESG optional9 optional9 optional9 optional9 CODE optional optional optional optional TEXT optional optional optional optional UAMM optional optional optional optional BLOCKCNT optional optional optional optional BLOCKSIZE optional optional optional optional MAXBLKS optional optional optional optional PROCCNT optional optional optional optional UAMMAP optional10 optional10 optional10 optional10 CODE optional optional optional optional FATAL optional optional optional optional FLAG optional optional optional optional MAPCODE optional optional optional optional SEVERITY optional optional optional optional STATE optional optional optional optional UASLCS optional optional optional n/a CTOS optional optional optional n/a NAME optional optional optional n/a STOC optional optional optional n/a UAUSER required11 required12 required12 required13 ACCESS n/a optional n/a n/a
Release 10R3: October 31, 2005 UniAccess Source Configuration Statement Reference 16-99
UniAccess System Component Statement Parameter UASL UARS UAHS UACL
UAUSER AREASEARCH n/a n/a optional n/a (continued) COMSRV n/a n/a n/a required DEBUG n/a n/a optional n/a DISTTRAN optional optional optional14 n/a DOUNICODE n/a optional n/a n/a INTTOCHAR n/a optional n/a n/a LONGCHAR n/a optional n/a n/a MAXBLOBSIZE n/a optional n/a n/a RECOVERY n/a optional n/a n/a ROWLIMIT n/a optional n/a n/a ROWLIMITH n/a n/a optional n/a SCHEMA n/a optional n/a n/a SCHEMAH n/a n/a optional n/a SPACETRIM n/a optional optional n/a SPACETRIMH n/a n/a optional n/a STRIPCTRL n/a optional n/a n/a STRIPCTRLH n/a n/a optional n/a TRANSACTIVE n/a optional n/a n/a TRANSACTIVEH n/a n/a optional n/a TRANSOPTION n/a optional n/a n/a TRANSOPTIONH n/a n/a optional n/a USERID required required required required USERTRAN n/a optional n/a n/a VERSION n/a optional n/a n/a WORKSIZE n/a optional n/a n/a
Release 10R3: October 31, 2005 16-100 UniAccess for OS 2200 System Administration Guide
1 The CHARSET statement included with the Site Information File template is required for UACL. Optionally, additional CHARSET statements may be defined by the customer. (continued)
2 The COMSRV UACSTYPE parameter should be set to UATC if a UACS will be servicing only UACL programs. Setting COMSRV UACSTYPE to UATC will make the COMSRV APPNUM parameter not be required by the UACF processor. 3 The LOCALE statement included with the Site Information File template is required for UACL. Optionally, additional LOCALE statements may be defined by the customer. 4 If TIP Session control is active, the SESSCTRL parameter is required and must be set to YES. 5 The RPCMAP statements included in the UA Information File are required for UASL, UARS, and UAHS. Optionally, additional RPCMAP statements may be defined by the customer in the Site Information File. 6 At least one SERVER statement is required to access a remote server from a UACL program. 7 The UAMESG statements included in the UA Information File are required. Optionally, additional UAMESG statements may be defined by the customer in the Site Information File. 8 This field is only optional if the SERVER HOSTNAME parameter is present. If the HOSTNAME parameter is not present, then the ADDR parameter is required. 9 The UAMMAP statements included in the UA Information File are required. Optionally, additional UAMMAP statements may be defined by the customer. 10 The UAUSER statement is not required if COMSRV USEUAUSER is set to NO. 11 A UAUSER statement is not required for each userid if a default UAUSER record is configured and if COMSRV USEUAUSER is set to NO. 12 A UAUSER statement is not required for each userid if a default UAUSER record is configured. 13 If UAHS is used for the UADriver Language Transaction Type and if UASL transactions are also present, this parameter is optional. This parameter is not applicable when UAHS is being used without UASL.
Release 10R3: October 31, 2005 17 Processor Execution 17 UniAccess System Processor Execution Statements
This chapter defines the syntax of command lines to execute the UniAccess System processors, UACF and UACS.
Topics Page
Overview of Execution Statements 17-1 Executing UACF 17-2 Executing UACS 17-6 Starting UACS with Default Runstreams 17-7 Starting UACS with a Batch Runstream 17-7
Overview of Execution Statements The UniAccess System for OS 2200 is managed by two processors: UACF, the UniAccess Configuration utility, and UACS, the UniAccess Communication Server. The UACF processor generates the UniAccess Configuration File from the Source Configuration File. It also initializes UAMM and loads UADT within the UniAccess Fixed-gate. UACS manages client/server communication between UniAccess System software and remote software, and it validates users through UADT.
Chapters 3 through 5 explain the steps you should take before executing the UniAccess System processors. Chapter 6 explains UniAccess System management and the steps required for initial and subsequent system executions, including system reboots. Please consult that chapter before employing the execution commands detailed here. The current chapter explains the syntax of the execution command lines and the options available through the UniAccess System for executing these processors.
Release 10R3: October 31, 2005 17-2 UniAccess for OS 2200 System Administration Guide
Executing UACF UACF is the UniAccess System processor that converts the two files of source configuration statements to the UniAccess Configuration File, the fixed-binary-form file utilized by components of the UniAccess System (see Chapter 6). UACF has seven modes of operation, determined by the option/s the administrator selects. Depending on the options passed on the UACF execute statement, the following functions are performed:
• Read and validate (check the syntax of) the source configuration statements in the Site Information File and the UA Information File.
• Read and validate the source configuration statements in the Site Information File and the UA Information File and write them to the UniAccess Configuration File.
• Read the UniAccess Configuration File and write configuration statements to the Site Information File or the terminal.
• Read the UniAccess Configuration File and write configuration statements to the UA Information File or the terminal.
• Initialize UAFG with a subset of the parameters contained in the UniAccess Configuration File.
• Re-load UADT with a subset of the UniAccess Configuration File contents.
• Dump the contents of UADT to the Site Information File or the terminal.
• Produce a report highlighting the UniAccess Dynamic Memory Bank Allocations associated with a configuration (see page 8-22).
Release 10R3: October 31, 2005 UniAccess System Processor Execution Statements 17-3
UACF is executed as an OS 2200 processor and accepts command line parameters. You can execute UACF using the following format:
@qual*file.UACF,options spec1,spec2,spec3
where:
qual*file is the name of the file where the UACF utility is located. For the production mode install, the default file name is SYS$LIB$*UAUTIL; for the test mode install, the default file name is SYS$LIB$*UAUTILT.
options are one of the following (some options may be used in combination):
A process the Site Information File in the file or file.element named in spec1 and the UA Information File in the file or file.element named in spec3 to build the UniAccess Configuration File named in spec2. For this option, spec1 is required and spec2 is required if UACF is not executed from the production mode installation file.
B build the Site Information statements using the UniAccess Configuration File named in spec2. The source will be placed in the file or file.element named in spec1. If spec1 is not specified, the generated source statements will be sent to the system standard print file (PRINT$). This option will build statements originally specified in the Site Information File when the UniAccess Configuration File was built. For this option, spec2 is required if UACF is not executed from the production mode installation file.
C send all output to the system console instead of the system standard print file (PRINT$).
D dump the contents of UADT. The contents will be placed in the file or file.element named in spec1. If spec1 is not specified, the contents will be sent to the system standard print file (PRINT$).
H display UACF help and version information.
Release 10R3: October 31, 2005 17-4 UniAccess for OS 2200 System Administration Guide
I initialize the UAMM and UADT services of UAFG using information contained in the UniAccess Configuration File named in spec2. The ‘I’ option cannot be used to reinitialize the Fixed-gate subsystem once it has been initialized (see page 6-7). For this option, spec2 is required if UACF is not executed from the production mode installation file.
L re-load the UniAccess Fixed-gate with the information contained in the UniAccess Configuration File named in spec2. The ‘L’ option can be used while the UniAccess System is active. For this option, spec2 is required if UACF is not executed from the production mode installation file.
M in association with the A or S options, produce a report highlighting the UniAccess Dynamic Memory Bank Allocations associated with the configuration. The explanation and layout of the report are detailed in the section beginning on page 8-22.
O bypass automatic cataloging of a new cycle of the UniAccess Configuration File when the ‘A’ option is specified. UACF uses the previously cataloged file named in spec2 instead of cataloging a new cycle. The ‘O’ option allows system administrators to catalog the UniAccess Configuration File on any device (fixed or removable).
S syntax check the contents of the file or file.element named in spec1 and the file or file.element named in spec3. If specified, spec2 will be ignored. For this option, spec1 is required.
T build the UA Information statements using the UniAccess Configuration File named in spec2. The source will be placed in the file or file.element named in spec1. If spec1 is not specified, the generated source statements will be sent to the system standard print file (PRINT$). This option will build statements originally specified in the UA Information File when the UniAccess Configuration File was built. For this option, spec2 is required if UACF is not executed from the production mode installation file.
The ‘A’ and ‘L’ options can both be specified on a single UACF call. This combination will allow the file or file.element named in spec1 and the file or file.element named in spec3 to be processed and the resultant output loaded into the UniAccess Fixed-gate in a single step. When both ‘A’ and ‘L’ are
Release 10R3: October 31, 2005 UniAccess System Processor Execution Statements 17-5
specified and a syntax error is detected in the file or file.element named in spec1, the UniAccess Fixed-gate will not be loaded.
spec1 is the Site Information File, that is, the input system data format (SDF) source configuration statement file or file.element that contains configuration statements if the ‘A’ or ‘S’ option is specified. This file must contain ASCII images. Fieldata images will cause UACF to generate an error. If the ‘B,’ ‘D,’ or ‘T’ option has been specified, it is the file or file.element into which output will be placed. When specified, the file must exist (be cataloged) before calling UACF.
spec2 is the UniAccess Configuration File. If this spec2 field is not specified and UACF is executed from the production mode installation file, the default name of UNIACCESS*CONFIG. is used. Otherwise, this field is required for all options that reference the UniAccess Configuration File. A new cycle of this file will be created and cataloged when the ‘A’ option is specified without the ‘O’ option. The file must exist (be cataloged) before calling UACF with the ‘B’ and ‘L’ options.
spec3 is the UA Information File, that is, the input system data format (SDF) source configuration statement file or file.element that contains configuration statements provided by AIS if the ‘A’ or ‘S’ option is specified. If this spec3 field is not specified, the name of qual*file.UNIACCESS/INC is used where qual*file is the qualifier and file name from which the UACF processor is executed. This file must contain ASCII images. Fieldata images will cause UACF to generate an error.
Note The default configuration file will be cataloged on fixed mass-storage unless the ‘O’ option is used.
Release 10R3: October 31, 2005 17-6 UniAccess for OS 2200 System Administration Guide
Executing UACS The UniAccess Communication Server is the OS 2200 processor that manages network input and output for all UniAccess System services. (Chapter 19 explains UACS management and describes the UACS console commands. Chapter 18 provides procedures for reconfigurations that involve UACS.)
UACS is executed as an OS 2200 processor and accepts command line parameters. You can execute UACS using the following format:
@qual*file.UACS,[h] [configfile],process
where:
qual*file is the qualifier and file where the UACS absolute is located. For the production mode install, the default file name is SYS$LIB$*UAUTIL; for the test mode install, the default file name is SYS$LIB$*UAUTILT.
h (optional) displays help information about the UACS call format, but does not start UACS.
configfile (optional) is the UniAccess Configuration File name. The default value is UNIACCESS*CONFIG.
process is the name of the COMSRV record in the UniAccess Configuration File that defines the operational characteristics for this UACS.
Note UACS captures T3 of the run condition word at the beginning of execution and, upon normal termination, it is restored.
Release 10R3: October 31, 2005 UniAccess System Processor Execution Statements 17-7
Starting UACS with Default Runstreams
You can choose to start UACS by using start runstreams. To do so, you must create a UniAccess Configuration File using the UACF processor. The start runstreams installed by AIS require the UniAccess Configuration File name to be:
UNIACCESS*CONFIG.
The process name is UACS, which must correspond to the COMSRV PROCNAM parameter in the Source Configuration File. The start runstream name is UACS in the file SYS$LIB$*RUN.
Starting UACS with a Batch Runstream
The following is an example of how a batch runstream looks for UACS. The run-id, the qualifier used for the DIAG$FILE file and the process name on the UACS execution statement should be unique for each copy of UACS started.
@RUN,/LK UACS,acct-id,user-id,project-id,9999,9999/9999 @ . @ . Set up DIAG$ @ . @FREE DIAG$. @CAT,P UACS*DIAG$FILE(+1).,F/200//9000 @ASG,AX UACS*DIAG$FILE. @USE DIAG$.,UACS*DIAG$FILE. @ . @ . Execute UACS @ . @SYS$LIB$*UAUTIL.UACS UNIACCESS*CONFIG.,UACS @FIN
Release 10R3: October 31, 2005 17-8 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 18 Reconfig Procedures 18 UniAccess Reconfiguration Procedures
This chapter provides the UniAccess administrator with information on reconfiguring UniAccess. It begins with procedures for modifying the UniAccess Configuration File and then presents information required for several typical reconfigurations, specifically, adding new users and adding another UACS. For detailed information on the UniAccess Configuration File design and management, please refer to Chapter 6, Managing the UniAccess System.
Topics Page
Modifying the Configuration File 18-1 Reconfigurations Relevant to UADT 18-3 Reconfigurations Relevant to UACS 18-3 Reconfigurations Relevant to UAMM 18-4 Requirements for Specific Configurations 18-5 Upgrading Product Key License 18-5 Adding New Users 18-6 Adding Another UACS within an Application Group 18-7 Adding a UACS within Another Application Group 18-10
Modifying the Configuration File The procedures for reconfiguring UniAccess depend on the particular configuration statements involved and on the UniAccess System component affected (UADT, UACS, UAMM). Reconfigurations always involve rebuilding the configuration file and may require loading selected information into the fixed-gate, restarting UACS, or reinitializing the UniAccess Fixed-gate. Table 18-1 indicates which UniAccess Configuration
Release 10R3: October 31, 2005 18-2 UniAccess for OS 2200 System Administration Guide
Statements are effected by reconfigurations to the UADT, UACS, and UAMM components. The sections that immediately follow describe in detail the reconfiguration requirements for these components.
Table 18-1: Configuration Statement Information Relevant to UADT, UACS, and UAMM
Config Statements Config Statements Config Statements Relevant to UADT Relevant to UACS Relevant to UAMM
(Statements (Statements (Statements that may be changed requiring a UACS requiring a Fixed-gate Dynamically) Restart) Reinitialization)
APPINF1 APPINF1 OSPARM2 CHARSET COMSRV UAMM LOCALE OSPARM2 HIERSRV RELSRV RPCMAP SERVER UAMESG UAMMAP UASLCS UAUSER
1 If changes to already existing APPINF parameters are made, UACS must be restarted; new APPINF statements may be added dynamically. 2 If the UACLPRODKEY, UAHSPRODKEY, UARSPRODKEY, and/or UASLPRODKEY parameter of the OSPARM statement is changed, the Fixed-gate must be re-initialized. If the other parameters are changed, UACS must be restarted.
Release 10R3: October 31, 2005 UniAccess Reconfiguration Procedures 18-3
Reconfigurations Relevant to UADT
If you wish to change any of the configuration statements that affect UADT (the UniAccess data management service within the UniAccess Fixed-gate), you may change them dynamically while UACS is running. You should follow the procedure detailed in this section. For a list of statements that affect UADT, please refer to the first column of Table 18-1.
1. Reconfigure the Source Configuration File with the new information.
2. Execute UACF to build the UniAccess Configuration File and to load UADT. The ‘A’ and the ‘L’ options on the execution statement may be combined in a single command line in this case. (Refer to page 17-2 for more information on UACF execution syntax.)
The following example demonstrates using the UACF utility to process the Site Information File in qual*file.configfile and the default UA Information File in SYS$LIB$*UAUTIL.UNIACCESS/INC to build and re-load the UniAccess Fixed-gate with the information contained in the default UniAccess Configuration File UNIACCESS*CONFIG:
@SYS$LIB$*UAUTIL.UACF,AL qual*file.configfile
Reconfigurations Relevant to UACS
If you wish to change any of the configuration statements that affect UACS (APPINF, COMSRV, and OSPARM) you must terminate and restart UACS. This procedure requires the following steps:
1. Terminate the affected UACS using the TERM UACS,
2. Reconfigure the Source Configuration File with the new information.
3. Execute UACF to build the UniAccess Configuration File. This involves using the ‘A’ option on the execution statement. (Refer to page 17-2 for more information on UACF execution syntax.)
Release 10R3: October 31, 2005 18-4 UniAccess for OS 2200 System Administration Guide
The following example demonstrates using the UACF utility to process the Site Information File in qual*file.configfile and the default UA Information File in SYS$LIB$*UAUTIL.UNIACCESS/INC to build the default UniAccess Configuration File UNIACCESS*CONFIG:
@SYS$LIB$*UAUTIL.UACF,A qual*file.configfile
4. Restart the affected UACS.
Reconfigurations Relevant to UAMM
If you wish to make any changes to the UAMM configuration statement you must terminate and reinitialize the Fixed-gate. This procedure requires the following steps:
1. Terminate all the affected UACSs using the TERM UACS,
2. Deactivate the UniAccess Fixed-gate. This is accomplished by signing on with the proper security clearance and executing the SOLAR DEACT utility. Add the following runstream to deactivate the production Fixed-gate:
@ADD SYS$LIB$*UAUTIL.DEACTUAFG
3. Reconfigure the Source Configuration File with the new information.
4. Execute UACF to build the UniAccess Configuration File. This involves using the ‘A’ option on the execution statement. (Refer to page 17-2 for more information on UACF execution syntax.)
The following example demonstrates using the UACF utility to process the Site Information File in qual*file.configfile and the default UA Information File in SYS$LIB$*UAUTIL.UNIACCESS/INC to build the default UniAccess Configuration File UNIACCESS*CONFIG:
@SYS$LIB$*UAUTIL.UACF,A qual*file.configfile
5. Execute UACF to reinitialize the Fixed-gate. This involves using the ‘I’ option on the execution statement.
Release 10R3: October 31, 2005 UniAccess Reconfiguration Procedures 18-5
The following example demonstrates using the UACF utility to reinitialize the Fixed-gate using the default UniAccess Configuration File UNIACCESS*CONFIG:
@SYS$LIB$*UAUTIL.UACF,I
6. Restart all the affected UACSs.
Requirements for Specific Configurations This section presents the requirements for several common reconfigurations, namely upgrading the product key license, and adding new users and new UACSs to the UniAccess Configuration File.
Upgrading Product Key License
Customers who upgrade their product key license receive a new product key from AIS. Adding a new product key involves the following steps:
1. Terminate all the affected UACSs using the TERM UACS,
2. Deactivate the UniAccess Fixed-gate. This is accomplished by signing on with the proper security clearance and executing the SOLAR DEACT utility. The following example demonstrates deactivating the production Fixed-gate:
@ADD SYS$LIB$*UAUTIL.DEACTUAFG
3. Reconfigure the Source Configuration File, updating the OSPARM UACLPRODKEY, OSPARM UAHSPRODKEY, OSPARM UARSPRODKEY, and/or OSPARM UASLPRODKEY configuration parameter(s) with the new product key(s).
4. Execute UACF to build the UniAccess Configuration File. This involves using the ‘A’ option on the execution statement. (Refer to page 17-2 for more information on UACF execution syntax.)
Release 10R3: October 31, 2005 18-6 UniAccess for OS 2200 System Administration Guide
The following example demonstrates using the UACF utility to process the Site Information File in qual*file.configfile and the default UA Information File in SYS$LIB$*UAUTIL.UNIACCESS/INC to build the default UniAccess Configuration File UNIACCESS*CONFIG:
@SYS$LIB$*UAUTIL.UACF,A qual*file.configfile
5. Execute UACF to reinitialize the Fixed-gate. This involves using the ‘I’ option on the execution statement.
The following example demonstrates using the UACF utility to reinitialize the Fixed-gate using the default UniAccess Configuration File UNIACCESS*CONFIG:
@SYS$LIB$*UAUTIL.UACF,I
6. Restart all the affected UACSs.
Adding New Users
Probably the most typical type of reconfiguration is adding a new user or making modifications to an existing user. A UAUSER configuration statement must be defined for each user of the UniAccess System except under the following circumstances:
• For UASL, if the COMSRV USEUAUSER parameter is set to NO
• For UARS and UAHS, if the COMSRV USEUAUSER parameter is set to NO and if one default UAUSER record is configured for all users
• For UACL, if one default UAUSER record is configured for all users.
For UARS, UAHS, and UACL users, a default UAUSER record is set up with a USERID of “@@@@@@@@@@@”. Refer to page 16-79 for more information on using the default UAUSER statement.
If TIP session control is on, UniAccess users must be assigned valid TIP userids. The userid can be created using SIMAN.
Release 10R3: October 31, 2005 UniAccess Reconfiguration Procedures 18-7
Rather than define each parameter of the UAUSER record individually, many parameters may be predefined to a default setting using the RELSRV statement (for the UniAccess Relational Service for RDMS 2200) and/or the HIERSRV statement (for the UniAccess Hierarchical Service for DMS 2200).
For instructions on updating the UniAccess Configuration File after these changes have been made to the Site Information File, refer to Reconfigurations Relevant to UADT earlier in this chapter.
Adding Another UACS within an Application Group
Multiple UACSs (UniAccess Communication Servers) may be configured to run in the same application group. Adding a new UACS always requires the following:
1. Configure another TSAM Process, Password, and I.P. Address.
One unique PROCESS statement must be configured for each UACS. The CMS 1100 or CPComm PROCESS statement process-id variable must match the UniAccess COMSRV PROCNAME parameter. For CMS 1100, the PROCESS network definition statement must be of type TSAM.
A PASSWORD variable must be configured for each CMS 1100 or CPComm PROCESS statement. The PASSWORD variable must match the UniAccess COMSRV PROCPSWD parameter.
Each CMS 1100 PROCESS statement must relate to a CMS 1100 INTERNET- ADR. Multiple CMS 1100 PROCESS statements can use the same CMS 1100 INTERNET-ADR. The CPComm configuration must contain at least one OP statement.
2. Add another UACS RUN$ element.
Each UACS should be assigned its own UACS symbolic element in the file SYS$LIB$*RUN$. Additionally, the run-id, the qualifier used for the DIAG$FILE, and the process name of the UACS execution statement should be unique for each copy of UACS started.
• Install another UARS transaction (if required).
Release 10R3: October 31, 2005 18-8 UniAccess for OS 2200 System Administration Guide
3. At times it may be necessary to install another UARS transaction within the same application group, for example, when UARS translation routines are in use. This can be accomplished by adding the UARS/INSTALL runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations). This runstream, once added, will prompt you for the application number, application name, SUPUR file number, transaction name, and transaction number. Refer to page 4-11 for a description of this runstream.
Note It is not necessary to generate another UNIACCESS1S1 within the same application group. Multiple UniAccess UACSs running in an application group that schedule UARS transactions will use the same UNIACCESS1S1 schema.
Note Unless the runstreams created by UARS/INSTALL are saved to another location or renamed, adding them will overlay the previously created UARS/BUILD, UNIACCESS/CREATE, UNIACCESS/DELETE, UNIACCESS6R1/DELETE and UNIACCESS6R1/MIGRATE runstreams in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations).
4. Install another UAHS transaction (if required).
At times it may be necessary to install another UAHS transaction within the same application group. This can be accomplished by adding the UAHS/INSTALL runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations). This runstream, once added, will prompt you for the application number, application name, SUPUR file number, transaction name, and transaction number. Refer to page 4-9 for a description of this runstream.
Note Unless the runstream created by UARS/INSTALL is saved to another location or renamed, adding it will overlay the previously created UAHS/BUILD runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations).
Release 10R3: October 31, 2005 UniAccess Reconfiguration Procedures 18-9
5. Add another COMSRV statement in the UniAccess Configuration File.
Mandatory parameters within the COMSRV statement when configuring a new UACS include APPNUM, DFLTTRAN, LISTENPRT (if auto selection is bypassed), a unique LNGFNAME (if UARSTRAN is used), PIDCNT, PIDSTART, PROCNAME, PROCPSWD, TRCFNAME, UAHSTRAN transaction name (if required), and UARSTRAN transaction name (if required). (Refer to Chapter 16, UniAccess Source Configuration Statement Reference, for a complete list of UniAccess Configuration File statements and parameters.)
The following is an example of configuring two UACSs within a single application group:
APPINF APPNAME,UDSSRC ; APPNUM,3 ; MCBBDI,400500
COMSRV PROCNAM,UACS ; PROCPSWD,PASSWORD ; APPNUM,3 ; LANGTRAN,UARS ; LISTENPRT,2050 ; LNGFNAME,UNIACCESS*UACS$LANG ; PIDCNT,100 ; PIDSTART,1000 ; TRCFNAME,UNIACCESS*UACS$TRACE
COMSRV PROCNAM, UACS2 ; PROCPSWD,PASSWORD ; APPNUM,3 ; LANGTRAN,UARS2 ; LISTENPRT,2051 ; LNGFNAME,UNIACCESS*UACS2$LANG ; PIDCNT,100 ; PIDSTART,1200 ; TRCFNAME,UNIACCESS*UACS2$TRACE
For instructions on updating the UniAccess Configuration File after these changes have been made to the Site Information File, refer to Reconfigurations Relevant to UACS earlier in this chapter.
Release 10R3: October 31, 2005 18-10 UniAccess for OS 2200 System Administration Guide
Adding a UACS within Another Application Group
Adding a UACS in another application group requires the same steps as discussed in the previous section titled Adding Another UACS within an Application Group with these additional considerations:
1. Verify the UniAccess System software requirement is met in the new application group. (Refer to the Pre-Installation Checklists A and B in Chapter 3 of this manual.)
2. Obtain Relational Service installation information, if used.
UniAccess Relational Service must be defined and installed in each application group in which it will operate. This can be accomplished by adding the UARS/ INSTALL runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test most installations). This runstream, once added, will prompt you for the application number, application name, SUPUR file number, transaction name, and transaction number. (Refer to page 4-11 of this manual for a description of this runstream.) Note Unless the runstreams created by UARS/INSTALL are saved to another location or renamed, adding them will overlay the previously created UARS/BUILD, UNIACCESS/CREATE, UNIACCESS/DELETE, UNIACCESS6R1/DELETE and UNIACCESS6R1/MIGRATE runstreams in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations).
3. Obtain Hierarchical Service installation information, if used.
UniAccess Hierarchical Service must be defined and installed in each application group in which it will operate. This can be accomplished by adding the UAHS/ INSTALL runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test most installations). This runstream, once added, will prompt you for the application number, application name, SUPUR file number, transaction name, and transaction number. Refer to page 4-11 for a description of this runstream.
Release 10R3: October 31, 2005 UniAccess Reconfiguration Procedures 18-11
Note Unless the runstreams created by UARS/INSTALL are saved to another location or renamed, adding them will overlay the previously created UARS/BUILD, UNIACCESS/CREATE, UNIACCESS/DELETE, UNIACCESS6R1/DELETE and UNIACCESS6R1/MIGRATE runstreams in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations).
4. Obtain UAINFO installation information, if used.
UAINFO must be installed in each application group in which it will operate. This can be accomplished by adding the UAINFO/INSTALL runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test most installations). This runstream, once added, will prompt you for the application number, SUPUR file number, transaction name, and transaction number. (Refer to page 4-14 for a description of this runstream.)
Note Unless the runstreams created by UAINFO/BUILD are saved to another location or renamed, adding them will overlay the previously created UAINFO/BUILD runstream in SYS$LIB$*UAUTIL (or SYS$LIB$*UAUTILT for test mode installations).
5. Add another APPINF statement in the UniAccess Configuration File.
The APPNAME, APPNUM, and MCBBDI are all required parameters. The following is an example of configuring UACSs in multiple application groups:
APPINF APPNAME,UDSSRC ; APPNUM,3 ; MCBBDI,400500 APPINF APPNAME,APPFIV; APPNUM,5 ; MCBBDI,40060
Release 10R3: October 31, 2005 18-12 UniAccess for OS 2200 System Administration Guide
COMSRV PROCNAM,UACS ; PROCPSWD,PASSWORD ; APPNUM,3 ; LANGTRAN,UARS ; LISTENPRT,2050 ; LNGFNAME, UNIACCESS*UACS$LANG ; PIDCNT,100 ; PIDSTART,1000 ; TRCFNAME,UNIACCESS*UACS$TRACE
COMSRV PROCNAM,UACS2 ; PROCPSWD,PASSWORD ; APPNUM,3 ; LANGTRAN,UARS2 ; LISTENPRT,2051 ; LNGFNAME,UNIACCESS*UACS2$LANG ; PIDCNT,100 ; PIDSTART,1200 ; TRCFNAME,UNIACCESS*UACS2$TRACE
COMSRV PROCNAM,UACS5 ; PROCPSWD,PASSWORD ; APPNUM,5 ; APPNUM,5 ; LANGTRAN,UARS5 ; LISTENPRT,2052 ; LNGFNAME,UNIACCESS*UACS5$LANG ; PIDCNT,100 ; PIDSTART,1400 ; TRCFNAME,UNIACCESS*UACS5$TRACE
For instructions on updating the UniAccess Configuration File after these changes have been made to the Site Information File, refer to Reconfigurations Relevant to UACS earlier in this chapter.
Release 10R3: October 31, 2005 19 UACS Operations 19 UACS Operations Reference
This chapter explains UniAccess Communication Server (UACS) management and describes the UACS console commands.
Topics Page
UniAccess Communication Server Management 19-2 Executing UACS 19-2 Acknowledging Communications Server 19-2 Connection Failure Acknowledging Communications Server Loss 19-2 Acknowledging MCB Initialization Loss 19-3 Administering UACS 19-3 Terminating UACS 19-4 Console Commands for UACS 19-4 HELP 19-6 LANGUAGE 19-7 STATUS 19-10 SYSLOG 19-23 TERM 19-24 TRACE 19-27 UAMM 19-29 UACS Security Logging 19-33 Security Event Log Entry Format 19-33
Release 10R3: October 31, 2005 19-2 UniAccess for OS 2200 System Administration Guide
UniAccess Communication Server Management UniAccess Communication Server (UACS) provides the connection between clients or servers on the OS 2200 system and remote clients or servers. It accepts client requests, routes them to a server, and returns them to the client. Multiple UACSs may be configured to run on the UniAccess System simultaneously (see Chapter 16 for this and other information related to reconfiguring UACS). This chapter explains how to manage UACS and describes the console commands used to control it while it is executing (running).
Executing UACS
UACS is executed as an OS 2200 processor using the syntax explained on page 17-6.
Acknowledging Communications Server Connection Failure
When UACS is started, it attempts to attach to a communications server (CMS 1100 or CPComm). If CMS or CPComm is unavailable when UACS attempts to attach to it, the following operator console message is displayed:
# **UACS** CMS UNAVAILABLE... RETRY CONNECTION
where # is the system console message number and CMS refers to both CMS 1100 and CPComm.
Answering ‘Y’ will cause UACS to attempt to attach to a communications server again. The same console message will continue to be displayed as long as a communications server is not available. Answering ‘N’ will cause UACS to terminate.
Acknowledging Communications Server Loss
If the communications server (CMS 1100 or CPComm) aborts or is terminated while UACS is active, UACS automatically detects the condition. UACS will terminate all active connections and attempt to reinitialize. The following operator console message is displayed:
# **UACS** CMS UNAVAILABLE... RETRY CONNECTION
where # is the system console message number and CMS refers to both CMS 1100 and CPComm.
Release 10R3: October 31, 2005 UACS Operations Reference 19-3
Answering ‘Y’ will cause UACS to attempt to attach to the communications server again. The same console message will continue to be displayed as long as the communications server is not available. Answering ‘N’ will cause UACS to terminate.
Acknowledging MCB Initialization Loss
If MCB terminates in an application group in which a UACS is operating, UACS is no longer initialized with that MCB. The following operator console message is displayed:
# **UACS** CONNECTION TO MCB appnum LOST... PRESS ANY KEY TO ACK
where:
# is the system console message number, and
appnum is the application group number in which UACS is operating.
No other console input will be accepted by UACS until this message is acknowledged. After the message is acknowledged, the following operator console message will display:
**UACS** SHUTDOWN UACS AND RESTART WHEN MCB IS AVAILABLE
When the MCB has been successfully restarted, UACS must be terminated and restarted to allow it to reinitialize with the MCB and schedule UASL transactions.
Note When a UACS is configured to only service UACL requests (COMSRV UACSTYPE of UATC), UACS does not initialize with MCB and will not display these operator console messages.
Administering UACS
While UACS is executing, you can use the CMS 1100 or CPComm STATUS and TRACE keyins to obtain generic information about UACS. Additionally, UACS provides its own set of console (CONS) keyins for more precise control. Access to a particular CONS command is based upon the console mode of the user (see page 9-10 for console mode requirements.)
Release 10R3: October 31, 2005 19-4 UniAccess for OS 2200 System Administration Guide
All UACS console commands are in the following format:
where:
is any optional parameter(s) related to a specific command.
The command (COMMAND) and parameter (PARM) options are listed in Table 19-1. The section that follows this table explains each statement in more detail.
Remote Consoles. Console commands may be accepted from remote consoles if the user has the console privileges required for UniAccess CONS commands. The syntax for the command statement is:
@@CONS UACS COMMAND,PARM
Terminating UACS
UACS is terminated by the console command TERM UACS,
Note For a list of console messages returned by UACS, see page D-2.
Console Commands for UACS The console commands to manage UACS while it is executing are listed in Table 19-1 that follows and described in detail in this section. The short command for the console command immediately follows the long format, consisting of the command and the parameter.
Release 10R3: October 31, 2005 UACS Operations Reference 19-5
Table 19-1: UACS Console Commands
Command Short Description Page Command Parameter Command HELP ? UACS console help 19-6 LANGUAGE Write language request information to a file 19-7 OFF LOFF Turn off language tracing 19-8 ON LON Turn on language tracing 19-8 CLOSE LC Close the language trace file 19-9
STATUS Display current status information 19-10 SUMMARY SS Status summary 19-10 ALL SA Status for all PIDs 19-15 EXTENDED SE Status for extended transactions 19-16
PID,
TERM Terminate a UACS or client connection 19-24 UACS,
PID,
LOW TL Change trace level 19-28 MEDIUM TM Change trace level 19-28 HIGH TH Change trace level 19-28 CLOSE TC Close the trace file 19-28
UAMM Display UAMM status information 19-29 SUMMARY US UAMM statistics summary 19-29
Release 10R3: October 31, 2005 19-6 HELP UniAccess for OS 2200 System Administration Guide
HELP
The HELP command displays a help screen of all the available UACS console commands. Before UACS services this command, it checks the console mode of the requester to ensure that he or she has full keyin privileges.
Command Format
Command Format Short Command Description
1.
1. HELP (?) Command
This command displays the format for a UACS console command as well as a list of all available UACS console commands. The following output illustrates an example console response.
Format:
Release 10R3: October 31, 2005 UACS Operations Reference LANGUAGE 19-7
LANGUAGE
The LANGUAGE commands write language request information to a language trace file. They allow administrators to turn language tracing on or off and to close and cycle a language trace file. A language trace file can help application developers debug their programs during the development phase. This file must be closed before it can be viewed. It may be viewed with any text editor that supports SDF images, including most OS 2200 editors.
The format of the language trace file is as follows:
[userid] [pid] [ip-address] [mm/dd/yy hh:mm:ss] [language string]
where:
userid is the userid specified by the client program
pid is the PID assigned by UACS
ip-address is the IP address of the client machine
mm/dd/yy hh:mm:ss is the timestamp indicating when the request was received
language string is the incoming language request of up to 504 bytes
If a language request is greater than 504 bytes in length, multiple language trace entries will be generated for each 504 byte segment.
The following is an example of a language trace entry:
[mikesmith] [401] [192.168.1.3] [03/08/99 17:19:35] [select min_salary, max_salary from uadbsamp.job_descriptiontb ]
Release 10R3: October 31, 2005 19-8 LANGUAGE UniAccess for OS 2200 System Administration Guide
Before UACS services a LANGUAGE command, it checks the console mode of the requestor to ensure that he or she has full keyin privileges.
The LANGUAGE commands affect the language trace file that has been named and defined by the system administrator with the COMSRV LNGFNAME and COMSRV LNGASGATTR configuration variables (see page 16-24). The initial state of language tracing is configured using the COMSRV LNGTRACE configuration variable (see page 16-24).
Note The language trace file is always assigned to UACS when it is active, regardless of the setting of the COMSRV LNGTRACE parameter.
Command Formats
Command Format Short Command Description
1.
1. LANGUAGE OFF (LOFF) Command
The LANGUAGE OFF command turns off language tracing while leaving the language trace file intact. The console response to this command displays the following:
LANGUAGE TRACING
2. LANGUAGE ON (LON) Command
The LANGUAGE ON command indicates turns on language tracing. The console response to this command displays the following:
LANGUAGE TRACING
Release 10R3: October 31, 2005 UACS Operations Reference LANGUAGE 19-9
3. LANGUAGE CLOSE (LC) Command
The CLOSE command requests that the language trace file be closed and a new cycle created. This action is required to view the current language trace file. The console response to a LANGUAGE CLOSE command displays the following:
LANGUAGE FILE: UNIACCESS*UACS$LANG(cycle). CLOSED AND CYCLED
where
cycle is the language trace file cycle number.
Release 10R3: October 31, 2005 19-10 STATUS UniAccess for OS 2200 System Administration Guide
STATUS
The STATUS command displays current summary statistics and detailed connection information.
Before UACS services the STATUS command, it checks the console mode of the requester to ensure that he or she has full key-in privileges.
Command Formats
Command Format Short Command Description
1.
1. STATUS SUMMARY (SS) Command
This command summarizes status statistics for all connections. These statistics are grouped into three categories: General Information, UATS Information, and UATC Information. The statistics in the UATS Information section will only be displayed on the console if UACS is configured to support UATS (COMSRV UACSTYPE of UATS or UATC/UATS—see page 16-30). The statistics under the UATC Information section will only be displayed if UACS is configured to support UATC (COMSRV UACSTYPE of UATC or UATC/UATS).
Release 10R3: October 31, 2005 UACS Operations Reference STATUS 19-11
Note Note that UniAccess ODBC Server for RDMS 2200 and UniAccess ODBC Server for DMS 2200 are included in the term UATS. Likewise, UARS and UAHS are included in the term UniAccess Server-Library (UASL).
The following statistics are output from this command and are illustrated in the example console response that follows.
General Information
UACS VERSION The UACS version.
UAFG VERSION The UAFG version.
TRACE LEVEL The current UACS trace level or UNASSIGNED. UNASSIGNED indicates that the new trace file could not be assigned the last time the trace file was closed using the TRACE CLOSE console command (see page 19-28). When the trace level is UNASSIGNED tracing is temporarily suspended. Once the problem with assigning the new trace file has been resolved, tracing can be resumed at the previous level by the TRACE CLOSE console command.
TASKS TSAM/TIPQ The number of TSAM tasks booted. / The number of TIPQ tasks booted.
CMS PROCESS NAME The CMS 1100 or CPComm PROCESS name by which UACS is identified.
PID RANGE The range of PIDs allocated to this UACS.
ABORTED CONNECTS The total number of aborted connections since boot or last statistics reset.
Release 10R3: October 31, 2005 19-12 STATUS UniAccess for OS 2200 System Administration Guide
SYSTEM LOG Defines whether or not this UACS is writing to the system log file.
CONFIG FILE The name of the configuration file used to boot UACS.
TRACE FILE The name and cycle of the current UACS trace file, or the last trace file written if the TRACE LEVEL is UNASSIGNED.
BYTES RECV/SENT The total number of bytes received and the total number of bytes sent since a boot or the last statistics reset.
THRTLES RECV/SENT The total number of blocked sends since a boot or the last statistics reset. / The total number of network throttles issued by UACS since a boot or the last statistics reset.
RESUMES RECV/SENT The total number of resumes received since a boot or the last statistics reset. / The total number of network resumes issued by UACS since a boot or the last statistics reset.
UATS (UniAccess Transaction Server) Information
NETWORK PORT The port on which UACS accepts client connections.
INTERNET ADDR When the COMSRV MULTIIP parameter is set to NO, the Internet address on which UACS accepts client connections is displayed. When the COMSRV MULTIIP parameter is set to YES, the value CMS DEFINED is displayed.
MCB STATUS The initialization status of this UACS with MCB.
Release 10R3: October 31, 2005 UACS Operations Reference STATUS 19-13
Status Meaning
CONNECTED Indicates that this UACS is initialized with MCB. DISCONNECTED Indicates that this UACS is no longer initialized with MCB. UACS must be terminated and restarted to reinitialize with MCB. (See page 19-24 for information on terminating and page 17-6 for information on starting UACS.
APPL GROUP The application group in which this UACS is executing.
RPCS The total number of UniAccess Server-Library RPC requests received since a boot or the last statistics reset.
LANGUAGE CALLS The total number of UniAccess Server-Library language calls received since a boot or the last statistics reset.
OPENS RECEIVED The total number of open requests since a boot or the last statistics reset.
FAILED REQUESTS The total number of failed requests since boot or last reset.
CMS NUMBER The CMS number of UACS.
LANGUAGE TRACE The indication of whether language request tracing is ON, OFF, or UNASSIGNED. UNASSIGNED indicates that the new language trace file could not be assigned the last time the language trace file was closed using the LANGUAGE CLOSE console command (see page 19-9). When the language trace level is UNASSIGNED, language tracing is temporaily suspended. Once the problem with assigning the new language trace file has been resolved, language tracing can be resumed by the LANGUAGE CLOSE console command.
Release 10R3: October 31, 2005 19-14 STATUS UniAccess for OS 2200 System Administration Guide
LANGUAGE TRACE FILE The name and cycle of the current language trace file, or the last language trace file written if the LANGUAGE TRACE is UNASSIGNED.
CONNECTIONS The total number of active UniAccess Server-Library connections.
EXTND/DISTR/UADTC The total number of Server-Library connections that are extended sessions. / The total number of Server-Library transactions that are participating in distributed transactions. / The total number of UADTC connections. / Extended sessions are initiated with the UARS transaction by initiating a user-defined transaction. They may also be initiated for user-written Server-Library transactions by the TDGETREQ function.
UATC (UniAccess Transaction Client) Information
CONNECTIONS (UATC) The total number of active UniAccess Client-Library connections.
REQUESTS The total number of UniAccess Client-Library requests since a boot or the last statistics reset. OPENS ISSUED The total number of opens issued by UniAccess Client-Library since a boot or the last statistics reset.
======UACS SUMMARY INFORMATION ======GENERAL INFORMATION: UACS VERSION: 10R3 UAFG VERSION: 10R3 TRACE LEVEL: LOW TASKS TSAM/TIPQ: 3/3 CMS PROCESS NAME: UACS PID RANGE: 400-499 ABORTED CONNECTS: 0 SYSTEM LOG: OFF CONFIG FILE: UNIACCESS*CONFIG. TRACE FILE: UNIACCESS*UACS$TRACE(524). BYTES RECV/SENT: 824403/777386 THRTLES RECV/SENT: 0/0 RESUMES RECV/SENT: 0/0
Release 10R3: October 31, 2005 UACS Operations Reference STATUS 19-15
UATS INFORMATION: NETWORK PORT: 2050 INTERNET ADDR: 192.168.1.16 MCB STATUS: CONNECTED APPL GROUP: 1 RPCS: 1763 LANGUAGE CALLS: 725 OPENS RECEIVED: 686 FAILED REQUESTS: 0 CMS NUMBER: 61 LANGUAGE TRACE: OFF LANG TRACE FILE: UNIACCESS*UACS$LANG(421). CONNECTIONS: 3 EXTND/DISTR/UADTC: 1/1/0 UATC INFORMATION: CONNECTIONS: 0 REQUESTS: 0 OPENS ISSUED: 0
2. STATUS ALL (SA) Command
This command displays detailed information about all active connections. The following statistics are displayed when this command is issued and are illustrated in the example console response below.
USERID The userid of the connected client.
PID The PID allocated to this connection. For UASL connections, this is the PID used to schedule the transaction.
TYPE The type of connection. Possible TYPEs are listed below:
Type Meaning
UACL UniAccess Client-Library connection. This connection type generates client requests to a configured suever. UASL UniAccess Server-Library connection. This connection type services client requests. UADTC UADTC connection. This connection type services requests interfacing with the UniAccess Distributed Coordinator.
Release 10R3: October 31, 2005 19-16 STATUS UniAccess for OS 2200 System Administration Guide
TRANCD The last transaction code executed by this connection. For UACL connections, this value will always be N/A. The TRANCD column consists of the transaction name with a possible appendage of (D), (X), or (DX). “D” signifies a transaction participating in a distributed transaction, “X” signifies an extended session transaction, and “DX” indicates an extended transaction participating in a distributed transaction.
IP ADDR The TCP/IP address of the requesting client. For TYPE of UACL, this field is always N/A since the UACL client resides on the OS 2200 system.
USERID PID TYPE TRANCD IP ADDR ======UADTC 401 UDTC N/A 192.168.1.114 cmax01 405 UASL UARS 192.168.1.114 cmax01 412 UASL T7F113 192.168.1.114 cmax01 413 UASL T7U113 192.168.1.114 cmax01 416 UASL UARS 192.168.1.114 cmax01 421 UASL T7F113 192.168.1.114 cmax01 423 UASL T7U113 192.168.1.114 cmax01 425 UASL T7R113 192.168.1.114 cmax01 431 UASL T7F113 192.168.1.114 cmax01 434 UASL T7U113 192.168.1.114 cmax01 437 UASL UARS 192.168.1.114 cmax01 442 UASL T7U113 192.168.1.114 cmax01 444 UASL UARS 192.168.1.114 cmax01 445 UASL T7R113 192.168.1.114 cmax01 446 UASL T7R113 192.168.1.114 mike148 452 UASL UARS 192.168.1.87 cmax01 458 UASL UARS 192.168.1.114 cmax01 467 UASL UARS (DX) 192.168.1.114
3. STATUS EXTENDED (SE) Command
This command displays information pertaining to transactions in extended session and those participating in distributed transactions. Extended sessions are initiated with the UARS transaction by initiating a user-defined transaction. They may also be initiated for user-written Server-Library transactions. Distributed transactions are discussed on page 15-1.
Release 10R3: October 31, 2005 UACS Operations Reference STATUS 19-17
The following statistics are output from this command and are illustrated in the example console response below.
PID The PID allocated to this connection. For UASL connections, this is the PID used to schedule the transaction.
TRANCD The last transaction code executed by this connection. For UACL connections, this value will always be N/A. The TRANCD column consists of the transaction name with a possible appendage of (D), (X), or (DX). “D” signifies a transaction participating in a distributed transaction, “X” signifies an extended session transaction, and “DX” indicates an extended participating in a distributed transaction.
TRANSACTION ID The unique identifier for a transaction participating in a distributed transaction. The transaction ID consists of a transaction timestamp (yyyy- mm-dd hh:mm:ss), transaction sequence number (nnnnnnn), and transaction step number (nnnn) in the format: yyyy-mm-dd hh:mm:ss nnnnnnn-nnnn. The transaction sequence number and the transaction step number are octal values. The unique distributed transaction ID is the step ID used by the OS 2200 operating system. For a transaction that is not participating in a distributed transaction, this statistic displays N/A.
PREPARED Indicates whether or not a global (distributed) transaction has reached the prepared state.
PID TRANCD TRANSACTION ID PREP ======1501 T10R302(DX)2002-10-26 13:56:23 00113456-0012 NO 502 T10R303(X) N/A N/A
Release 10R3: October 31, 2005 19-18 STATUS UniAccess for OS 2200 System Administration Guide
4. STATUS PID,
This command displays current status information for a single PID. The following statistics are output from this command and are illustrated in the console response below.
PID The PID allocated to this connection.
USER NAME The userid of the connected client.
TYPE The type of connection. It is either UACL or UASL.
UASL TYPE Possible UASL TYPEs are listed below:
Type Meaning
DIRECT Directly connected client application. N/A UACL connection. UADTC UADTC connection.
LOCAL IP ADDR The Internet address of the local connection.
LOCAL PORT The port number at the local connection.
REMOTE IP ADDR The Internet address of the remote connection.
REMOTE PORT The port number at the remote connection.
TDS LEVEL The TDS level supported by the client.
Release 10R3: October 31, 2005 UACS Operations Reference STATUS 19-19
TDS STATE States available to TDS STATE are listed below.
State Meaning
USED PID has been allocated but no activity has occurred. NO MMPROC The UAMM slot allocation has been lost. This will only occur in an error condition. RECEIVING LOGIN In the process of receiving a login request. WAITING FOR LOGIN Waiting for a response to a login request from a RESPONSE server. IDLE Idle and logged into a server. RECEIVING REQUEST Receiving a language or an RPC request. WAITING FOR REQUEST Waiting for the response to a language or an RPC RESPONSE request. ATTENTION RECEIVED Attention received from client. CLOSE RECEIVED Close in progress. ERROR An error has occurred on this connection.
NETWORK STATE States available to NETWORK STATE are listed below.
State Meaning
CONNECTION NOT Connection not currently established with a remote peer. ESTABLISHED CONNECTION Connection currently established with a remote peer. ESTABLISHED ACTIVE OPEN PENDING Active open request pending to a remote peer. LOCAL CLOSE PENDING Local close request issued to a remote peer. ABORT PENDING Abort request is pending. CONNECTION BLOCKED Connection is blocked. Waiting for resume from a remote peer. REMOTE CLOSE Remote close is pending from a remote peer. PENDING
Release 10R3: October 31, 2005 19-20 STATUS UniAccess for OS 2200 System Administration Guide
TRANSACTION CODE The last transaction code started. For UACL connections, this value will always be N/A. The TRANCD column consists of the transaction name with a possible appendage of (D), (X), or (DX). “D” signifies a transaction participating in a distributed transaction, “X” signifies an extended session transaction, and “DX” indicates an extended transaction participating in a distributed transaction.
TIMESTAMP Timestamp of the last activity for this connection.
BYTES RECEIVED The total number of bytes received from this remote connection since connection or last statistics reset.
PACKETS RECEIVED The total number of packets received from this remote connection since connection or last statistics reset.
BYTES SENT The total number of bytes sent to this remote connection since connection or last statistics reset.
PACKETS SENT The total number of packets sent to this remote connection since connection or last statistics reset.
TRANSACTION ID The unique identifier for a transaction participating in a distributed transaction. The transaction ID consists of a transaction timestamp (yyyy- mm-dd hh:mm:ss), transaction sequence number (nnnnnnn), and transaction step number (nnnn) in the format: yyyy-mm-dd hh:mm:ss nnnnnnn-nnnn. The transaction sequence number and the transaction step number are octal values. The unique distributed transaction ID is the step ID used by the OS 2200 operating system. For a transaction that is not participating in a distributed transaction, this statistic displays N/A.
Release 10R3: October 31, 2005 UACS Operations Reference STATUS 19-21
======UACS PID INFORMATION ======PID: 404 USER NAME: kevin67 TYPE: UASL UASL TYPE: UADTC LOCAL IP ADDR: 192.168.1.16 LOCAL PORT: 2040 REMOTE IP ADDR: 192.168.1.200 REMOTE PORT: 3776 TDS LEVEL: 5.00 TDS STATE: idle NETWORK STATE: connection established TRANSACTION CODE: RSAIS(DX) TIMESTAMP: 07/04/99 10:06:37:050 BYTES RECEIVED: 826 PACKETS RECEIVED: 12 BYTES SENT: 729 PACKETS SENT: 19 TRANSACTION ID: 2002-07-04 10:05:02 00010171-0001
5. STATUS RESET,GLOBAL (SR,GLOBAL) Command
This command requests re-initialization of all statistics counters. It displays the following response:
GLOBAL STATISTICS RESET
6. STATUS RESET,
This command requests that the statistics counter for a single PID be reset. It displays the following response:
PID STATISTICS RESET
7. STATUS USER,
This command displays detailed information about all connections with the specified userid. This may include more than one connection. The following statistics are output from this command and illustrated in the example console response below.
Release 10R3: October 31, 2005 19-22 STATUS UniAccess for OS 2200 System Administration Guide
USERID The userid of the connected client.
PID The PID allocated to this connection. For UASL connections, this is the PID used to schedule the transaction.
TYPE The type of connection. The connection type is either UASL or UACL.
UASL TYPE Possible UASL TYPEs are listed below:
Type Meaning
DIRECT Directly connected client application. N/A UACL connection. UADTC UADTC connection.
TRANCD The last transaction code executed by this connection. For UACL connections, this value will always be N/A. The TRANCD column consists of the transaction name with a possible appendage of (D), (X), or (DX). “D” signifies a transaction participating in a distributed transaction, “X” signifies an extended session transaction, and “DX” indicates an extended transaction participating in an extended session.
USERID PID TYPE UASL TYPE TRANCD ======KEVIN67 410 UACL N/A N/A KEVIN67 411 UASL DIRECT RSAIS(X) BERNI223 1500 UASL DIRECT T7A102(D) UADTC 1501 UASL UADTC N/A
Release 10R3: October 31, 2005 UACS Operations Reference SYSLOG 19-23
SYSLOG
The SYSLOG command is used to control UACS writing security-related events to the OS 2200 system log file. (These security-related events will also be written to the UACS trace file when UACS tracing is set to high.) When system security logging is on, UACS tracing may be set to any level. This allows a site to capture security-related events without impacting the performance of UACS tracing. (For more information on UACS security logging and the format of a security event log see page 19-33.)
The initial state of security event logging is configured using the COMSRV SYSLOG configuration variable (see page 16-28).
Command Formats
Command Format Short Command Description
1.
1. SYSLOG ON (SLON) Command
The SYSLOG ON command enables logging of security-related events to the system log file. The console response to this command displays the following:
SYSTEM LOGGING
2. SYSLOG OFF (SLOFF) Command
The SYSLOG OFF command disables logging of security-related events to the system log file. The console response to this command displays the following:
SYSTEM LOGGING
Release 10R3: October 31, 2005 19-24 TERM UniAccess for OS 2200 System Administration Guide
TERM
The TERM command is used to either shutdown UACS or to terminate a current client connection. Before a terminate request is serviced, the console mode of the requester is checked to ensure that he or she has response keyin privileges. The operator is queried with the following prompt to ensure that the request was truly intended:
# **UACS** ARE YOU SURE
Note You may suppress this unsolicited input message by configuring the COMSRV COMFIRMTERM parameter value to NO (see page 16-21).
Command Formats
Command Format Short Command Description
1.
1. TERM UACS,
This command shuts down the UACS specified by the command.
The timeout time specified on the shutdown request (
Release 10R3: October 31, 2005 UACS Operations Reference TERM 19-25
The console response to a TERM UACS,
UACS SHUTDOWN COMPLETE. [16] *INFORMATION*
Note After the shutdown process has been initiated, no other console keyins will be accepted.
2. TERM PID,
The TERM PID,
The TERM PID,
This command may need to be executed twice on some PIDs because UACS initially attempts to terminate all connections gracefully. If UACS cannot gracefully terminate the connection, the PID will be placed in an ERROR state. Check the status of the PID after the first termination request to determine if a second termination request is required.
The following scenarios can lead to a PID being placed into an ERROR state that will not be automatically resolved:
• UACS successfully schedules the transaction, but the transaction does not execute.
• UACS successfully schedules the transaction, but the transaction error terminates prior to performing the TDINIT call. When the transaction errors prior to performing the TDINIT call, the UniAccess Fixed-gate subsystem has not been registered for contingency notification and, therefore, must assume that the transaction is still active.
Release 10R3: October 31, 2005 19-26 TERM UniAccess for OS 2200 System Administration Guide
Note Extreme care should be taken when using this command. It should only be used to clear hung PIDs. The administrator should guarantee that currently running transactions have terminated and that the normal, application-driven termination sequence has not succeeded. Using this command in any other manner may cause UACS and UAFG to function abnormally.
The console response to a TERM PID,
INVALID PID SPECIFIED
The console response to a TERM PID,
ATTEMPTING TO TERMINATE PID nnn
where nnn is the PID being terminated.
Release 10R3: October 31, 2005 UACS Operations Reference TRACE 19-27
TRACE
The TRACE commands write debugging information to a trace file. They allow administrators to turn off tracing, to turn on and/or adjust the level of tracing, and to close and cycle a trace file. A trace file helps the administrator resolve problems by providing error, warning, and informational messages. It must be closed before it can be viewed. It may be viewed with any text editor that supports SDF images, including most OS 2200 editors. (See page D-2 for a complete list of trace file messages generated by UACS.)
Before a trace request is serviced, the console mode of the requester is checked to ensure that he or she has full keyin privileges.
The TRACE commands affect the trace file that has been named and defined by the system administrator with the COMSRV TRCFNAME configuration variable. The initial level of trace activity is configured using the COMSRV TRCLEVEL parameter. (See page 16-29.)
Note The UACS trace file is always assigned to UACS when it is active, regardless of the setting of the COMSRV TRCLEVEL parameter.
Command Formats
Command Format Short Command Description
1.
Release 10R3: October 31, 2005 19-28 TRACE UniAccess for OS 2200 System Administration Guide
1. TRACE OFF (TOFF) Command
This command turns off tracing while leaving the trace file intact. The console response to this command displays the following:
TRACE LEVEL CHANGED TO OFF
2-4. TRACE LOW (TL), TRACE MEDIUM (TM), TRACE HIGH (TH) Commands
These commands request that tracing be initiated at or changed to the selected tracing level. The initial tracing level is defined in the COMSRV TRCLEVEL configuration statement (see page page 16-29).
Tracing at a low level provides error messages; tracing at a medium level provides error and warning messages; and tracing at a high level provides error, warning, and informational messages. The console response to these commands is displayed below:
TRACE LEVEL CHANGED TO
5. TRACE CLOSE (TC) Command
This command requests that the trace file be closed and a new cycle created. In doing so, UACS sets the trace level of OFF, flushes all output to the trace file, closes it, frees it, opens a new cycle of the trace file, and resets the trace level. During the close process, incoming trace information may be lost because the trace level is temporarily set to OFF. The console response to a TRACE CLOSE command displays the following:
TRACE FILE: UNIACCESS*UACS$TRACE(123). CLOSED AND CYCLED
Release 10R3: October 31, 2005 UACS Operations Reference UAMM 19-29
UAMM
The UAMM command is used to provide information about the state of the UniAccess Message Manager, particularly the availability of UAMM connection slots. Slots can become hung when clients and /or servers abnormally terminate and the UniAccess Fixed-gate is unable to detect that the client and/or server has terminated.
To assist system administrators in determining the status of UAMM resources, the following message will be displayed on the console at UACS initialization time:
UAMM process slots, total [%d], available [%d].
where:
the 1st %d is the total number of UAMM slots allocated, and
the 2nd %d is the total number of slots available.
The above message will also appear in the trace file.
Before UACS services the UAMM command, it checks the console mode of the requester to ensure that he or she has full key-in privileges.
Command Formats
Command Format Short Command Description
1.
1. UAMM SUMMARY (US) Command
This command determines the status of UniAccess Fixed-gate UAMM resources. This provides information about resources used by this UACS and all other UACSs currently using the Fixed-gate. The following statistics are output from this command and are illustrated in the example console response that follows.
Release 10R3: October 31, 2005 19-30 UAMM UniAccess for OS 2200 System Administration Guide
UACS Attachment States
UNUSED The number of unallocated UACS attachment slots. This indicates the number of additional UACSs that could be started for this fixed-gate.
USED The number of allocated UACS attachment slots. This indicates the number of UACSs currently active.
ERROR The number of UACS attachment slots marked in error. These slots cannot be recovered. To free these slots the Fixed-gate must be reinitialized. (For information on reinitializing the UniAccess Fixed-gate, see page 6-12.)
TOTAL The total number of UACS attachment slots.
UAMM Process Slot States
UNUSED The number of unallocated UAMM process slots. This indicates the number of additional connections the UniAccess Fixed-gate can support.
NORMAL The number of allocated UAMM slots by all UACSs.
ATTENTION The number of UAMM slots in an attention state.
LOGIN The number of UAMM slots in a login state.
ERROR The number of UAMM slots in an error state. These slots may not be recovered. If this number becomes too large, the UniAccess Fixed-gate must be reinitialized. (For information on reinitializing the UniAccess Fixed-gate, see page 6-12.)
Release 10R3: October 31, 2005 UACS Operations Reference UAMM 19-31
TOTAL The total number of UAMM slots configured for this fixed-gate.
UAMM Memory Block States:
CONFIGURED The UAMM BLOCKCNT parameter value.
UNUSED The number of available UAMM memory blocks.
BLOCKSIZE The UAMM BLOCKSIZE parameter value.
NUMBER OF BANKS The number of banks created by UAMM to hold all the UAMM memory blocks.
UAMM Product Key Connection States:
CONFIGURED UACL/UAHS/UARS/UASL The product key limits for each product.
ACTIVE UACL/UAHS/UARS/UASL The current active count for each product key. The current active product key count may not exceed the configured product key count. Any attempt to violate this rule will result in a connection being rejected. The difference between configured and active denotes the expansion capability for each product key’s connections.
Release 10R3: October 31, 2005 19-32 UAMM UniAccess for OS 2200 System Administration Guide
======UAMM Summary Information ======UACS Attachment States: Unused: 15 Used: 1 Error: 0 Total: 16 UAMM Process Slot States: Unused: 99 Normal: 1 Attention: 0 Login: 0 Error: 0 Total: 100 UAMM Memory Block States: Configured 1000 Unused: 149 Blocksize: 512 Number of Banks: 1 UAMM Product Key Connection States: Configured UACL/UAHS/UARS/UASL: 65000/ 65000/ 65000/ 65000 Active UACL/UAHS/UARS/UASL: 0/ 0/ 0/ 0
Release 10R3: October 31, 2005 UACS Operations Reference UAMM 19-33
UACS Security Logging UACS can be configured to write security events to the OS 2200 system log file. The events that will optionally be logged in the system log file are a subset of events that may be logged to the UACS trace file. Writing these events to the system log file has the following advantages:
• The system log file is normally a protected file.
• The system log file can easily be monitored as it is being written to allow detection of security violation attempts.
• The security events can be written to the system log file with UACS tracing on low to minimize the performance impact.
• Third party tools may be used to analyze the log file for security events.
Control of UACS’s writing security related events to the system log file is controlled by the SYSLOG configuration parameter of the COMSRV configuration statement (see page 16- 28) and the SYSLOG console command (see page 19-23).
Security Event Log Entry Format
The security events written to the OS 2200 system log file by UACS correspond to the User Formatted Log Entries as described in the Unisys OS 2200 System Log Operations and Support Reference Manual. The first eleven words of the security event log entry (words 0 to 012) are the system log type identifier. The system log type identifier is defined by the SYSLOGTYPE parameter of the COMSRV configuration statement (see page 16-29).
The security event log entry subtype is the message code (msgcode) of the UACS Trace File entry that corresponds to the system log file message. These entries are a subset of the UACS Trace File messages specific to UACS security events and are listed on page D-38 of Appendix D.
The data area of the security event log contains ASCII characters. The fields used to create the ASCII text of the message are:
Release 10R3: October 31, 2005 19-34 UAMM UniAccess for OS 2200 System Administration Guide
Field Description Size in Bytes
Preamble size Size of text preceding UACS message, currently 52 4 COMSRV name Name of the COMSRV (UACS) that wrote the entry 7 F-cycle header The string “Trace F-Cycle: “ 15 F-cycle Current UACS file cycle 6 Reserved Reserved for future use 19 End sentinel Line Feed character (012) 1 Message The security related message Up to 306
For example, the following is a Log Analyzer dump of a UACS security event log.
Type=59999 Subtype=24 length=65 version=0 classification=000001 time stamp=04 Sep 28 0951:50.116 thread-id=000267337501 626027427050 caller-id=000267337501 626027427050 run-id=UACS
0000 300013000101 010400000000 000267372207 136661340142 165137000030 000000000000 000000000001 000267337501 0010 626027427050 000267337501 626027427050 040065062040 125101103123 040040040124 162141143145 040106055103 0020 171143154145 072040040040 040065062064 040040040040 040040040040 040040040040 040040040040 040040040012 0030 060071057062 070057060064 040060071072 065061072065 060072061061 064040133061 061065061062 064060060060 0040 060060064135 040133062064 135040052111 116106117122 115101124111 117116052012 040040103154 151145156164 0050 040154157147 151156040162 145143145151 166145144040 040055040040 125163145162 156141155145 040075040133 0060 142154165145 146151163150 135054040160 151144040075 040133064070 065135054040 155155151144 040075040133 0070 063070065060 135054040111 120055141144 144162040075 040133061071 062056061066 070056061056 070067135056 0100 012000040202
0000 ###A #### #### ^##b u_## #### #### #### 0010 ###( #### ###( 52 UACS T race F-C 0020 ycle : 524 # 0030 09/2 8/04 09: 51:5 0:11 4 [1 1512 4000 0040 004] [24 ] *I NFOR MATI ON*# Cl ient 0050 log in r ecei ved - User name = [ 0060 blue fish ], p id = [48 5], mmid = [ 0070 3850 ], I P-ad dr = [19 2.16 8.1. 87]. 0100 ## #
Release 10R3: October 31, 2005 Appendixes Appendixes ......
Appendix A: UniAccess System Product Installation Files
Appendix B: Configuration Relationships
Appendix C: UniAccess Sample Programs
Appendix D: UniAccess System Messages
Appendix E: UniAccess System Tables
Appendix F: Troubleshooting and Problem Reporting
Appendix G: References
A Installation Files A UniAccess System Product Installation Files
The tables in this appendix describe the contents of each of the product installation files for the current release of the UniAccess System for OS 2200. Table A-1 describes the files installed by Modes A and B, the production modes; Table A-2 describes the files installed by Modes C and D, the test modes. (See Chapter 4, Installing the UniAccess System, for the distinction between modes.)
Topics Page
Installation Files for Production Modes A and B A-2 Notes A-6 Installation Files for Test Modes C and D A-7 Notes A-12
Note All product installation files have a default qualifier of SYS$LIB$.
Release 10R3: October 31, 2005 A-2 UniAccess for OS 2200 System Administration Guide
Installation Files for Production Modes A and B Table A-1 lists the contents of product installation files for Mode A, the official production release, and Mode B, the maintenance update production release of the UniAccess product suite.
Table A-1: UniAccess 10R3 Product Installation Files for Production Modes A and B
File Element Description Used in ENGL$ISO-1 US English/ISO-1 localization files UACL COBCT/LOC COBOL layer localization file UACL COMMON/LOC Common library localization file UACL CSLIB/LOC CS library localization file UACL CTLIB/LOC CT library localization file UACL LIBUAMM/LOC UAMM localization file UACL LOCALES/DAT Localization information file UACL TCLLIB/LOC TCL library localization file UACL ISO-1 ISO-1 character set files UACL BINARY/SRT Binary character set file UACL CHARSET/LOC Character set information file UACL UAAFCB* ASCII COBOL Interface UASL BANK-BDI$ SOLAR BANK BDI UASL CBEP$$BMAFCB External entry points (Rel) UASL CBEP$$BMAFCB External entry points (MASM) UASL TPENPE$I ASCII COBOL interface AFCB UASL UAFG UAFG fixed-gate definition BANK-BDI$ UAFG SOLAR BANK BDI ALL MASM-EP UAFG entry point module ALL SSDEF$ UAFG SOLAR SSDEF ALL UACLSTUB/OBJ UACL external functions UACL UASLSTUB/OBJ UASL MCB-specific functions UASL UAINCL Copyprocs and include files CLCOPYPROC UACL COBOL copyproc source UACL CLCPCOB UACL COBOL copyproc (PDP'd) UACL
Release 10R3: October 31, 2005 UniAccess System Product Installation Files A-3
File Element Description Used in UAINCL CSCONFIG/H UACL 'C' header UACL (continued) CSPUBLIC/H UACL 'C' header UACL CSTYPES/H UACL 'C' header UACL CTPUBLIC/H UACL 'C' header UACL SLCOPYPROC UASL COBOL copyproc source UASL SLCOPYPROCA UASL ASCII COBOL copyproc source UASL SLCPCOB UASL COBOL copyproc (PDP'd) UASL SLCPCOBA UASL ASCII COBOL copyproc (PDP'd) UASL SQLCA/H UACL 'C' header UACL SRV/H UASL 'C' header UASL SYBDB/H UASL 'C' header UASL SYBDBTOK/H UASL 'C' header UASL SYBFRONT/H UASL 'C' header UASL SYBLOGIN/H UASL 'C' header UASL UACLCKIT/H UACL 'C' header UACL UASL/H UASL 'C' header UASL UASLCKIT/H UASL 'C' header UASL USRXLATE/H translation 'C' utility header UAHS/UARS UAOM UAFG subsystem absolute ALL UAOM UAFG subsystem absolute ALL UASAMP Sample programs and database CLNT1/C UACL sample 'C' program UACL CLNT1/UCOB UACL sample UCS COBOL program 1 UACL CLNT1SS/UCOB UACL sample UCS COBOL program UACL that access Microsoft SQL Server CLNT2/UCOB UACL sample UCS COBOL program 2 UACL CLNT2SS/UCOB UACL sample UCS COBOL program UACL that access Microsoft SQL Server CLNT3/UCOB UACL sample UCS COBOL program 3 UACL CLNT4/UCOB UACL sample UCS COBOL program 4 UACL CLNT5/UCOB UACL sample UACS COBOL program 5 UACL EMPREVIEW1/SQL RDMS SQL insert table commands UARS EMPREVIEW2/SQL RDMS SQL insert table commands UARS
Release 10R3: October 31, 2005 A-4 UniAccess for OS 2200 System Administration Guide
File Element Description Used in UASAMP EMPREVIEW5/SQL RDMS SQL insert table commands UARS (continued) RDMSBLD/ADD Add runstream to build RDMS database UARS/UASL RDMSBLD/SQL RDMS SQL database creation commands UARS/UASL RDMSDRP/SQL RDMS SQL delete table commands UARS/UASL RDMSDRP/ADD Add runstream to drop RDMS database UARS/UASL RDMSDRP/URP RDMS UREP delete storage-area and UARS/UASL database commands SECOFF/C Logoff security transaction 'C' sample UARS SECOFF/UCOB Logoff security transaction UCS COBOL UARS sample SECON/C Logon security transaction 'C' sample UARS SECON/UCOB Logon security transaction UCS COBOL UARS sample SERV1/ACOB UASL sample ASCII COBOL program UASL SERV1/C UASL sample 'C' program 1 UASL SERV2/C UASL sample ‘C’ program 2 UASL SERV1/UCOB UASL sample UCS COBOL program 1 UASL SERV2/UCOB UASL sample UCS COBOL program 2 UASL SERV3/UCOB UASL sample UCS COBOL program 3 UASL SERVL/UCOB UASL sample language program UASL SERV5/UCOB UASL sample UCS COBOL program 5 UASL SSRVBLD/SQL SQL Server database creation commands UACL UACLSAMPLE/C UACL sample 'C' utility routines UACL UACLSAMPLE/H UACL sample 'C' utility header UACL UACLSAMPLE/PROC UACL sample UCS COBOL utility routines UACL UASLSAMPLE/C UASL sample 'C' utility routines UASL UASLSAMPLE/H UASL sample 'C' utility header UASL UASLSAMPLE/PROC UASL sample UCS COBOL utility routines UASL UASLSAMPLE/PROCA UASL sample ASCII COBOL utility routines UASL UASLSAMPLE/VALTABS UASL sample program VALTABs UASL UAUTIL Utilities CLPRMCHK UACL parameter checking ECL UACL CPTOUCH1S1/OBJ Utility to update UNIACCESS TABLES UARS
Release 10R3: October 31, 2005 UniAccess System Product Installation Files A-5
File Element Description Used in UAUTIL DEACTUAFG UAFG fixed-gate SOLAR deactivation ALL (continued) ISQL ISQL absolute UACL MCHINFO Utility to obtain MCN number ALL SCHEMADEF SCHEMADEF absolute UAHS SET$PARAMS/OBJ Dummy routine UARS SLPRMCHK UASL parameter checking ECL UASL TABLEDEF TABLEDEF absolute UAHS TPENPEAFCB/REL Basic mode bridge AFCB UASL UACF UniAccess configuration utility ALL UACLSTUB/OBJ UACL external functions UACL UACLSTUBDBG/OBJ UACL parameter checking module UACL UACOMN/OBJ UniAccess common library ALL UACS UACS absolute ALL UACS UACS startup batch stream ALL UACS/OBJ UACS library ALL UACSCP/BUILD Re-links UACS for use with CPComm ALL UACSTC/BUILD Re-links UACS for use with test-mode CMS ALL UAHS* UAHS absolute UAHS UAHS/BUILD* UAHS transaction build routine UAHS UAHS/INSTALL UAHS environment SBS UAHS UAHS/OBJ UAHS library UAHS UAIN* UAINFO absolute UASL UAIN/OBJ UAINFO object module UASL UAINFO/BUILD* UAINFO transaction build routine UASL UAINFO/INSTALL UAINFO installation SSG UASL UAIR UAIR absolute UASL/UARS UAOSDMS/CFG UAOS for DMS Site information template UAHS UAOSRDMS/CFG UAOS for RDMS Site information template UARS UARS* UARS absolute UARS UARS/BUILD* UARS transaction build routine UARS UARS/INSTALL UARS environment SSG UARS UARS/OBJ UARS library UARS
Release 10R3: October 31, 2005 A-6 UniAccess for OS 2200 System Administration Guide
File Element Description Used in UARS/KANJI UARS library supporting Kanji UARS UAUTIL UASLBMB/BUILD* UASL basic mode bridge build routine UASL (continued) UASLBMB/INSTALL UASL basic mode bridge installation SSG UASL UASLSTUB/OBJ UASL MCB-specific functions UASL UASLSTUB/REL UASL basic mode MCB-specific functions UASL UASLSTUBDBG/OBJ UASL parameter checking module UASL UATC/CFG UATC Site information template UACL UATS/CFG UATS Site information template UASL UNIACCESS/CREATE* UNIACCESS database creation script UARS UNIACCESS/ UNIACCESS database creation script UARS CREATE$SKEL template UNIACCESS/DELETE* UNIACCESS database deletion script UARS UNIACCESS/ UNIACCESS database deletion script UARS DELETE$SKEL template UNIACCESS6R1/DELETE* UNIACCESS 6R1 database deletion script UARS UNIACCESS6R1/ UNIACCESS 6R1database deletion script UARS DELETE$SKEL template UNIACCESS6R1/ UNIACCESS 6R1to 8R2 database migration UARS MIGRATE* script UNIACCESS6R1/ UNIACCESS 6R1to 8R2 database migration UARS MIGRATE$SKEL script template UNIACCESS/INC UA information file template ALL USRXLATE/C Translation 'C' utility routine UAHS/UARS USRXLATE/CMP Translation 'C' utility compile batch stream UAHS/UARS UARXLATE/OBJ Translation 'C' utility routine UAHS/UARS
Notes
The files/elements marked with an asterisk (*) are created as the result of user-run build scripts. These components will not exist at the completion of the SOLAR install.
For UniAccess installation in Modes A and B, the installation routine places a start script in SYS$LIB$*RUN$. for UACS and registers the ISQL processor.
Release 10R3: October 31, 2005 UniAccess System Product Installation Files A-7
Installation Files for Test Modes C and D Table A-2 lists the contents of product installation files for Mode C, the test mode for the official release, and Mode D, the test mode for the maintenance update version of the UniAccess product suite.
Table A-2: UniAccess 10R3 Product Installation Files for Test Modes C and D
File Element Description Used in ENGL$ISO-1T US English/ISO-1 localization files UACL COBCT/LOC COBOL layer localization file UACL COMMON/LOC Common library localization file UACL CSLIB/LOC CS library localization file UACL CTLIB/LOC CT library localization file UACL LIBUAMM/LOC UAMM localization file UACL LOCALES/DAT Localization information file UACL TCLLIB/LOC TCL library localization file UACL ISO-1T ISO-1 character set files UACL BINARY/SRT Binary character set file UACL CHARSET/LOC Character set information file UACL UAAFCBT* ASCII COBOL Interface UASL BANK-BDI$ SOLAR BANK BDI UASL CBEP$$BMAFCB External entry points (Rel) UASL CBEP$$BMAFCB External entry points (MASM) UASL TPENPE$I ASCII COBOL interface AFCB UASL UAFGT UAFG fixed-gate definition BANK-BDI$ UAFG SOLAR BANK BDI ALL MASM-EP UAFG entry point module ALL SSDEF$ UAFG SOLAR SSDEF ALL UACLSTUB/OBJ UACL external functions UACL UASLSTUB/OBJ UASL MCB-specific functions UASL UAINCLT Copyprocs and include files CLCOPYPROC UACL COBOL copyproc source UACL CLCPCOB UACL COBOL copyproc (PDP'd) UACL
Release 10R3: October 31, 2005 A-8 UniAccess for OS 2200 System Administration Guide
File Element Description Used in UAINCLT CSCONFIG/H UACL 'C' header UACL (continued) CSPUBLIC/H UACL 'C' header UACL CSTYPES/H UACL 'C' header UACL CTPUBLIC/H UACL 'C' header UACL SLCOPYPROC UASL COBOL copyproc source UASL SLCOPYPROCA UASL ASCII COBOL copyproc source UASL SLCPCOB UASL COBOL copyproc (PDP'd) UASL SLCPCOBA UASL ASCII COBOL copyproc (PDP'd) UASL SQLCA/H UACL 'C' header UACL SRV/H UASL 'C' header UASL SYBDB/H UASL 'C' header UASL SYBDBTOK/H UASL 'C' header UASL SYBFRONT/H UASL 'C' header UASL SYBLOGIN/H UASL 'C' header UASL UACLCKIT/H UACL 'C' header UACL UASL/H UASL 'C' header UASL UASLCKIT/H UASL 'C' header UASL USRXLATE/H translation 'C' utility header UAHS/UARS UAOMT UAFG subsystem absolute ALL UAOM UAFG subsystem absolute ALL UASAMPT Sample programs and database CLNT1/C UACL sample 'C' program UACL CLNT1/UCOB UACL sample UCS COBOL program 1 UACL CLNT1SS/UCOB UACL sample UCS COBOL program UACL that access Microsoft SQL Server CLNT2/UCOB UACL sample UCS COBOL program 2 UACL CLNT2SS/UCOB UACL sample UCS COBOL program UACL that access Microsoft SQL Server CLNT3/UCOB UACL sample UCS COBOL program 3 UACL CLNT4/UCOB UACL sample UCS COBOL program 4 UACL CLNT5/UCOB UACL sample UACS COBOL program 5 UACL EMPREVIEW1/SQL RDMS SQL insert table commands UARS EMPREVIEW2/SQL RDMS SQL insert table commands UARS EMPREVIEW5/SQL RDMS SQL insert table commands UARS
Release 10R3: October 31, 2005 UniAccess System Product Installation Files A-9
File Element Description Used in UASAMPT RDMSBLD/ADD Add runstream to build RDMS database UARS/UASL (continued) RDMSBLD/SQL RDMS SQL database creation commands UARS/UASL RDMSDRP/SQL RDMS SQL delete table commands UARS/UASL RDMSDRP/ADD Add runstream to drop RDMS database UARS/UASL RDMSDRP/URP RDMS UREP delete storage-area and UARS/UASL database commands SECOFF/C Logoff security transaction 'C' sample UARS SECOFF/UCOB Logoff security transaction UCS COBOL UARS sample SECON/C Logon security transaction 'C' sample UARS SECON/UCOB Logon security transaction UCS COBOL UARS sample SERV1/ACOB UASL sample ASCII COBOL program UASL SERV1/C UASL sample 'C' program 1 UASL SERV2/C UASL sample ‘C’ program 2 UASL SERV1/UCOB UASL sample UCS COBOL program 1 UASL SERV2/UCOB UASL sample UCS COBOL program 2 UASL SERV3/UCOB UASL sample UCS COBOL program 3 UASL SERVL/UCOB UASL sample language program UASL SERV5/UCOB UASL sample UCS COBOL program 5 UASL SSRVBLD/SQL SQL Server database creation commands UACL UACLSAMPLE/C UACL sample 'C' utility routines UACL UACLSAMPLE/H UACL sample 'C' utility header UACL UACLSAMPLE/PROC UACL sample UCS COBOL utility routines UACL UASLSAMPLE/C UASL sample 'C' utility routines UASL UASLSAMPLE/H UASL sample 'C' utility header UASL UASLSAMPLE/PROC UASL sample UCS COBOL utility routines UASL UASLSAMPLE/PROCA UASL sample ASCII COBOL utility routines UASL UASLSAMPLE/VALTABS UASL sample program VALTABs UASL UATEST Test version components CBEP$$BMAFCB/TEST Used for test mode ALL COMN/OBJ UACL service library UACL CS/OBJ UACL service library UACL
Release 10R3: October 31, 2005 A-10 UniAccess for OS 2200 System Administration Guide
File Element Description Used in UATEST CT/OBJ UACL service library UACL (continued) FGSS/MSM UAFG entry point source module ALL FGSSBM/MSM UASL basic mode omnibus UASL FGSSBM/MSM UASL basic mode source UASL INTL/OBJ UACL service library UACL ISQL/OBJ ISQL library UACL ISQL/LINK ISQL link ECL stream UACL MCHINFO/OBJ Object module for mchinfo utility ALL MCHINFO/LINK Link runstream for mchinfo utility ALL NET/OBJ UACL service library UACL SSDEF SSDEF module ALL UACF/OBJ UACF library ALL UACF/LINK UACL link ECL stream ALL UACLSTUB/OBJ UACL external functions UACL UACOMN/OBJ UniAccess common library ALL UACS/OBJ UACS library ALL UACS/LINK UACL link ECL stream ALL UADT/OBJ UADT service library ALL UAMM/OBJ UAMM library ALL UAOM/LINK UAOM link ECL stream ALL UASL/OBJ UASL service library UASL UASLSTUB/MSM UASL basic mode source UASL UASLSTUB/OBJ UASL external functions UASL UNIACCESS/ Build script for test mode ALL SITE-INSTALL UAUTILT Utilities CLPRMCHK UACL parameter checking ECL UACL CPTOUCH1S1/OBJ Utility to update UNIACCESS tables UARS DEACTUAFG UAFG fixed-gate SOLAR deactivation ALL ISQL* ISQL absolute UACL MCHINFO Utility to obtain MCN number ALL SCHEMADEF SCHEMADEF absolute UAHS
Release 10R3: October 31, 2005 UniAccess System Product Installation Files A-11
File Element Description Used in UAUTILT SET$PARAMS/OBJ Dummy routine UARS (continued) SLPRMCHK UASL parameter checking ECL UASL TABLEDEF TABLEDEF absolute UAHS TPENPEAFCB/REL Basic mode bridge AFCB UASL UACF* UniAccess configuration utility ALL UACLSTUB/OBJ UACL external functions UACL UACLSTUBDBG/OBJ UACL parameter checking module UACL UACOMN/OBJ UniAccess common library UARS UACS* UACS absolute ALL UACSCP/BUILD Re-links UACS for use with CPComm ALL UACST UACS startup batch runstream ALL UAHS* UAHS absolute UAHS UAHS/BUILD* UAHS build routine UAHS UAHS/INSTALL UAHS environment SBS UAHS UAHS/OBJ UAHS library UAHS UAIN* UAINFO absolute UASL UAIN/OBJ UAINFO object module UASL UAINFO/BUILD* UAINFO transaction build routine UASL UAINFO/INSTALL UAINFO installation SSG UASL UAIR UAIR absolute UASL/UARS UAOSDMS/CFG UAOS for DMS Site information template UAHS UAOSRDMS/CFG UAOS for RDMS Site information template UARS UARS* UARS absolute UARS UARS/BUILD* UARS transaction build routine UARS UARS/INSTALL UARS environment SSG UARS UARS/OBJ UARS library UARS UARS/KANJI UARS Library supporting Kanji UARS UASLBMB/BUILD* UASL basic mode bridge build routine UASL UASLBMB/INSTALL UASL basic mode bridge installation SSG UASL UASLSTUB/OBJ UASL MCB-specific functions UASL UASLSTUB/REL* UASL basic mode MCB-specific functions UASL UASLSTUBDBG/OBJ UASL parameter checking module UASL
Release 10R3: October 31, 2005 A-12 UniAccess for OS 2200 System Administration Guide
File Element Description Used in UAUTILT UATC/CFG UATC Site information template UACL (continued) UATS/CFG UATS/ODBC Site information template UARS UNIACCESS/CREATE* UNIACCESS database creation script UARS UNIACCESS/ UNIACCESS database creation script UARS CREATE$SKEL template UNIACCESS/DELETE* UNIACCESS database deletion script UARS UNIACCESS/ UNIACCESS database deletion script UARS DELETE$SKEL template UNIACCESS6R1/ UNIACCESS 6R1database deletion script UARS DELETE* UNIACCESS6R1/ UNIACCESS 6R1to 8R2 database deletion UARS DELETE$SKEL script template UNIACCESS6R1/ UNIACCESS 6R1to 8R2 database migration UARS MIGRATE* script UNIACCESS6R1/ UNIACCESS 6R1to 8R2 database migration UARS MIGRATE$SKEL script template UNIACCESS/INC UA information file template ALL USRXLATE/C Translation 'C' utility routine UAHS/UARS USRXLATE/CMP Translation 'C' utility compile batch stream UAHS/UARS USRXLATE/OBJ Translation 'C' utility routine UAHS/UARS
Notes
The files/elements marked with an asterisk (*) are created as the result of user-run build scripts. These components will not exist at the completion of the SOLAR install.
For UniAccess installation in Modes C and D, the installation routine places a start script in SYS$LIB$*RUN$. for UACST and places the ISQL processor in SYS$LIB$*UAUTILT.
Release 10R3: October 31, 2005 B Config Relationships B Configuration Relationships
This appendix shows how to configure UniAccess System for OS 2200 on a Local Area Network (LAN) with UNIX, Windows and DOS platforms and contains the following sections. An understanding of OS 2200 and Microsoft client/server configuration techniques is assumed.
Topics Page
Configuration Example B-2 OS 2200 Configuration B-3 Sybase SQL Server UNIX Configuration B-8 Microsoft SQL Server Configuration B-8 Configuration Relationship Tables B-9 Application Group Definition Relations B-9 Internationalization Relations B-10 TSAM Relations B-10 Activity Relations B-11 Session Relations B-11 UniAccess Service Relations B-11 Network Address Relations B-13 PID Definition Relations B-14 Message Definition Relations B-14 User Definition Relations B-15 UniAccess CPComm Configurations B-16 UniAccess DCP Configurations B-17
Release 10R3: October 31, 2005 B-2 UniAccess for OS 2200 System Administration Guide
Configuration Example Figure B-1 illustrates a sample configuration based on a simple network consisting of three platforms (UNIX, Windows, and DOS) and one OS 2200 host attached to a LAN. The OS 2200 host accesses the LAN through the Host LAN Controller (HLC). In the tables that follow the diagram, parameters indicated in boldface type are those that are referred to in the Configuration Relationship Tables section.
Windows DOS Open Client Open Client
UNIX host
LAN
HLC OS 2200 Host
12 12
12 12
12345 789
Figure B-1: Sample Configuration
Release 10R3: October 31, 2005 Configuration Relationships B-3
OS 2200 Configuration
UniAccess Configuration — Site Information File
1 .======2 .= = 3 .= Description: Site Information File = 4 .= Version: 10R3 = 5 .= = 6 .======7 . 8 .------. 9 . Application Group Definitions . 10 .------. 11 APPINF APPNUM,3 ; 12 APPNAME,UDSSRC ; 13 MCBBDI,0400612 ; 14 UAHSTIPF,50 ; 15 UDSBDI,0400753 16 . 17 .------. 18 . Character Set Definitions . 19 .------. 20 CHARSET NAME,iso_1 ; 21 FILE,SYS$LIB$*ISO-1. 22 . 23 .------. 24 . Communication Server Definitions . 25 .------. 26 COMSRV PROCNAM,UACS ; 27 PROCPSWD,PASSWORD ; 28 APPNUM,3 ; 29 USEUAUSER,YES ; 30 USERMTSRV,YES ; 31 DFLTTRAN,UARSTRAN,UASL,UAHS ; 32 UAHSTRAN,UAHS ; 33 UARSTRAN,UARS ; 34 LISTENPRT,2050 ; 35 PIDSTART,400 ; 36 PIDCNT,50 ; 37 TIPQCNT,3 ; 38 TSAMCNT,3 39 . 40 .------. 41 . Localization Definitions . 42 .------. 43 LOCALE NAME,default ; 44 LANGUAGE,us_english ;
Release 10R3: October 31, 2005 B-4 UniAccess for OS 2200 System Administration Guide
45 CHARSET,iso_1 ; 46 FILE,SYS$LIB$*ENGL$ISO-1. 47 . 48 .------. 49 . Operating System Definitions . 50 .------. 51 OSPARM SESSCTRL,YES ; 52 UACLPRODKEY,XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX 53 UAHSPRODKEY,XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX 54 UARSPRODKEY,XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX 55 UASLPRODKEY,XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX 56 . 57 .------. 58 . Remote Server Definitions . 59 .------. 60 SERVER NAME,MSSQL7 ; 61 ADDR,192.152.80.3 ; 62 PORT,2025 ; 63 MSSQLSRV,YES 64 . 65 .------. 66 . User Definitions . 67 .------. 68 UAUSER USERID,demouser ; 69 SCHEMA,UASAMPLE ; 70 SCHEMAH,UAUSAMPLE ; 71 COMSRV,UACS 72 UAUSER USERID,uademo ; 73 SCHEMA,UADEMO ; 74 COMSRV,UACS
UniAccess Configuration — UA Information File
1 .======2 .= = 3 .= Description: UniAccess Information File = 4 .= Version: 10R3 = 5 .= = 6 .======7 . 8 .------. 9 . RPC to VALTAB Mapping Definitions . 10 .------. 11 RPCMAP RPCNAME,sp_column_privileges ; 12 TRANCODE,%%UACP 13 RPCMAP RPCNAME,sp_columns ; 14 TRANCODE,%%UAPC 15 RPCMAP RPCNAME,sp_databases ; 16 TRANCODE,%%UACP
Release 10R3: October 31, 2005 Configuration Relationships B-5
17 18 ... 19 20 RPCMAP RPCNAME,sp_tables ; 21 TRANCODE,%%UACP 22 RPCMAP RPCNAME,uars ; 23 TRANCODE,%%UARS 24 RPCMAP RPCNAME,UARS ; 25 TRANCODE,%%UARS 26 RPCMAP RPCNAME,uahs ; .UAHS RPC map (lowercase) 27 TRANCODE,%%UAHS 28 RPCMAP RPCNAME,UAHS ; .UAHS RPC map (UPPERCASE) 29 TRANCODE,%%UAHS 30 . 31 .------. 32 . Message Text Definitions . 33 .------. 34 UAMESG CODE,103 ; 35 TEXT,"String is too long (RDMS: %s)" 36 UAMESG CODE,105 ; 37 TEXT,"Unclosed quote (RDMS: %s)" 38 UAMESG CODE,138 ; 39 TEXT,"Illegal correlation clause in subquery (RDMS: %s)" 40 41 ... 42 43 UAMESG CODE,33819 ; 44 TEXT,"UACS error: Transaction timeout detected (%s), connection \ 45 aborted" 46 UAMESG CODE,33820 ; 47 TEXT,"UACS error: Catalog requests not supported by configured \ 48 language transaction" 49 UAMESG CODE,33821 ; 50 TEXT,"UACS error: Language requests not supported by current \ 51 configuration" 52 . 53 .------. 54 . Message Map Definitions . 55 .------. 56 UAMMAP CODE,206 FLAG,S MAPCODE,105 57 UAMMAP CODE,300 FLAG,S MAPCODE,2717 58 UAMMAP CODE,312 FLAG,S MAPCODE,103 59 60 ... 61 62 UAMMAP CODE,33819 FLAG,U MAPCODE,33819 63 UAMMAP CODE,33820 FLAG,U MAPCODE,33820 64 UAMMAP CODE,33821 FLAG,U MAPCODE,33821
Release 10R3: October 31, 2005 B-6 UniAccess for OS 2200 System Administration Guide
CMS 1100 Configuration
1 PROCESS,UACS TYPE,TSAM ; 2 PASSWORD,PASSWORD ; 3 INTERNET-ADR,UACSIP 4 5 INTERNET-ADR,UACSIP IP,HOST,192.152.80.200 6 7 IP,HOST LINK-LAYER,LAN1 8 9 STATIC-BANKS TCP-MCB,TCP/IP 10 11 INFO BMMAX,262000
MCB Configuration
1 APNAME UDSSRC . APPLICATION NAME 2 APNUMBER 3 . STEP CONTROL APPLICATION GROUP NUMBER 3 EXTENDEDMODE YES . ENABLE EXTENDED MODE 4 MCBNUM 7 . CMS USED BY MCB 5 SLT$NUM 100 . # OF CONCURRENT RUNS USING MCB (SLOTS) 6 MCBBDI 0400612 . BDI OF MCBBNK COMMON BANK 7 EMMCBBDI 0402662 . BDI OF EMMCB COMMON BANK 8 P$ID 1,3000 1,1 1,1 1,0,0,0 . PID - MRF
TIP - VALTAB Configuration
1 95 ACT,UARS 2 AUD,3 3 NAM,UARS 4 OPT,LMTZ 5 PRG,3 6 PRT,PR 7 QPR,3 8 STA,JLM 9 96 ACT,UAHS 10 AUD,3 11 NAM,UARS 12 OPT,LMTZ 13 PRG,3 14 PRT,PR 15 QPR,3 16 STA,JLM
Release 10R3: October 31, 2005 Configuration Relationships B-7
EXEC Configuration
1 STEPCONTROL 3 APPLICATION NAME IS UDSSRC. 2 STEPCONTROL 3 NUMBER OF CONCURRENT SESSIONS IS 100. 3 STEPCONTROL 3 SESSIONFILE CONTAINER IS QUAL,FILENAME 4 TFPMAX 500 5 TIPMEF 500
UDS - Dynamic System Reconfiguration
1 APPL-NAME UDSSRC 2 APPL-GROUP-NUMBER 3 3 MCB-MSG-BANK-BDI 0400612 4 MCB-RECY-BANK-BDI 0 5 MCB-ENTRY-POINT 01000
UDS Control —System Generation Statements
1 appl_bank 0405170 UDSC$PFGSBDI attr5 2 appl_bank 0405171 UDSC$CFGSBDI attr5 3 appl_bank 0400660 UDS$TCLCD001 attr1 4 appl_bank 0402436 UDS$TCLCD002 attr1 5 appl_bank 0405172 UDS$TCLCD003 attr1 6 appl_bank 0400753 UDS$TCLCDICR attr1 7 appl_bank 0400664 UDS$TCSICR attr1
SIMAN Configuration
1 INSTALL USERID = DEMOUSER 2 MINIMUM_CLEARANCE = 0 3 MAXIMUM_CLEARANCE = 0 4 FILE = UNOWNED 5 ADD PRIVILEGES = SMOQUE 6 USERID_MAINTENANCE = USER 7 MINIMUM_PASSWORDDAYS = 0 8 MAXIMUM_PASSWORDDAYS = 180 9 RUN_MODE = DEMAND , BATCH , TIP 10 TIME 11 LOGON = 60 12 DISABLE 13 RUN_GENERATION = SYSTEM 14 MAXIMUM_TIME = 999 15 MAXIMUM_PAGES = 999999 16 RUN_PROJECTID = AIS 17 RUN_ACCOUNT = UNIACCESS 18 CONSOLE_MODE = DISPLAY 19 LIST KEYINS = RUNSTA
Release 10R3: October 31, 2005 B-8 UniAccess for OS 2200 System Administration Guide
Sybase SQL Server UNIX Configuration
Interfaces File Configuration
1 UACS 2 query tcp enet uacs 2050 3 SYBASE 4 query tcp enet ais 2025 5 master tcp enet ais 2025 6 console tcp enet ais 2026
Host File Configuration
1 192.152.80.200 uacs 2 192.152.80.3 ais
Microsoft SQL Server Configuration
The Microsoft SQL Server is configured graphically. The steps to view the port using the SQL Server Enterprise Manager for SQL Server 2000 are:
• Right click on the server name, in the left pane. • Select Properties. •In the General tab, click on Network Configuration. • In the right box, highlight TCP/IP and click on the Properties box. •Click Cancel. •Click Cancel. •Click Cancel. • Exit the SQL Server Enterprise Manager.
SQL Server will use the IP address of the machine on which it is installed. To find out the IP Address of a Windows NT or Windows 2000 workstation or server:
• Open a command prompt window. • Enter the command: ipconfig
Release 10R3: October 31, 2005 Configuration Relationships B-9
Configuration Relationship Tables The tables in this section explain relationships among and within the various configuration files illustrated in the previous section. The values for all variables listed in any one table must correspond to one another. The line number given with the location of each statement variable refers to line numbers within the previous sample configurations.
Application Group Definition Relations
The UniAccess System servers (UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, and UniAccess ODBC Server for DMS 2200) require the use of application groups. Application group definitions must be configured in the UniAccess Configuration File and must match OS 2200 definitions. The VALTAB application group information for UniAccess System server transactions must match UniAccess and OS 2200 definitions.
Application Group Number
Statement Variable Location
APPINF APPNUM UniAccess Configuration—Site Information File, line 11 COMSRV APPNUM UniAccess Configuration—Site Information File, line 28 APNUMBER MCB Configuration, line 2 AUD TIP - VALTAB Configuration, lines 2 and 10 APPL-GROUP-NUMBER UDS DSR Configuration, line 2 STEPCONTROL EXEC Configuration, lines 1, 2, and 3, 1st parameter
Application Group Name
Statement Variable Location
APPINF APPNAME UniAccess Configuration—Site Information File, line 12 APNAME MCB Configuration, line 1 APPL-NAME UDS DSR Configuration, line 1 APPLICATION NAME EXEC Configuration, line 1, 2nd parameter
Release 10R3: October 31, 2005 B-10 UniAccess for OS 2200 System Administration Guide
MCB BDI
Statement Variable Location
APPINF MCBBDI UniAccess Configuration—Site Information File, line 13 MCBBDI MCB Configuration, line 6 MCB-MSG-BANK-BDI UDS DSR Configuration, line 3
UDS BDI
Statement Variable Location
APPINF UDSBDI UniAccess Configuration—Site Information File, line 15 appl bank for UDS$TCLCDICR UDS Control—System Generation Files, line 6
Internationalization Relations
The locale internationalization definition must have a matching character set definition.
Statement Variable Location
CHARSET NAME UniAccess Configuration—Site Information File line 20 LOCALE CHARSET UniAccess Configuration—Site Information File, line 45
TSAM Relations
Each UACS must have a TSAM process defined in CMS 1100.
Process Name
Statement Variable Location
COMSRV PROCNAM UniAccess Configuration—Site Information File, line 26 PROCESS CMS 1100 Configuration, line 1 UAUSER COMSRV UniAccess Configuration—Site Information File, lines 71 & 74
Release 10R3: October 31, 2005 Configuration Relationships B-11
Process Password
Statement Variable Location
COMSRV PROCPSWD UniAccess Configuration—Site Information File, line 27 PASSWORD CMS 1100 Configuration, line 2
Activity Relations
The total number of tasks configured for all UACSs in a single application group must be less than the MCB SLT$NUM parameter.
Statement Variable Location
COMSRV TIPQCNT UniAccess Configuration—Site Information File, line 37 COMSRV TSAMCNT UniAccess Configuration—Site Information File, line 38 SLT$NUM MCB Configuration, line 5
Session Relations
If TIP session control is active (that is, the number of concurrent sessions in the EXEC Configuration is greater than 0), the OSPARM SESSCTRL parameter must be set to YES.
Statement Variable Location
OSPARM SESSCTRL UniAccess Configuration—Site Information File, line 51 NUMBER OF CONCURRENT EXEC Configuration, line 2, 2nd parameter SESSIONS
UniAccess Service Relations
If a UniAccess language service (UARS or UAHS) is used, the VALTAB information of the language service must match UniAccess Configuration information. If UARS or UAHS is initiated via an RPC, RPC to VALTAB mapping can be used to standardize RPC initiation conventions.
Release 10R3: October 31, 2005 B-12 UniAccess for OS 2200 System Administration Guide
Relational Service VALTAB Name
Statement Variable Location
COMSRV UARSTRAN UniAccess Configuration—Site Information File, line 33 ACT TIP - VALTAB Configuration, line 1
Hierarchical Service VALTAB Name
Statement Variable Location
COMSRV UAHSTRAN UniAccess Configuration—Site Information File, line 32 ACT TIP - VALTAB Configuration, line 9
RPC to VALTAB Mappings
The %%UACP, %%UARS, and %%UAHS RPCMAP TRANCODE parameters (UniAccess Configuration—UA Information File, lines 12, 23, and 25) are special parameters recognized by the UniAccess Communication Server as components of UniAccess language service transactions. UACS uses the COMSRV DFLTTRAN parameter as the VALTAB for RPCs with these unique RPCMAP TRANCODEs.
Statement Variable Location
COMSRV UARSTRAN UniAccess Configuration—Site Information File, line 33 COMSRV UAHSTRAN UniAccess Configuration—Site Information File, line 32 RPCMAP TRANCODE UniAccess Configuration—UA Information File, lines 12, 23, and 27
Application Group
Statement Variable Location
COMSRV APPNUM UniAccess Configuration—Site Information File, line 28 AUD TIP - VALTAB Configuration, lines 2 and 10
Release 10R3: October 31, 2005 Configuration Relationships B-13
Network Address Relations
Network addresses consisting of Internet addresses and ports must be configured on both client and server platforms.
UniAccess Transaction Server and ODBC Server Internet Addresses
Statement Variable Location
INTERNET-ADR CMS 1100 Configuration, line 5 ------Sybase SQL Server UNIX Configuration, Host File Configuration, line 1 ------This value, or a name associated with this value, is used in the IP Address/Host Name box (on the General tab) of the UADriver Setup dialog
UniAccess Transaction Server and ODBC Server Ports
Statement Variable Location
COMSRV LISTENPRT UniAccess Configuration—Site Information File, line 34 ------Sybase SQL Server UNIX Configuration, Interfaces File Configuration, line 2 ------This value is used in the Port box (on the General tab) of the UADriver Setup dialog
UniAccess Transaction Client Internet Addresses
Statement Variable Location
SERVER ADDR UniAccess Configuration—Site Information File, line 61 ------Sybase SQL Server UNIX Configuration, Host File Configuration, line 2 ------Microsoft SQL Server, the port assigned to the system where SQL Server is running.
Release 10R3: October 31, 2005 B-14 UniAccess for OS 2200 System Administration Guide
UniAccess Transaction Client Port
Statement Variable Location
SERVER PORT UniAccess Configuration—Site Information File, line 62 ------Sybase SQL Server UNIX Configuration, Interfaces File Configuration, line 4 ------Microsoft SQL Server, the port assigned to the system where SQL Server is running.
PID Definition Relations
PIDs allocated to UACS must be configured within the range set up by OS 2200 configurations. The MCB Configuration P$ID defines the range of PIDs in use by a particular MCB. The UniAccess Configuration defines the set of PIDs (the beginning PID and the total number of PIDs) that the UniAccess System will use. When TIP session control is active, the number of PIDs allocated to UACS must be less than or equal to the number of concurrent sessions defined in the EXEC Configuration.
Statement Variable Location
COMSRV PIDSTART UniAccess Configuration—Site Information File, line 35 COMSRV PIDCNT UniAccess Configuration—Site Information File, line 36 P$ID MCB Configuration, line 8 NUMBER OF CONCURRENT EXEC Configuration, line 2, 2nd parameter SESSIONS
Message Definition Relations
Message text information is maintained in the UAMESG statement, and details about the messages are maintained in the UAMMAP statement.
Statement Variable Location
UAMMAP MAPCODE UniAccess Configuration—UA Information File, line 58 UAMESG CODE UniAccess Configuration—UA Information File, line 34
Release 10R3: October 31, 2005 Configuration Relationships B-15
User Definition Relations
All UniAccess Transaction Client users must be configured. All users of a UniAccess System Server (Transaction Server and ODBC Servers) must be configured if the COMSRV USEUAUSER (UniAccess Configuration, line 29) statement variable is set to YES. A SIMAN-created userid must be created for users of a UniAccess System server when TIP session control is active.
UACL User Definitions
Statement Variable Location
UAUSER COMSRV UniAccess Configuration—Site Information File, lines 71 and 74 COMSRV PROCNAM UniAccess Configuration—Site Information File, line 26 PROCESS CMS 1100 Configuration, line 1
UASL/UARS/UAHS User Definitions
The RUN_MODE for each user must include TIP.
Statement Variable Location
UAUSER USERID UniAccess Configuration—Site Information File, line 72 USERID SIMAN Configuration, line 1 (also lines 2-19)
Release 10R3: October 31, 2005 B-16 UniAccess for OS 2200 System Administration Guide
UniAccess CPComm Configurations When CPComm is used to provide TCP/IP support on the 2200 Series, CPComm controls the connection between the host channel and LAN. UACS can access the network directly via CPComm or indirectly using CMS 1100 and CPComm.
If UACS will directly access CPComm, the following CPComm configuration would allow the process UACS to communicate via the IP address 192.61.252.45.
CPComm Configuration
PROCESS,UACS PASSWORD,C74A07 ip,ip-3 ip-info,ipinfoF ; ip-address,192.61.252.45 ; link,fet10
If UACS will access the network indirectly using both CMS 1100 and CPComm, the CMS PROCESS statement must point to CPComm.
CMS 1100 Configuration
PROCESS,UACS TYPEP,TSAM.CPCOMM ; PASSWORD,C74A07 ; INTERNET-ADR,IPA1 INTERNET-ADR,IPA1 IP,IP1,192.61.252.44 ;
CPComm Configuration
PROCESS,UACS PASSWORD,C74A07 IP,IP-3 IP-INFO,IPINFOF ; IP-ADDRESS,192.61.252.45 ; LINK,FET10
In this configuration, the IP address from line 2 of the CPComm configuration will be used and not the IP address in the CMS configuration file.
Note that if the CPComm IP configuration explicitly assigns the UACS process name to one or more IP address, the UACS process name must also be explicitly assigned in the CPComm configuration to a LOOPBACK LINK with the IP address of 127.0.0.1. For example:
Release 10R3: October 31, 2005 Configuration Relationships B-17
CPComm Configuration
PROCESS,UACS PASSWORD,C74A07 IP,IP-3 IP-INFO,IPINFOF ; IP-ADDRESS,192.61.252.45,UACS ; LINK,FET10 IP,INTERNAL LINK,LOOPBACK ; IP-ADDRESS,127.0.0.1,UACS
UniAccess DCP Configurations When DCP is used to provide TCP/IP support on the 2200 Series, the connection between the host channel and the DCP is represented as a separate LAN (see Figure B-2). The total DCP configuration is beyond the scope of installing UniAccess; however, the following guidelines will be helpful.
If the DCP is configured as a communications front-end and as a router with no TCP/IP traffic to the 2200, you will need to modify both the CMS and TELCON configurations to support host based TCP/IP.
• The IP address on the DCP used for the host LAN must use a different subnet address than the IP address used for the LAN. That is, the address must differ in the first three fields.
• The TELCON configuration for the DCP must contain IPADR and SUBNET statements for the host channel interface.
• The TELCON configuration SUBNET statement for the LAN must specify RIP=(YES...) to allow the DCP to act as a bridge.
Release 10R3: October 31, 2005 B-18 UniAccess for OS 2200 System Administration Guide
Windows DOS Open Client Open Client
UNIX host
LAN DCP OS 2200 Host
12 12
12 12
12345 789
Figure B-2: Sample Configuration for DCP
Release 10R3: October 31, 2005 C Sample Programs C UniAccess Sample Programs
This appendix describes the components of the UniAccess Sample System, including the RDMS and SQL sample databases. It explains how to set up the sample programs for each UniAccess product.
Topics Page
Sample System Overview C-2 UniAccess Sample Databases C-4 Functional View of the Sample Database C-4 Logical View of the Sample Database C-5 Physical View of the UASAMPLE RDMS 2200 C-6 Database Physical View of the uasample SQL Server C-7 Database Constraints, Triggers, and Views C-8 SQL Server Stored Procedures C-9 UniAccess Sample Programs C-10 UniAccess Transaction Server Programs C-10 UniAccess Transaction Client Programs C-12 UniAccess PC Client Programs C-16 Setting up the Sample System C-16 RDMS 2200 Database Setup C-17 SQL Server Database Setup C-18 UniAccess Transaction Server Sample Setup C-19 UniAccess Transaction Client Sample Setup C-22 PC Client Sample Setup C-23 Additional Sample Setup Information C-23
Release 10R3: October 31, 2005 C-2 UniAccess for OS 2200 System Administration Guide
Sample System Overview The sample programs provided with UniAccess are modular and flexible, allowing them to operate in a variety of client/server environments. The sample servers provided are UniAccess Transaction Server (UATS) and SQL Server. The sample clients provided are UniAccess Transaction Client (UATC), PC Client, and SQL Server.
The sample system has the following components, discussed in this appendix and illustrated in Figure C-1.
• RDMS 2200 UASAMPLE Database. The sample database accessed by the sample UATS programs.
• SQL Server uasample Database. The sample database accessed by the sample UATC and PC Client programs.
• SQL Server Stored Procedures. The stored procedures used in conjunction with the sample UATC and PC Client programs.
• UATS Samples. UniAccess Server-Library programs that work with the sample UATC and PC Client programs.
• UATC Samples. UniAccess Client-Library programs that work with the sample UATS programs and sample SQL Server stored procedures.
• PC Client Samples. PC Client programs that work with the sample UATS programs and sample SQL Server stored procedures.
Release 10R3: October 31, 2005 UniAccess Sample Programs C-3
SQL Server Platform Workstation SQL Server UASAMPLE Database PC Client SQL Server Samples Stored Procedures
UATS UATC Samples Samples
RDMS 2200 UASAMPLE Database
OS 2200 Host
Figure C-1: Components of the UniAccess Sample System
Figure C-1 illustrates the modularity of the sample programs. The UATC samples, the PC Client samples and SQL Server stored procedure samples can all function as client applications. They can issue requests to UATS or to SQL Servers.
Release 10R3: October 31, 2005 C-4 UniAccess for OS 2200 System Administration Guide
UniAccess Sample Databases The UniAccess Sample System provides two sample databases: the UASAMPLE database for RDMS 2200 and the uasample database for SQL Server. Both databases are functionally equivalent.
Functional View of the Sample Database
The following high-level, functional view of the sample system database applies to both the RDMS 2200 and SQL Server versions.
Table C-1: Functional View of the Sample Database
Table Name Column Name Description
employee employee_id employee identification number first_name first name last_name last name password password birth_date date of birth job_code job code number salary annual salary start_time work start time shift_rotation shift rotation date and time withhold_401k 401K withholding percentage withhold_state state/province withholding percentage withhold_local local government withholding percentage job_description job_code job code number category_code job category code salaried salaried indicator hourly hourly indicator min_salary minimum salary max_salary maximum salary description job description job_category category_code job category code description category description employee_review employee_id employee identification number review text employee performance review
Release 10R3: October 31, 2005 UniAccess Sample Programs C-5
Logical View of the Sample Database
Table C-2 demonstrates the relationship among the employee, job_description, and job_category tables. The shaded cells in the table indicate primary keys.
This high-level, logical view of the sample system database applies to both the RDMS 2200 and SQL Server versions.
Table C-2: Logical View of the Sample Database employee job_description job_category
job_code job_code category_code category_code employee_id job_code category_code N 1 N 1 first_name category_code description last_name salaried password hourly birth_date min_salary job_code max_salary salary description start_time shift_rotation withhold_401k withhold_state withhold_local
employee_review employee job_description employee_id employee_id employee_id employee_id job_code job_code job_code 1 1 N 1 review_text first_name category_code last_name salaried as above as above
Release 10R3: October 31, 2005 C-6 UniAccess for OS 2200 System Administration Guide
Physical View of the UASAMPLE RDMS 2200 Database
Table C-3 describes the physical implementation of the UASAMPLE database for RDMS 2200.
Table C-3: Physical View of the UASAMPLE RDMS 2200 Database
Table Name Column Name Datatype Characteristics
employee employee_id integer not null, primary key first_name character(30) not null last_name character(30) not null password character(30) birth_date date not null job_code smallint not null salary numeric(8,2) not null start_time time shift_rotation timestamp withhold_401k real withhold_state float not null withhold_local double not null job_description job_code smallint not null, primary key category_code smallint not null salaried character(1) not null hourly character(1) not null min_salary decimal(8,2) not null max_salary decimal8,2) not null description character(255) job_category category_code smallint not null, primary key description character(30) employee_review employee_id integer not null, primary key review_text character (1920)
Release 10R3: October 31, 2005 UniAccess Sample Programs C-7
Physical View of the uasample SQL Server Database
Table C-4 describes the physical implementation of the uasample database for SQL Server.
Table C-4: Physical View of the uasample SQL Server Database
Table Name Column Name Datatype Characteristics
employee employee_id int not null, primary key first_name char(30) not null last_name char(30) not null password binary(30) null birth_date smalldatetime not null job_code smallint not null salary money not null start_time datetime null shift_rotation datetime null withhold_401k real null withhold_state float not null withhold_local double precision not null job_description job_code smallint not null, primary key category_code tinyint not null salaried bit not null hourly bit not null min_salary smallmoney not null max_salary smallmoney not null description varchar(255) job_category category_code tinyint not null, primary key description char(30) employee_review employee_id integer not null, primary key review_text text
Release 10R3: October 31, 2005 C-8 UniAccess for OS 2200 System Administration Guide
Constraints, Triggers, and Views
Foreign Key Constraints
The following foreign key constraints apply to both the RDMS 2200 and SQL Server sample databases.
Table Foreign Key Primary Key Table
job_description category_code job_category employee job_code job_description employee_review employee_id employee
Check Constraint
The following check constraints apply to both the RDMS 2200 and SQL Server sample databases.
check (job_category.category_code > 0 and job_category.category_code < 100)
Trigger
This trigger is created for the SQL Server database only. The integrity of this trigger is maintained in the RDMS 2200 database by the Server-Library transactions.
create trigger salary_check on employee for insert as if (select count(*) from job_description, inserted where job_description.job_code = inserted.job_code and (job_description.min_salary > inserted.salary or job_description.max_salary < inserted.salary)) > 0 begin rollback transaction print "Salary outside job description range." end go
Release 10R3: October 31, 2005 UniAccess Sample Programs C-9
View
The following view applies to both the RDMS 2200 and SQL Server sample databases.
create view employee_job_description ( employee_id, first_name, last_name, cat_description, job_description ) as select employee_id, first_name, last_name, job_category.description, job_description.description from employee, job_description, job_category where employee.job_code = job_description.job_code and job_description.category_code = job_category.category_code
SQL Server Stored Procedures
The following stored procedures apply to the SQL Server sample database. They are created in the SSRVBLD/SQL script.
Table C-5: UniAccess Stored Procedures for SQL Server
Procedure Name Description
get_employee The get_employee stored procedure accepts @first_name and @last_name as input parameters and @row_count as an output parameter. It returns one or more employee records as a result set based upon the received @first_name and @last_name parameters.
It also updates the @row_count parameter with the number of rows in the database. get_description The get_description stored procedure accepts @category_code as an input parameter. It returns one job description record based upon the received job code parameter and one category record based upon the category code of the retrieved job description record. store_employee The store_employee stored procedure accepts all employee table columns as input parameters. It stores an employee record in the employee table using the received parameters.
Release 10R3: October 31, 2005 C-10 UniAccess for OS 2200 System Administration Guide
UniAccess Sample Programs This section summarizes the sample programs provided with the UniAccess System for OS 2200. Note that client programs that send RPC calls have corresponding server programs. The language-processing programs do not have corresponding names because a single language transaction handles all language requests for a server.
UniAccess Transaction Server Programs
The UniAccess Transaction Server package includes five Server-Library programs. The SERV1, SERV2, SERV3, and SERV5 programs process RPCs; the SERVL program processes a language request. Table A-1 provides the file names for each server sample program, the mapped RPC name, the name of the corresponding client program, and the element where the server source program resides. A description of each program follows.
Table C-6: UniAccess Server-Library Samples
UniAccess Server Mapped RPC UniAccess Client UniAccess Server Program Name Program Element
SERV1 get_employee CLNT1 SERV1/UCOB, SERV1/C, SERV1/ACOB SERV2 get_description CLNT2 SERV2/UCOB, SERV2/C
SERV3 store_employee CLNT3 SERV3/UCOB SERV5 get_emp_review CLNT5 SERV5/UCOB SERVL n/a n/a SERVL/UCOB
SERV1 SERV1 accepts @first_name and @last_name as input parameters and @row_count as an output parameter. It returns one or more employee records as a result set based upon the received @first_name and @last_name parameters. It also updates the @row_count parameter with the number of rows in the database. In addition to demonstrating a variety of Server-Library programming techniques and a wide variety of Server- Library functions, this program demonstrates the following concepts: • processing server RPCs
Release 10R3: October 31, 2005 UniAccess Sample Programs C-11
• processing input parameters • processing output parameters • returning 1 result set consisting of a variety of datatypes • processing errors.
SERV2 SERV2 accepts @category_code as an input parameter. It returns one category description record based upon the received @category_code parameter and all job description records with that category code. In addition to being an example of efficient Server-Library program design using a minimum number of Server-Library calls, this program demonstrates the following concepts: • processing server RPCs • processing input parameters • returning 2 result sets consisting of a variety of datatypes • processing errors.
SERV3 SERV3 accepts all employee table columns as input parameters and an extended session parameter. It checks to ensure that the specified salary is within the range of the corresponding job_description.min_salary and job_description.max_salary fields. It stores an employee record in the employee table using the received parameters.
SERV3 accepts 12 or 13 parameters. If 12 parameters are passed to SERV3, it always operates in non-extended session mode. The 13th parameter (EXT-SESSION-PARM) is the extended session control parameter. When it is passed to SERV3, it determines whether or not SERV3 operates in extended session mode. If the parameter is ‘y’ or ‘Y’, the transaction is placed in extended session mode. All other values of EXT-SESSION-PARM cause SERV3 to exit extended session mode (if it is in that mode) and to terminate when the input parameters have been processed and a response sent to the client.
The program demonstrates the following concepts: • processing server RPCs • processing input parameters of a variety of datatypes
Release 10R3: October 31, 2005 C-12 UniAccess for OS 2200 System Administration Guide
• processing extended session requests • participating in a distributed transaction • processing errors.
SERV5 SERV5 accepts @empid as an input parameter. It returns one employee review (or ALL) description record(s) based upon the received @empid parameter. In addition to being an example of efficient Server-Library program design using a minimum number of Server-Library calls, this program demonstrates the following concepts: • processing server RPCs • processing input parameters • returning one result set consisting of a variety of datatypes, particularly the DTS-TEXT datatype • processing errors.
SERVL SERVL accepts an incoming language request. It analyzes and responds to the language request. The program demonstrates the following concepts: • processing server language requests • processing return messages • processing errors.
UniAccess Transaction Client Programs
The UniAccess Transaction Client package includes seven Client-Library programs. CLNT1, CLNT2, and CLNT3 programs send RPCs to a OS 2200 server or Sybase SQL Server; CLNT1SS and CLNT2SS programs process language requests that invoke stored procedures on SQL Server; CLNT4 sends a language request to a OS 2200 server, Microsoft SQL Server or Sybase SQL Server; CLNT5 sends an RPC to a OS 2200 server. Table A-1 provides the file names for each client sample program, the name of the corresponding server program, the stored procedure name, and the element where the client source program resides. A description of each program follows.
Release 10R3: October 31, 2005 UniAccess Sample Programs C-13
Table C-7: UniAccess Client-Library Samples
Microsoft SQL Sybase SQL UniAccess UniAccess UniAccess Server Stored Server Stored Client Program Server Program Client Element Procedure Procedure
CLNT1 SERV1 n/a get_employee CLNT1/UCOB (get_employee) CLNT1/C
CLNT1SS n/a get_employee n/a CLNT1SS/UCOB CLNT2 SERV2 n/a get_description CLNT2/UCOB (get_description)
CLNT2SS n/a get_description n/a CLNT2SS/UCOB CLNT3 SERV3 n/a store_employee CLNT3/UCOB (store_employee) CLNT4 UARS n/a n/a CLNT4/UCOB (language request) (language request) (language request) CLNT5 SERV5 n/a n/a CLNT5/UCOB (get_emp_review)
CLNT1 CLNT1 prompts the user for @first_name and @last_name. It calls a remote procedure named get_employee with the user-specified fields as input parameters and a program-defined field as an output parameter. It displays the row results and the return parameter value. In addition to being an example of efficient Client-Library program design, this program demonstrates the following concepts: • issuing RPCs • processing input parameters • processing output parameters • retrieving 1 result set consisting of a variety of datatypes • processing errors.
Release 10R3: October 31, 2005 C-14 UniAccess for OS 2200 System Administration Guide
CLNT1SS CLNT1SS prompts the user for @first_name and @last_name. It calls a language request to invoke the get_employee stored procedure on Microsoft SQL Server with the user-specified fields as input parameters and a program-defined field as an output parameter. It displays the row results and the return parameter value. In addition to being an example of efficient Client-Library program design, this program demonstrates the following concepts: • issuing a language request that invokes a stored procedure. • processing input parameters • processing output parameters • retrieving 1 result set consisting of a variety of datatypes • processing errors.
CLNT2 CLNT2 prompts the user for @category_code. It calls a remote procedure named get_description with a user-specified field as an input parameter. It displays the two row result sets. In addition to demonstrating a variety of Client-Library programming techniques, this program demonstrates the following concepts: • issuing RPCs • processing input parameters • retrieving 2 result sets consisting of a variety of datatypes • processing errors.
CLNT2SS CLNT2SS prompts the user for @category_code. It calls a language request to invoke the get_description stored procedure on Microsoft SQL Server with a user-specified field as an input parameter. It displays the two row result sets. In addition to demonstrating a variety of Client-Library programming techniques, this program demonstrates the following concepts: • issuing a language request that invokes a stored procedure • processing input parameters • retrieving 2 result sets consisting of a variety of datatypes • processing errors.
Release 10R3: October 31, 2005 UniAccess Sample Programs C-15
CLNT3 CLNT3 prompts the user for all employee columns and for an extended session flag. It calls a remote procedure named store_employee with the user-specified parameters. It displays the status result. If the extended session flay is ‘y’ or ‘Y’, the server transaction will process multiple CLNT3 inputs as a single TIP transaction. CLNT3 demonstrates the following concepts: • processing client RPCs • processing input parameters of a variety of datatypes • extended session use by a client application • processing errors.
CLNT4 CLNT4 sends a hardcoded language request to the language transaction requesting all records from the employee_job_description view. It displays the row result set. It demonstrates the following concepts: • issuing language requests • retrieving 1 result set consisting of a variety of datatypes • processing errors.
CLNT5 CLNT5 prompts the user for either @employee_id or ALL. It calls a remote procedure named get_emp_review with the user-specified field as input parameters and a program-defined field as an output parameter. It displays the row results and the return parameter value. In addition to being an example of efficient Client-Library program design, this program demonstrates the following concepts: • issuing RPCs • processing input parameters • processing output parameters, particularly TDS-TEXT data. • retrieving 1 result set consisting of a variety of datatypes • processing errors.
Release 10R3: October 31, 2005 C-16 UniAccess for OS 2200 System Administration Guide
UniAccess PC Client Programs
The PC Client examples provide client programs designed to work with the UniAccess sample system. The welcome.htm document included with the samples explains how they work, as well as the environmental requirements. These samples are designed to work with both the OS 2200 and SQL Server environments.
Setting up the Sample System To set up the sample system, you must create the sample database and then build and install the client and server applications. Scripts to create all the components of the sample system are included with each product package. However, UniAccess Transaction Server must be installed in order to compile and run the UATS examples, and UniAccess Transaction Client must be installed in order to compile and run the UATC examples. The PC Client samples require either the UniAccess Transaction Server or the UniAccess ODBC Server for RDMS 2200. Table C-8 indicates which components should be set up for each UniAccess product package.
Table C-8: Sample System Components for UniAccess Product Packages
UATS UATC UATS & UARS Component only only UATC
RDMS 2200 database yes no yes yes SQL Server database optional yes optional no UATS sample programs yes no yes no UATC sample programs no yes yes no PC Client sample programs* yes no yes yes sample user definition yes yes yes yes sample remote server definition optional no optional optional * The PC Client samples are provided on the UniAccess 10R3 PC Client CD. Information about these samples can be found in the welcome.htm document installed with the samples.
Release 10R3: October 31, 2005 UniAccess Sample Programs C-17
The sections that follow explain the procedures for setting up each of the components listed above. All sample scripts described in the setup sections are located in the OS 2200 file SYS$LIB$*UASAMP (or SYS$LIB$*UASAMPT for test mode installations). Some of these scripts can be down-loaded to a Windows workstation and executed from there.
RDMS 2200 Database Setup
The elements RDMSBLD/SQL, RDMSDRP/SQL and RDMSDRP/URP contain commands to create and drop the RDMS 2200 version of the UASAMPLE database. To run the scripts from Windows, they must be downloaded to a Windows workstation. The following sections provide information for a variety of installation options as well as instructions for removing the UASAMPLE database.
Creating the RDMS Database from Microsoft Windows
The RDMSBLD/SQL script can be used from an ODBC client to create the RDMS 2200 UASAMPLE database. The following steps illustrate creating the RDMS UASAMPLE database using the Microsoft ODBC Test program.
• Modify the ##USERID## token to a valid OS 2200 userid. This should be the same userid that is used to connect to UACS from ODBC Test.
• Connect to the appropriate data source.
• Retrieve the RDMSBLD/SQL script from the File/Open menu item.
• Execute the script in its entirety using the SQL EXECUTE statement.
• Retrieve the empreview1.sql script from the File/Open menu item.
• Execute the script in its entirety using the SQL EXECUTE statement.
• Retrieve the empreview2.sql script from the File/Open menu item.
• Execute the script in its entirety using the SQL EXECUTE statement.
Release 10R3: October 31, 2005 C-18 UniAccess for OS 2200 System Administration Guide
Creating the RDMS Database from OS 2200
From an OS 2200 demand session, the RDMSBLD/SQL runstream can be used as input to the RSAC-COIVP processor. (RDMSSQL/ADD is provided as a skeleton run to add this runstream, if desired.). The ##USERID## token should be modified to a valid OS 2200 userid. It should match the demand userid for the current session.
Note In order to populate the employee_review table, the empreview.sql script must be executed from Microsoft Windows (see previous section for instructions).
Deleting the RDMS Database
The RDMSDRP/SQL script provides SQL commands that will delete all tables and views from the UASAMPLE database. After the tables and views have been deleted, you can delete the schema and all storage areas using the UREP commands provided in the RDMSDRP/UREP script. (RDMSSQL/ADD is provided as a skeleton run to add this runstream, if desired.)
SQL Server Database Setup
The SSRVBLD/SQL element contains SQL commands to create the SQL Server version of the uasample database. It also contains commands to create the get_employee, get_description, and store_employee stored procedures. To run the script from Windows, it must be downloaded to a Windows workstation. The following sections provide information for a variety of installation options.
Creating the SQL Server Database from Microsoft Windows
The steps required to create the database from Windows are outlined below. The userid you use to connect to a SQL Server should permit the ability to create databases. The SSRVBLD/SQL script can be used from an ODBC client to create the SQL Server uasample database. The following steps illustrate creating the SQL Server uasample database using the Microsoft ODBC Test program.
• Connect to the appropriate data source using the ODBC Test.
Release 10R3: October 31, 2005 UniAccess Sample Programs C-19
• Retrieve the SSRVBLD/SQL script from the File/Open menu item.
• Execute the script in its entirety using the SQL EXECUTE statement.
Creating the SQL Server Database from OS 2200
From an OS 2200 demand session, you can use the SSRVBLD/SQL script as input to the ISQL processor provided with UniAccess Transaction Client. The userid you use to connect to SQL Server should permit the ability to create databases. See Chapter 13 for the details about ISQL input file specification.
Deleting the SQL Server Database
Use the Transact-SQL command DROP DATABASE to delete the uasample database from SQL Server.
UniAccess Transaction Server Sample Setup
Setting up the UATS RPC Transactions
The UATS sample programs are Server-Library transactions. To set up the sample Server- Library transactions, perform the following steps:
• Obtain TIP program numbers for each Server-Library program (SERV1, SERV2, SERV3, and SERV5).
• Edit the UASLSAMPLE/VALTABS script, replacing the # fields with site- specific information. The UASLSAMPLE/VALTABS script creates a VALTAB for each of the programs.
• Add this runstream.
• Select the appropriate Server-Library runstreams for your environment. The UniAccess Server-Library sample runstreams contain the source program, the ECL to compile and link each program, and the syntax that copies the absolute into the SUPUR file. As depicted in the following table, SERV1 provides sample syntax in USC COBOL, UCS C, and ASCII COBOL. Sample syntax for SERV2 is provided in UCS COBOL and UCS C. SERV3 and SERV5 syntax is provided in UCS COBOL.
Release 10R3: October 31, 2005 C-20 UniAccess for OS 2200 System Administration Guide
Program UCS COBOL UCS C ASCII COBOL Name Source Runstream Source Runstream Source Runstream
SERV1 SERV1/UCOB UASLSAMPLE/C and SERV1/ACOB SERV1/C* SERV2 SERV2/UCOB UASLSAMPLE/C and SERV2/C* SERV3 SERV2/UCOB SERV5 SERV5/UCOB * SERV1/C and UASLSAMPLE/C work together. SERV2/C and UASLSAMPLE/C work together.
• Edit the sample runstream selected, modifying all occurrences of the tokens ##AGNAME##, ##AGNUMBER##, and ##SUPURNUMBER## to the appropriate values for the application group name, application group number, and SUPUR file number.
• Add these runstreams.
• After the programs have been successfully created and installed, you must map the program names to more descriptive RPC names. Insert the following RPCMAP statements in the UniAccess Configuration File. (See page 16-60 for a description of the RPCMAP statement.)
RPCMAP RPCNAME,get_employee ;. get_employee RPC map TRANCODE,SERV1 RPCMAP RPCNAME,get_description ;. get_description RPC map TRANCODE,SERV2 RPCMAP RPCNAME,store_employee ;. store_employee RPC map TRANCODE,SERV3 RPCMAP RPCNAME,get_emp_review ; . get_emp_review RPC map TRANCODE,SERV5
• Re-load the UADT with the updated parameters using the UACF processor. (See page 17-2 for the execution syntax of the UACF processor.)
Release 10R3: October 31, 2005 UniAccess Sample Programs C-21
Note Some client environments require the UNIACCESS1S1.SQL_PROCEDURES and UNIACCESS1S1.SPT_PROCEDURE_COLUMNS tables to be populated with UATS RPC transaction definitions. Microsoft Visual Basic applications using the RDO interface and PowerBuilder programs are two client products with this requirement. See the Appendix E for details on how to populate these tables.
Setting up the UATS Language Transaction
In the UniAccess System, language requests are processed by a single transaction, defined by UACS to receive all language requests. This server transaction must either be provided by UARS, or be written by the user. Sample program SERVL is provided as an example of a program that services SQL language requests.
Perform the following steps to set up the sample language transaction:
• Set up a VALTAB for SERVL.
• Edit the runstream SERVL/UCOB modifying all occurrences of the tokens ##AGNAME##, ##AGNUMBER##, and ##SUPURNUMBER## to the appropriate values for the application group name, application group number, and SUPUR file number.
• Add this runstream.
• After SERVL has been successfully created and installed, add the USERTRAN PARAMETER to the COMSRV statement in the UniAccess Configuration File. In addition, you may want to change the default language transaction. The DFLTTRAN parameter of the COMSRV statement specifies the default language transaction. (See page 16-21 for a description of the DFLTTRAN parameter. See page 16-32 for a description of the USERTRAN parameter.)
USERTRAN,SERVL ;
• Since this change affects the UACS configuration, the procedure for updating the UniAccess Configuration is as follows:
Release 10R3: October 31, 2005 C-22 UniAccess for OS 2200 System Administration Guide
— Terminate UACS (if active).
— Build the UniAccess Configuration File using the UACF processor. (See page 17-2 for the execution syntax of the UACF processor.)
— Restart UACS.
UniAccess Transaction Client Sample Setup
The UniAccess Client-Library sample runstreams contain the source program as well as the ECL to compile and link each program. As depicted in the following table, CLNT1 provides sample syntax in UCS COBOL and UCS C, while CLNT1SS, CLNT 2, CLNT2SS, CLNT3, CLNT4, CLNT5 provide sample syntax in UCS COBOL.
Program Name UCS COBOL UCS C Source Runstream Source Runstream
CLNT1 CLNT1/UCOB UACLSAMPLE/C CLNT1/C CLNT1SS CLNT1SS/UCOB n/a CLNT2 CLNT2/UCOB n/a CLNT2SS CLNT2SS/UCOB n/a CLNT3 CLNT3/UCOB n/a CLNT4 CLNT4/UCOB n/a CLNT5 CLNT5/UCOB n/a
To set up the sample Client-Library programs, perform the following steps:
• Select the appropriate runstreams for your environment and add them.
• After the Client-Library programs have been successfully created, configure the internet address, server name, and server port of the remote server to which the Client-Library programs will access. These configuration parameters are defined in the SERVER statement of the UniAccess Configuration File. The following syntax is an example of configuring a remote server. (See page 16-65 for a complete description of the SERVER statement.)
Release 10R3: October 31, 2005 UniAccess Sample Programs C-23
SERVER ADDR,192.152.80.3 ; NAME,SYBASE10 ; PORT,2025
• Re-load the UADT using the UACF processor. (See page 17-2 for the execution syntax of the UACF processor.)
PC Client Sample Setup
Refer to the welcome.htm document installed with the UniAccess UniAccess 10R3 PC Client CD for details on the PC Client samples setup.
Additional Sample Setup Information
User Definition
If UACS is configured to validate userids, all UniAccess System users must be configured in the UniAccess Configuration File. Each time a client request is received by UACS, the login information packaged with the request is validated against the list of UAUSER records maintained in UADT. Additionally, the following conditions should be met when defining users to UniAccess:
• If TIP session control is active, this userid must also be a valid OS 2200 userid.
• Any client connecting to UARS must have the UAUSER SCHEMA parameter set to UASAMPLE.
• All UniAccess Transaction Client users must have the UAUSER COMSRV configured. The following is an example of a UAUSER statement. (See page 16-78 for a complete description of the UAUSER statement.)
UAUSER USERID,uademo ; COMSRV,UACS ; SCHEMA,UASAMPLE
• After adding a UAUSER statement, UADT must be re-loaded using the UACF processor. (See page 17-2 for the execution syntax of the UACF processor.)
Release 10R3: October 31, 2005 C-24 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 D System Messages D UniAccess System Messages
This appendix explains UniAccess System messages types and lists all operational and server program messages.
Sections Page
Operational Messages D-2 UACS Trace File and Console Messages D-2 Security Event Log Messages D-38 UACF Warnings D-47 UAMM Error Messages D-50 UAIR Error Messages D-53 SCHEMADEF Error Messages D-56 TABLEDEF Error Messages D-60 Server Program Messages D-69 UAHS Error Messages D-88 Client Program Messages D-94 Server Messages returned by Client-Library D-94 Client Messages returned by Client-Library D-94
Release 10R3: October 31, 2005 D-2 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Overview of UniAccess System Messages The following types of messages, listed and described in this appendix, may be returned by components of the UniAccess System:
• Operational Messages (run-time messages generated by a UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, UniAccess ODBC Server for DMS 2200, or UniAccess Transaction Client processor, but not returned to a client application)
• Server Program Messages (messages generated by a UniAccess Transaction Server, UniAccess ODBC Server for RDMS 2200, or UniAccess ODBC Server for DMS 2200 component or by a Server-Library transaction, which are to be returned to a client application)
• Client Program Messages (messages generated by Client-Library applications).
Operational Messages Operational messages are run-time messages generated by a UniAccess System processor, but not returned to a client application. The UACS, UACF and UAMM processors are components of all UniAccess System product packages. The UAIR processor is used by UniAccess Transaction Server and UniAccess ODBC Server for RDMS 2200; the SCHEMADEF and TABLEDEF processors are used by UniAccess ODBC Server for DMS 2200.
UACS Trace File and Console Messages
Trace File Messages
Trace file messages have the following format:
timestamp [taskid] [msgcode] type msgtext
where:
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-3
timestamp is a timestamp string in the format of mm/dd/yy hh:mm:ss:hhh
taskid is the octal taskid value
msgcode is the message code listed below
type is the literal *ERROR*, *WARNING* or *INFORMATION*
msgtext is the message text listed below.
The amount of information written to the trace file is initially controlled by the trace level specified by the COMSRV TRCLEVEL parameter in the Source Configuration File. The trace level can be changed during run time with a UACS console keyin. When the trace level is HIGH, error, warning, and information messages are written to the trace file. When the trace level is MEDIUM, error and warning messages are written to the trace file. When the trace level is LOW, only error messages are written to the trace file. When the trace level of OFF, no messages are written to the trace file.
System Console Messages
System console messages have the following format:
msgtext [msgcode] type
where:
msgtext is the message text listed below
msgcode is the message code listed below
type is the literal *ERROR*, *WARNING* or *INFORMATION*.
Release 10R3: October 31, 2005 D-4 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Messages Conventions
This section contains a list of the messages generated by UACS, their description, and a resolution where necessary. The following fields are included for each message:
Type may be INFORMATION, WARNING or ERROR
Reason contains an explanation of the message and a description of variable fields returned
Action contains a resolution for WARNING and ERROR types
Location is the System Console and/or Trace File.
The variables listed below are used in message text:
%o fields are octal integer values %d fields are decimal integer values %x fields are hexidecimal integer values %s fields are character string values
1 Current UACS state [%s]. Type: INFORMATION Reason: UACS has changed states. This message is used by AIS during problem analysis. Action: N/A Location: Trace File
2 Error accessing trace file [%s], [%s], os error [%s]. Type: ERROR Reason: Opening a new UniAccess trace file cycle failed. The first %s is the name of the trace file that failed to open. The second %s is the error encountered by UACS if any. The third %s describes either a system error number (such as for file open failure) or a facility error number (such as a file assign failure) if available.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-5
Action: Assign a new cycle of the file manually to determine what OS 2200 limitation prohibited UACS from assigning the file. Location: System Console
3 Error accessing configuration file [%s], [%s], os error [%s]. Type: ERROR Reason: The UniAccess Configuration File specified on the UACS processor command line call could not be accessed. This could occur because the command line syntax was incorrect, the file could not be opened, or the specified file is not a valid UniAccess Configuration File. The first %s is the name of the Configuration File that failed to open. The second %s is the error encountered by UACS if any. The third %s describes either a system error number (such as for file open failure) or a facility error number (such as a file assign failure) if available. Action: Check the syntax of the command-line call on the UACS execution, and/or rebuild the Configuration File using the UACF processor. Location: System Console
4 UACS initialization complete. Type: INFORMATION Reason: UACS has successfully initialized and is ready to accept requests. Action: N/A Location: System Console, Trace File
5 Console keyin (CONS) error: [%s] [%o]. Type: ERROR, INFORMATION Reason: For an ERROR type, the console registration or message retrieval failed. The %s is the UACS process name that UACS used to register for console input. The %o is the return code from the KEYIN$ executive request. For an INFORMATION type, an invalid console command was received by UACS. The %s is the invalid command text. The %o is 0. Action: For ERROR types, examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 EXEC System Software Executive Requests Programming Reference. Location: System Console, Trace File
Release 10R3: October 31, 2005 D-6 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
6Trace level changed via CONS keyin [%s]. Type: WARNING Reason: The current trace level has been changed by a UACS console keyin to the level indicated by the %s field. Action:N/A Location: Trace File
7Bank allocation error [%s] [%o]. Type: ERROR Reason: During its initialization sequence, UACS failed to allocate a program-level data bank. The %s indicates the type of bank that was attempting to be created. The %o contains the error code returned from the service library storage management service. Action: Examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Service Library (SLIB) Programming Reference Manual. Location: System Console, Trace File
8Error retrieving command line parameter [%o]. Type ERROR Reason: UACS failed to retrieve command line parameters. The %o contains the error code returned from the service library internal format (INFOR) service. Action: Examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Service Library (SLIB) Programming Reference Manual. Location: System Console
9 TSAM function [%s] failed for PID [%d], status [%o]. Type: ERROR Reason: A CMS 1100 Transport Service Access Method (TSAM) or CPComm API call has failed. The %s is the name of the call that failed. The %d is the PID of the connection on which the error occurred or 0 if a PID has not yet been allocated. The %o is the return code from the TSAM call. Action: Examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Communications Management System (CMS 1100) Programming Reference Manual, or in the Unisys OS 2200 Cooperative Processing Communications Platform (CPComm) Programming Reference Manual. Location: System Console, Trace File
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-7
10 TSAM required level [%d] mismatches available level [%d]. Type: ERROR Reason: The requested TSAM interface level did not match the available TSAM interface level. The first %d is the requested interface level and the second %d is the available interface level. Action: Verify that the correct level of CMS 1100 is installed (see Chapter 3). Location: System Console, Trace File
11 CMS registration error [%d]. Type: ERROR Reason: UACS failed to register as an OS 2200 CMS. The %d contains the error code returned from the CMS$REG executive request. Action: Examine the error code returned in the %d field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual. Location: System Console, Trace File
12 PID assign/release error [%o]. Type: ERROR Reason: UACS failed to assign PIDs. The %o contains the error code returned from the RT$PID executive request. Action: Examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual. Location: System Console, Trace File
13 Task initialization error, tipq - [%o], tsam - [%o], mmq - [%o]. Type: ERROR Reason: UACS failed to successfully start all TIPQ, TSAM, and MMQ tasks. The %o fields are bit masks indicating the number of tasks that were successfully started. Action: Examine the trace file for other trace messages to determine the reason for the task initialization failure. Location: System Console, Trace File
14 Basic mode CMS call error [%s] [%o]. Type: ERROR Reason: A basic mode MCB/CMS call failed. The %s is the name of the call that failed. The %o contains the error code returned from the basic mode call.
Release 10R3: October 31, 2005 D-8 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Action: Examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in Appendix B of the Unisys OS 2200 Message Control Bank (MCB) Programming Reference Manual. Location: System Console, Trace File
. 15 Invalid UACS command line option specified. Type: ERROR Reason: An invalid command line option has been specified on the UACS processor call. Action: Review Chapter 17 for a description of the UACS processor execution syntax. Location: System Console
16 UACS shutdown complete. Type: INFORMATION Reason: UACS has terminated processing. Action: N/A Location: System Console
17 UACS shutdown failed... will abort. Type: ERROR Reason: UACS failed to terminate active TSAM and/or TIPQ tasks when attempting to terminate. Action: Examine the trace file for other trace messages to determine the reason for the task termination failure. Location: System Console
18 TIP$SM call [%s] failed [%o] affecting User = [%s], pid = [%d]. Type: ERROR Reason: A TIP session modification call failed. The first %s contains the type of request. The %o contains the status of the TIP$SM executive request. The second %s contains the userid of the affected connection. The %d contains the PID of the affected connection. Action: Examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual. Location: System Console, Trace File
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-9
19 Terminating with [%d] clients still active. Type: WARNING Reason: UACS is terminating with active connections. Action: Terminate all connections before shutting down UACS or give UACS additional time to terminate. Location: System Console, Trace File
20 Terminating a client connection [%s] [%d]. Type: WARNING Reason: UACS is terminating with active connections. The %s is the userid specified by the client application. The %d is the PID of the connection. Action: Terminate all connections before shutting down UACS or give UACS additional time to terminate. Location: Trace File
21 TSAM Task [%d] successfully initialized. Type: INFORMATION Reason: The TSAM task has successfully initialized. The %d indicates the task value. Action:N/A Location: Trace File
22 TSAM Task [%d] terminating. Type: INFORMATION Reason: The TSAM task has successfully terminated. The %d indicates the task value. Action: N/A Location: Trace File
23 Unsupported TDS version [%4s]. Type: ERROR Reason: An unsupported TDS level was received from a client application. The %s indicates the TDS level. Action: Use a TDS level that is supported by UACS. Location: Trace File
24 Client login received - Username = [%s], pid = [%d], mmid = [%d], IP-addr = [%s]. Type: INFORMATION
Release 10R3: October 31, 2005 D-10 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Reason: A client login was received by UACS. The first %s indicates the userid of the connection. The first %d is the PID allocated to the connection. The second %d is an internal structure allocated to this connection for AIS use. The second %s is the IP address associated with the computer logging into UniAccess. The IP address is in the format "x.x.x.x.", where each x is an integer between 1 and 225. Action:N/A Location: Trace File
25 Language request received - Language alias = [%s], pid = [%d]. Type: INFORMATION Reason: A language request has been received. The %s is the name of the language transaction used. The %d is the PID on which the request was received. Action: N/A Location: Trace File
26 RPC received - RPC name = [%s], pid = [%d]. Type: INFORMATION Reason: An RPC has been received. The %s is the name of the RPC. The %d is the PID on which the request was received. Action: N/A Location: Trace File
27 Client disconnect received - Username = [%s], pid = [%d]. Type: INFORMATION Reason: A client has disconnected. The %s is the userid of the client. The %d is the PID on which the request was received. Action: N/A Location: Trace File
28 Could not allocate a client structure. Type: ERROR Reason: UACS has no more connections available. Action: Allocate more PIDs to the current UACS or boot an additional UACS. Location: Trace File
29 MCB output received - Username = [%s], pid = [%d], [%s]. Type: ERROR
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-11
Reason: UACS received an MCB output message on the output routing queue. The first %s is the userid of the connection on which the request was received. The %d is the PID on which the request was received. The second %s contains the beginning portion of the message. Action: Examine the text of the message contained in the second %s to determine the transaction problem. Location: System Console
30 TIPQ Task [%d] successfully initialized. Type: INFORMATION Reason: The TSAM task has successfully initialized. The %d indicates the task value. Action: N/A Location: Trace File
31 PID [%d] not w/in range of valid PIDs [%d -> %d] for this UACS. Type: ERROR Reason: UACS received a transaction response from a PID that is not within the range of PIDs that UACS is prepared to service. The first %d is the PID received. The subsequent %d’s are the valid PID range. Action: Determine what transaction is generating results using an invalid PID and correct the transaction. Location: Trace File
32 TIP$TALK call [%s] failed [%o] affecting User = [%s] pid = [%d]. Type: ERROR Reason: TIP session establishment failed. The first %s contains the TIP$TALK executive request function being executed. The %o contains the error code returned from the TIP$TALK executive request. The %s is the userid for which the error occurred. The %d is the PID for which the error occurred. Action: Examine the error code returned in the %o field to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual. Location: Trace File
. 33 Unsupported queue item found on output routing queue [%s]. Type: WARNING Reason: UACS received an unsupported queue item on the output routing queue. The description of the item is contained in the %s field.
Release 10R3: October 31, 2005 D-12 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Action: N/A Location: Trace File
34 Unknown queue item found on output routing queue - function [%o]. Type: ERROR Reason: UACS received an unrecognized queue item on the output routing queue. The function code of the item is contained in the %o field. Action: Examine the function code returned in the %o field to determine the type of request UACS received. The function code is documented in the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual. Location: Trace File
35 TIPQ Task [%d] terminating. Type: INFORMATION Reason: The TIPQ task has successfully terminated. The %d indicates the task value. Action: N/A Location: Trace File
36 TSAM received a TCP resume for PID [%d]. Type: INFORMATION Reason: UACS received a TCP resume for the PID indicated by the %d field. Action: N/A Location: Trace File
37 Unknown event [%d] requested for Username = [%s], pid = [%d]. Type: ERROR Reason: UACS received an unsupported or unrecognized TDS request. The first %d is the TDS token value. The %s is the userid for which the request was received. The second %d is the PID for which the request was received. Action: Correct the application that is sending invalid or unsupported TDS tokens to UACS. Location: Trace File
38 Inconsistent request [%s], pid [%d], process state [%s], net state [%s]. Type: ERROR Reason: UACS has received an inappropriate request for the current state of a connection. The first %s describes the type of request received by UACS.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-13
The %d is the PID of the connection. The second %s is the connection process state. The last %s is the connection network state. Action: Ensure that the programs involved in the offending request are properly constructed and verify the integrity of the network. If the problem persists, contact AIS Technical Support. Location: Trace File
39 UACS shutdown in progress [%s] request for PID [%d] refused. Type: ERROR Reason: UACS received a request after the shutdown process was initiated. The %s indicates the type of request received. The %d is the PID of the connection on which the request was received. Action: Execute the request when a UACS is not shutting down. Location: Trace File
40 Application [%s] state notification received. Type: ERROR, WARNING Reason: UACS received an application group state modification notification on the output routing queue. This will occur when the application group that UACS is servicing is uped or downed. The %s describes the state that was received from the routing queue. Action: If UACS is servicing UASL requests, it must be shutdown and restarted when the application group is up and MCB is initialized. Location: Trace File
41 Signon procedure for Username = [%s] pid = [%d] failed. Prompt [%s]. Type: ERROR Reason: UACS failed to establish a TIP session for a user. This error typically occurs when a default answer to a TIP session manager prompt is not allowed. The first %s is the userid for which the session establishment attempt was made. The %d is the PID allocated to the connection. The last %s is the last prompt that the TIP session manager issued during the connection attempt. Action: Examine the userid and prompt fields to determine what sequence of prompts are being issued by the TIP session manager. Refer to Using UniAccess System Security Facilities in Chapter 9 for user definition criteria under TIP session control. Location: Trace File
Release 10R3: October 31, 2005 D-14 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
42 Signon failed. Illegal userid/passwd from Username = [%s], pid = [%d]. Type: ERROR Reason: UACS failed to establish a TIP session for a user. The userid and/or password specified were not valid for the OS 2200 host. The first %s is the userid for which the session establishment attempt was made. The %d is the PID allocated to the connection. Action: Use a valid OS 2200 userid and password. Location: Trace File
43 User = [%s] pid = [%d] recvd unsolicited msg = [%s]. Type: WARNING Reason: UACS received a TIP session manager message when one was not expected. The first %s is the userid for which the request was received. The %d is the PID allocated to this connection. The last %s is the text of the TIP session manager message. Action: If the message adversely affects session establishment for users, examine the message text to determine the source of the message. Location: Trace File
44 TIP Session Control has closed User = [%s] pid = [%d]. Type: WARNING, ERROR Reason: UACS received a TIP session manager termination notification. The %s is the name of the user for which the termination was received. The %d is the PID allocated to the connection. The session has been closed. Action: If the TIP session manager times out the connection too quickly, the time- out value should be increased using the OS 2200 SIMAN utility. If a LOGOFFTRAN is configured, the transaction has not been scheduled. Location: Trace File
45 Unknown TIP$SM function = [%o] received for User = [%s] pid [%d]. Type: ERROR Reason: UACS received an unrecognized function from the TIP session manager. The %o is the function code returned from the TIP$SM executive request. The %s is the userid for which a session establishment request was being attempted. The %d is the PID allocated to the connection. Action: Examine the function code returned in the %o field to determine the type of request UACS received. The function code is documented in the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual. Location: Trace File
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-15
48 TIPQ received an MCB output message for an un-assigned pid [%d]. Type: ERROR Reason: UACS received an output routing queue message for an unallocated PID. The %d is the PID for which the message was received. This will typically occur when other OS 2200 applications are using PIDs allocated to UACS. Action: Ensure that all PIDs allocated to UACS are not in use by other OS 2200 applications. Location: Trace File
49 Invalid configuration file version [%x] [%x], filename [%s]. Type: ERROR Reason: A UniAccess Configuration File was specified with an invalid version. The first %x is the Configuration File version required by UACS. The second %x is the Configuration File version of the file specified on the UACS processor call. The %s is the Configuration File name of the file specified on the UACS processor call. Action: Generate a Configuration File using the UACF utility that was provided with the current version of UACS and reboot UACS, or use the correct Configuration File on the UACS processor call (see Executing UACS in Chapter 17). Location: System Console
51 Validation for [%s] failed - UADT not loaded. Type: ERROR Reason: UADT has not been loaded. The %s is the name of the item that UACS was attempting to validate in UADT. Action: Refer to Chapter 6 (specifically, page 6-7) for instructions on loading UADT. Location: Trace File
52 User validation for [%s] failed - User not located in UADT. Type: ERROR Reason: ACS failed to locate a UAUSER definition in UADT for the connection attempt. The %s is the userid that failed the validation check. Action: Add the userid to the UniAccess Configuration File and load the information into UADT. Refer to Chapter 6 for instructions on this process. Location: Trace File
Release 10R3: October 31, 2005 D-16 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
53 Invalid or missing UACS process name. Type: ERROR Reason: The UACS processor call did not contain a UACS process name, or the call syntax was incorrect. Action: Specify a UACS process name on the UACS processor call command line. Location: System Console
54 UADT not initialized. Type: ERROR Reason: UACS failed to boot because UADT is not initialized. Action: Refer to Chapter 6 (specifically, page 6-7) for instructions on loading UADT. Location: System Console
55 Client connection timeout [%s] on pid [%d]. Type: WARNING Reason: UACS connection time-out processing was configured and a connection inactivity time-out was detected. UACS aborted the connection. The %s is the userid specified by the client application. The %d is the PID that was allocated to the aborted connection. Action: If the connection termination was not desired, increase the connection time-out value or discontinue connection time-out processing. The COMSRV CONTIMOUT UniAccess configuration parameter defines this value (see Chapter 16). Location: Trace File
56 Failed to locate COMSRV entry [%s] in configuration file. Type: ERROR Reason: UACS was unable to locate a COMSRV entry in the UniAccess Configuration File for the process name specified on the UACS processor call command line. The %s is the name of the process name used to search for a COMSRV record. Action: Create a UniAccess Configuration File COMSRV entry for the process name being used. Location: System Console
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-17
57 Failed to initialize with UAMM [%d] [%o]. Type: ERROR Reason: UACS failed to initialize with UAMM. The %d is a UAMM detailed error code. The %o contains the error code returned from the service library storage management service. Action: Examine the %d field to determine the reason for the failure. (The error code is documented on page D-50 under UAMM Detailed Error Messages.) If the %o field is non-zero, examine the error code to determine the reason for the failure. [The error code is documented in the Unisys OS 2200 Service Library (SLIB) Programming Reference Manual.] Deactivate and initialize the UniAccess Fixed-gate. (Refer to Chapter 6 for instructions on these procedures.) Location: System Console
58 Failed in function [%s] in UAMM,pid [%d],other info [%d]. Type: ERROR Reason: UACS failed on a UAMM function call. The %s is the name of the function call. The %d is the PID of the connection for which the call was being made. The last %d is a UAMM detailed error code. Action: Examine the %d field to determine the reason for the failure. The error code is documented on page D-50 under UAMM Detailed Error Messages in this appendix. Location: Trace File
. 59 Connection does not belong to UASL or UACL,pid [%d],type [%d], process state [%s]. Type: ERROR Reason: An internal UACS error has occurred. The first %d is the PID of the connection on which the error occurred. The second %d is the offending type value, and the %s is the connection process state. Action: Terminate and restart UACS. If the problem persists, contact AIS Technical Support. Location: Trace File 60 Disconnect from UAMM failed [%d][%o]. Type: ERROR Reason: UACS failed to disconnect successfully from UAMM. The %d is a UAMM detailed error code. The %o contains the error code returned from the service library storage management service.
Release 10R3: October 31, 2005 D-18 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Action: Examine the %d field to determine the reason for the failure. (The error code is documented on page D-50 under UAMM Detailed Error Messages, in this appendix.) If the %o field is non-zero, examine the error code to determine the reason for the failure. [The error code is documented in the Unisys OS 2200 Service Library (SLIB) Programming Reference Manual.] Terminate all active UACSs, deactivate and reinitialize the UniAccess Fixed-gate. (Refer to Chapter 6 for instructions on these procedures.) Location: System Console, Trace File
61 Server validation for [%s] failed - Server not located in UADT. Type: ERROR Reason: UACS failed to locate a SERVER definition in UADT. The %s is the server that failed the validation check. Action: Add the SERVER statement to the UniAccess Configuration File and load the information into UADT (see Chapters 6). Location: Trace File
62 Network read timeout [%s] on pid [%d]. Type: WARNING Reason: UACS detected a time-out on a connection waiting for data from the network. The connection was aborted. The %s is the userid for the aborted connection. The %d is the PID that was allocated to the connection. Action: If the connection termination was not desired, increase the read time-out value or discontinue read time-out processing. The COMSRV NWRTIMOUT UniAccess configuration parameter defines this value (see Chapter 16). Location: Trace File
63 Network write timeout [%s] on pid [%d]. Type: WARNING Reason: UACS detected a time-out on a connection sending data to the network. The connection was aborted. The %s is the userid for the aborted connection. The %d is the PID that was allocated to the connection. Action: If the connection termination was not desired, increase the write time-out value or discontinue read time-out processing. The COMSRV NWWTIMOUT UniAccess configuration parameter defines this value (see Chapter 16). Location: Trace File
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-19
64 Unknown queue item found on the MMq routing queue - type [%d]. Type: ERROR Reason: UACS received an unrecognized queue item from UAMM. The %d is the type of queue item received. This is an internal UniAccess System error. Action: Contact AIS Technical Support. Location: Trace File
65 MMQ received write request for Username = [%s], pid = [%d]. Type: INFORMATION Reason: UACS received a request to write a packet to the network from UAMM. The %s is the userid for which the request was received. The %d is the PID allocated to the connection on which the request was received. Action: N/A Location: Trace File
. 66 MMQ received connect request for pid [%d]. Type: INFORMATION Reason: UACS received a request to establish a network connection with a server from UAMM. The %d is the PID allocated to the connection on which the request was received. Action: N/A Location: Trace File
67 MMQ received close request for Username = [%s], pid = [%d]. Type: INFORMATION Reason: UACS received a request to close a network connection with a server from UAMM. The %s is the userid for which the request was received. The %d is the PID allocated to the connection on which the request was received. Action: N/A Location: Trace File
68 MMQ received error request for Username = [%s], pid = [%d], rpc = [%s]. Type: ERROR Reason: UACS received an error indication from UAMM. The first %s is the userid for which the request was received. The %d is the PID allocated to the connection on which the request was received. The second %s is the name of the RPC last scheduled for the user. The UniAccess library program terminated without detaching from the UniAccess System.
Release 10R3: October 31, 2005 D-20 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Action: Check for transaction errors and resolve them. Location: Trace File
69 TSAM error indication received [%o] [%d] [%d]. Type: ERROR, WARNING Reason: UACS received an error indication from the network. The %o is status returned from a TSAM receive function call or CPComm API. The first %d is the reason field of the TSAM receive call. The second %d is the subreason field of the TSAM receive call. Action: For ERROR types, the status, reason, and subreason fields can be examined. These fields is documented in the Unisys OS 2200 Communications Management System (CMS 1100) Programming Reference Manual or in the Unisys OS 2200 Cooperative Processing Communications Platform (CPComm) Programming Reference Manual. Location: Trace File
. 70 Inconsistent qitem [%d], pid [%d], process state [%s], net state [%s]. Type: ERROR Reason: UACS has received an inappropriate request for the current state of a connection. The %d is the UAMM queue item received by UACS. The second %d is the PID of the connection. The first %s is the connection process state. The last %s is the connection network state. Action: Ensure the programs involved in the offending request are properly constructed and verify the integrity of the network. If the problem persists, contact AIS Technical Support. Location: Trace File
71 Table Response to a Command received - Username = [%s], pid = [%d]. Type: INFORMATION Reason: UACS received a response to a UACL request from the network. The %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: N/A Location: Trace File
72 TSAM Open Rejected pid = [%d]. Type: WARNING Reason: UACS received a rejection from a UACL network open request. The %d is the PID of the connection.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-21
Action: Use the PID to determine which UACL transaction was making the connection request. Next, determine to which remote peer the UACL transaction was connecting. Ensure that the peer is functioning properly and retry the connection attempt. Location: Trace File
73 Stop connection input done for pid = [%d]. Type: INFORMATION Reason: UACS issued a stop connection input for a connection. The %d is the PID of the connection. Action: N/A Location: Trace File
74 Resume connection input done for pid = [%d]. Type: INFORMATION Reason: UACS issued a resume connection input for a connection. The %d is the PID of the connection. Action: N/A Location: Trace File
75 Signon failed. User password has expired. Username = [%s], pid = [%d]. Type: ERROR Reason: The TIP session manager indicated to UACS that the password has expired for the userid contained in the %s field. The %d is the PID allocated to the connection. This error will only occur when TIP Session control is active. Action: If the Open Client application supports the password syntax of oldpas/ newpas, UACS can be used to modify the password by specifying oldpas/ newpas as the password where oldpas is the current password and newpas is the new password. Otherwise, change the password using a demand or TIP session or have the system administrator change the password. Location: Trace File 76 Invalid FGSS version [%x] [%x]. Type: ERROR Reason: The level of UACS and the UniAccess Fixed-gate are incompatible. The first %x is the Fixed-gate level that UACS requires. The second %x is the actual level of the Fixed-gate. Action: Install matching levels of the UniAccess Fixed-gate and UACS. Ensure that UACS has been completely installed after an upgrade installation. Location: System Console
Release 10R3: October 31, 2005 D-22 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
77 Error accessing language trace file [%s], [%s], os error [%s]. Type: ERROR Reason: Opening a new UniAccess language trace file cycle failed. The %s is the name of the trace file that failed to open. The second %s is the error encountered by UACS if any. The third %s describes either a system error number (such as for file open failure) or a facility error number (such as a file assign failure) if available. Action: Assign a new cycle of the file manually to determine what OS 2200 limitation prohibited UACS from assigning the file. Location: System Console
78 MMQ received UATC connection request when UATC requests are not valid. Type: ERROR Reason: UACS has encountered a connection request made by a UniAccess Transaction Client (Client-Library) program when UACS is configured to only accept UniAccess Transaction Server (Server-Library) programs. The connect request has been rejected. Action: Modify the UniAccess Transaction Client program to communicate through a UACS that is configured to accept UniAccess Transaction Client requests or reconfigure UACS to accept UniAccess Transaction Client requests. (See the COMSRV UACSTYPE parameter in Chapter 16 for details.) Location: Trace File
79 %s failed, [MCBERR: %o], of VAR security for %s, %d. Type: ERROR Reason: UACS has received an error from MCB while attempting to start the Logon/Logoff VAR security program. The first %s defines the function UACS was trying to perform, logon request or logoff request. The %o is the error code reported by MCB. The %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: Ensure the program involved is set up properly. The function types logon request and logoff request correlate to the transactions defined by the CONSRV LOGONTRAN and LOGOFFTRAN records (see Chapter 16). Location: Trace File
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-23
80 Logon failed. Illegal userid/passwd from Username = [%s], pid = [%d], comment = [%s]. Type: ERROR Reason: The VAR security system has rejected a logon request because of an illegal userid or password. The first %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. The second %s is any comment that the VAR security system has included as further explanation for the rejection. If no comment has been supplied, this field will be N/A. Action: Verify the userid and password with the VAR security system. Location: Trace File
81 Logon failed. User password has expired. Username = [%s], pid = [%d], comment = [%s]. Type: ERROR Reason: The VAR security system has rejected a logon request because the password for this user has expired. The first %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. The second %s is any comment that the VAR security system has included as further explanation for the rejection. If no comment has been supplied, this field will be N/A. Action: Consult the VAR security procedures on how to update the password. Execute these procedures for the user on which the result was received. Location: Trace File
82 Transaction request [%s] denied. Username = [%s], pid = [%d], comment = [%s]. Type: ERROR 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. The third %s is any comment that the VAR security system has included as further explanation for the rejection. If no comment has been supplied, this field will be N/A. Action: Contact the security system administrator to coordinate transaction security for the indicated transaction and userid. Location: Trace File
Release 10R3: October 31, 2005 D-24 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
83 User session timeout received. Username = [%s], pid = [%d], comment = [%s]. Type: ERROR Reason: The VAR security system has terminated the user session because the user terminal session has existed longer than allowed. The first %s is the name of the transaction the user attempted to execute. The %d is the PID allocated to the connection on which the result was received. The second %s is any comment that the VAR security system has included as further explanation for the rejection. If no comment has been supplied, this field will be N/A. Action: Re-establish your session with UACS. Consult with the security administrator about extending your terminal session time limits. Location: Trace File
84 Unknown msg received from VAR security [%s]. Username = [%s], pid = [%d], comment = [%s]. Type: ERROR Reason: The VAR security system has sent a message to UACS that UACS does not understand. The first %s is the message received by UACS. 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. The third %s is any comment that the VAR security system has included as further explanation for the rejection. If no comment has been supplied, this field will be N/A. Action: Contact the security administrator and verify that the message is in the format expected by UACS. If it is not in the proper format, check the value of the COMSRV LOGONTRAN variable (see Chapter 16). Verify that this is the correct transaction to execute. If this is the correct transaction or if the message is not in the proper format, contact the VAR security support or AIS support. Location: Trace File 85 VARSEC error: latent msg received, Username =[%s], pid = [%d], msg = [%s], comment = [%s]. Type: ERROR Reason: UACS has received a message from the VAR security logon transaction for a user that is no longer associated with this PID. The first %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. The second %s is the message received by UACS. The third %s is any comment that the VAR
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-25
security system has included as further explanation for the rejection. If no comment has been supplied, this field will be N/A. Action: A configuration problem probably existed and was subsequently cleared up. However, there are/were outstanding output queue items from the MCB to UACS that could not be processed. Ensure that there are no more outstanding output queue items from the MCB. If there are, the MCB will have to be brought down and re-initialized to delete these queue items. If the problem persists, contact AIS Support. Location: Trace File
86 MMQ Task [%d] successfully initialized. Type: INFORMATION Reason: The MMQ task has successfully initialized. The %d indicates the task value. Action: N/A Location: Trace File
87 MMQ Task [%d] terminating. Type: INFORMATION Reason: The MMQ task has successfully terminated. The %d indicates the task value. Action: N/A Location: Trace File
88 TSAM received a TCP suspend for PID [%d]. Type: INFORMATION Reason: UACS received a TCP suspend for the PID indicated by the %d field. Action: N/A Location: Trace File
89 An invalid extended session request was received, pid = [%d], active trx = [%s], requested trx = [%s]. Type: ERROR Reason: A client in extended session mode has issued a request for a transaction that is different from that already servicing the client. The %d is the client’s associated PID. The first %s is the server transaction currently executing for the client’s extended session. The second %s is the second or subsequent requested server transaction.
Release 10R3: October 31, 2005 D-26 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Action: Examine and correct the client program. Location: Trace File
90 CMS is unavailable, UACS will attempt to reconnect. Type: INFORMATION Reason: UACS has detected that CMS or CPComm has become unavailable. A console message is displayed asking the operator whether or not UACS should attempt to reconnect to CMS or CPComm. UACS will close the trace file and create a new cycle. Action: The operator must answer the console prompt. If UACS is requested to reinitialize with CMS or CPComm, the operator should ensure that CMS or CPComm has been reinitialized before making this request. Location: Trace file
91 CMS is available, UACS reinitialization complete. Type: INFORMATION Reason: After UACS has detected that CMS or CPComm has become available, it has been able to successfully attach to CMS or CPComm and initialize all tasks. Action: N/A Location: Trace file, System Console
92 No product service permissions exist in the product key. Type: ERROR Reason: The product key contained in UADT does not contain any product permissions. Action: The UniAccess Configuration File must be rebuilt with a valid product key(s) and the UniAccess Fixed-gate shared subsystem must be deactivated and reloaded. Location: System Console, Trace File 93 UADT permissions do not match the product key values. Type: ERROR Reason: One or more product permission(s) has expired. Action: The UniAccess Configuration File must be rebuilt with a valid product key(s) and the UniAccess Fixed-gate shared subsystem must be deactivated and reloaded. Location: System Console, Trace File
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-27
94 Invalid product key. Type: ERROR Reason: An invalid product key has been specified in the UniAccess Configuration File. Action: The Configuration File must be rebuilt with a valid product key(s) and the UniAccess Fixed-gate shared subsystem must be deactivated and reloaded. Location: System Console
95 PRODKEY record read error. Type: ERROR Reason: A read error occurred when UACS attempted to read the product key information (UACLPRODKEY, UAHSPRODKEY, UARSPRODKEY, and/or UASLPRODKEY) from the UniAccess Fixed-gate shared subsystem. Action: The Fixed-gate must be deactivated and reloaded. Location: System Console
96 OSPARM record read error. Type: ERROR Reason: A read error occurred when UACS attempted to read the OSPARM record from the UniAccess Fixed-gate shared subsystem. Action: The Fixed-gate must be deactivated and reloaded. Location: System Console
97 Invalid UACSTYPE parameter value. Type: ERROR Reason: The UACSTYPE parameter of the COMSRV statement in the UniAccess Configuration File specifies an invalid value. Action: Correct the UACSTYPE parameter and rebuild the UniAccess Configuration File. The UniAccess Fixed-gate subsystem must be deactivated and reloaded. Location: System Console
98 UACSTYPE [%s] is not authorized and has been removed. Type: INFORMATION Reason: The UACSTYPE parameter of the COMSRV statement in the UniAccess Configuration File specifies a service that is not permitted by the product key(s) (UATC or UATS).
Release 10R3: October 31, 2005 D-28 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
Action: Correct the UACSTYPE parameter and rebuild the UniAccess Configuration File. The UniAccess Fixed-gate subsystem must be deactivated and reloaded. Location: System Console, Trace File
99 UACS error: [%s] permission is required. Type: ERROR Reason: A request has been received which is not supported by the product key. The %s is the feature that is missing from the product key. This may be the UASL, UACL, UAHS, or UARS. Action: Verify that the product key(s) is correct in the UniAccess Configuration File. If incorrect, reconfigure using the correct product key(s), ensuring that the UniAccess Fixed-gate shared subsystem is deactivated and reloaded after the configuration has occurred. If the product key(s) does not support the feature, the missing feature must be ordered, the Configuration File rebuilt using the new product key, and the Fixed-gate deactivated and reloaded. Location: Trace File
100 UAMM process slots, total [%d], available [%d]. Type: INFORMATION Reason: When UACS is started, this message is displayed to provide information about the status of the UAMM process slots. It can be used to determine if the UniAccess Fixed-gate shared subsystem needs to be reinitialized. The first %d is the total number of UAMM slots allocated. The second %d is the total number of slots available. Action: If a large number of UAMM process slots are unavailable, use the key-in: UACS UAMM STATUS to display the process states. The Fixed-gate must be deactivated and reloaded to free the slots. Otherwise, no action is required. Location: System Console, Trace File
101 Language request not supported by COMSRV configuration. Type: ERROR Reason: A language request was received, but no language transaction was configured. Action: Configure a language transaction. A default language transaction (COMSRV DFLTTRAN) needs to be configured if a non-ODBC client or a pre-6R2 ODBC client is being used. Location: Error returned to application, UACS Trace File.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-29
102 Catalog request not supported by language transaction. Type: ERROR Reason: A catalog RPC request was received when the configured language transaction is not capable of servicing the request. This can occur when the language transaction is a user language transaction or no language transaction is configured. Action: Catalog RPC requests can only be serviced by the UniAccess Relational Service or the UniAccess Hierarchical Service. Configure users to use these language transactions. Location: Trace File
103 An invalid distributed transaction request was received, pid = [%d], active trx = [%s], requested trx = [%s]. Type: ERROR Reason: A client participating in a distributed transaction has issued a request for a transaction that is different from that already servicing the client. The first %s is the server transaction currently executing on behalf of the client. The second %s is the second or subsequent requested server transaction. Action: Examine the client program and correct. Location: Trace File
104 Distributed transaction command [%s] received, pid = [%d], transaction id = [%s], VA LTA B = [ %s ]. Type: INFORMATION Reason: The distributed transaction commands are of 2 types: command REQUEST (incoming to UACS) and command REPLY (outgoing from UACS). The message types are complementary (e.g., PREPARE REQUEST has a complement in PREPARE REPLY). If the command is of type command REQUEST, UACS has received a distributed transaction command; the command still needs to be processed. A successful completion of the command REQUEST command is signified by its complementary REPLY trace message. The exception to this rule is the case where STEPID REPLY occurs before its complement PULL REQUEST. Note that if the processing of a REQUEST type command results in an error, trace message 105 is posted. The first %s is the distributed transaction command, the %d is the client’s associated PID. The second %s is the client’s associated transaction ID (if applicable) in the form YYYY-MM-DD HH:MM:SS 01234567-0001,
Release 10R3: October 31, 2005 D-30 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
otherwise N/A. The third %s is the client’s associated server transaction VALTAB name (if applicable), otherwise N/A. Action: None. This message is for information purposes only. Location: Trace File
105 Distributed transaction command [%s] unsuccessfully processed, pid = [%d], transaction id = [%s], VALTAB = [%s]. Type: ERROR Reason: UACS has unsuccessfully processed a distributed transaction request from either a client or UADTC. The first %s is the distributed transaction command. The %d is the client’s associated PID. The second %s is the client’s associated transaction ID (if applicable) in the form YYYY-MM- DD HH:MM:SS 01234567-0001, otherwise N/A. The third %s is the client’s associated server transaction VALTAB name (if applicable), otherwise N/A. Action: The client program should be examined for distributed transaction compliance and corrected appropriately. The trace file should be examined to determine if prior events occurred for the client’s PID which may have contributed to the error (e.g., did the client disconnect prior to a PREPARE). Location: Trace File
106 [%s] recovery being attempted, transaction id = [%s]. Type: WARNING Reason: UACS has received a UADTC command to COMMIT/ABORT/ RECONNECT for a client PID which is no longer active. UACS recovery processing examines the list of recovered PREPARED transactions in order to respond to the request. The first %s is the UADTC command (COMMIT/ABORT/RECONNECT). The second %s is the transaction ID in the form YYYY-MM-DD HH:MM:SS 01234567-0001. Action: None. This is a normal recovery operation which will occur if transactions are left in the prepared state after a system, application group or UACS stop. Location: Trace File
107 Distributed transaction request was rejected because the UDS BDI is not configured, pid = [%d]. Type: ERROR
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-31
Reason: UACS has rejected a distributed transaction command because the UniAccess Configuration File APPINF UDSBDI parameter has not been defined. The %d is the client PID. Action: The UniAccess Configuration File must be updated to supply the appropriate APPINF UDSBDI parameter value. After updating the Configuration File, UACS must be stopped and restarted. Location: Trace File
108 A distributed transaction ENLIST request was received for a connection in extended session mode, pid = [%d], VALTAB = [%s]. Type: ERROR Reason: UACS has rejected a distributed transaction ENLIST command because the client is executing in extended session mode. The %d is the client PID. The %s is the client’s associated server transaction VALTAB name. Action: The client program should be checked for UADTC compliance and corrected as appropriate. Location: Trace File
109 Distributed transaction command [%s] was rejected because the connection is not enlisted, pid = [%d], transaction id = [%s], VALTAB = [%s]. Type: ERROR Reason: UACS has processed a distributed transaction command which was rejected because the client has not issued a distributed transaction ENLIST command. The %d is the client PID. The first %s is the distributed transaction command. The second %s is the transaction ID in the form YYYY-MM-DD HH:MM:SS 01234567-0001, if available. The third %s is the client’s associated server transaction VALTAB name. Action: The client program should be checked for UADTC compliance and corrected as appropriate. If the client is compliant, then the trace file should be examined to determine if prior events occurred for the client’s PID which may have contributed to the error (e.g., did the ENLIST fail). Location: Trace File
110 Distributed transaction command [%s] contained invalid transaction id for pid = [%d], transaction id = [%s]. Type: ERROR Reason: UACS has rejected a distributed transaction command because the distributed transaction ID is no longer valid. The %d is the client PID. The
Release 10R3: October 31, 2005 D-32 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
first %s is the distributed transaction command. The second %s is the client’s associated transaction ID in the form YYYY-MM-DD HH:MM:SS 01234567-0001. Action: The client program should be checked for UADTC compliance and corrected as appropriate. If the client is distributed transaction compliant, then the trace file should be examined to determine if prior events occurred for the client’s PID which may have contributed to the error (e.g., did the client disconnect prior to a PREPARE). Location: Trace File
111 Distributed transaction command contained PID [%d] not within range of valid PIDs [%d -> %d]. Type: ERROR Reason: UACS has received a distributed transaction request for a client associated PID which lies outside the range of configured PIDs. The first %d is the submitted client associated PID. The second %d is the lower limit of configured PID range for this UACS. The third %d is the upper limit of configured PID range for this UACS. Action: Determine why the client associated PID is invalid; in particular, ensure that the PID range has not been changed in the configuration. Location: Trace File
112 Distributed transaction completed. Enlist this session in a new transaction or the NULL transaction. PID = [%d]. Type: ERROR Reason: 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. Location: Trace File
113 Native server-to-server connection request rejected, server = [%s]. Type: ERROR Reason: UACS has received a server-to-server protocol request. UACS no longer supports this type of protocol. The %s is the name of the originating server.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-33
Action: Change client protocol so as not use server-to-server protocol. Location: Trace File
114 Network Buffer size has been reset to [%d] bytes for PID [%d]. Type: INFORMATION Reason: UACS has reset the network buffer size from the default network buffer size (UAMM BLOCKSIZE configuration parameter). The first %d is the network size to be used by the connection. The second %d is the PID that was allocated to the connection. Action: If the default network buffer size needs to be changed, reset the UACS block size accordingly. The UAMM BLOCKSIZE UniAccess configuration parameter defines this value (see Chapter 16). Location: Trace File
115 Bad PID timeout [%s] on pid [%d]. Type: WARNI NG Reason: UACS detected that a connection is in error, but the connection has not been terminated by UACS. The connection was aborted. The %s is the userid for the aborted connection. The %d is the PID that was allocated to the connection. Action: If an unconditional error connection termination was not desired or a different timeout interval is wanted, set the bad PID timeout value accordingly. The COMSRV BADPIDTIMOUT UniAccess configuration parameter defines this value (see Chapter 16). Location: Trace File
116 TIP Session Control forced closure preventing scheduling of LOGOFF transaction, User = [%s] pid = [%d]. Type: ERROR Reason: TIP session control has timed out a user and hence, UACS is unable to schedule a designated logoff transaction. Action: When a logoff transaction is configured, timeout values should be set to ensure that either the UniAccess connection timeout (COMSRV CONTIMOUT parameter) or a timeout from the security API (either third party software or local software) occurs prior to TIP session control terminating the session. TIP session control terminates the session after a specified period expires with no input. The termination timeout value for TIP sessions is specified
Release 10R3: October 31, 2005 D-34 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
via userid using SIMAN. For additional information, please see the Unisys Security Planning and Administration Reference Manual. Location: Trace File
117 Signon failed. [%s] User = [%s], pid = [%d]. Type: ERROR Reason: UACS has tried logging on to the OS2200 system and the request has been rejected. The most probable cause is that the user has tried to change the password and has supplied invalid information. The first %s is the OS2200 explanation for the sign-on rejection. The second %s is the userid for the aborted connection. The %d is the PID that was allocated to the connection. Action: The OS2200 explanation should be self-explanatory and the user should take appropriate action. Typical OS 2200 explanations for a new password being rejected are: — The new password is too short. — The new password is too long. — The new password must be different than the old password. — The new password contains invalid characters. Location: Trace File
118 Server [%s] Domain Name could not be resolved - CMS DNR error [%o]. Type: ERROR Reason: The SERVER HOSTNAME parameter value could not be resolved by the CMS Domain Name Resolver module and no ADDR parameter has been defined for the SERVER. The %s is the erroneously configured SERVER parameter and the %o is the error value returned by the CMS DNR feature. Action: Verify that the specified SERVER HOSTNAME parameter value is valid (see Chapter 16) and ensure that the CMS Domain Name Resolver configuration parameters (TCPIP-DNR) are valid, including an up-to-date HOSTS-FILE file. Additionally, a SERVER ADDR parameter could be configured. Location: Trace File
119 Server [%s] Domain Name could not be resolved - configured address will be used. Type: WARNI NG Reason: The SERVER DOMAINNAME parameter could not be resolved by the CMS Domain Name Resolver module, and the configured ADDR
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-35
parameter value will be used as the SERVER IP address. The %s is the dubious configured server. Action: Verify that the specified SERVER DOMAINNAME parameter value is valid (see Chapter 16) and ensure that the CMS Domain Name Resolver configuration parameters (TCPIP-DNR) are valid including an up-to-date HOSTS-FILE file. Location: Trace File
120 Blocked PID timeout [%s] on pid [%d]. Type: WARNI NG Reason: UACS detected that a PID for a server transaction has been blocked longer than the configured COMSRV BLKPIDTIMOUT value. The connection was aborted. The %s is the userid for the aborted connection. The %d is the PID that was allocated to the connection. Action: If the termination of the blocked transaction was not desired, increase the BLKPIDTIMOUT value or turn off blocked PID checking by setting the BLKPIDTIMOUT parameter to a value of zero (see Chapter 16). If this action persists or occurs too often, the Client application should be reviewed to determine why it cannot accept the Server transaction’s output data. Location: Trace File
121 Connection terminated - [%s] product key limit reached, User = [%s], pid = [%d]. Type: WARNI NG Reason: The connection could not be made because the specified products’s product key connection limit has already been reached. The first %s is the product whose product key limit has been reached. The second %s is the affected user. The %d is the user’s PID. Action: Contact AIS Technical Support to purchase an upgraded product key license(s). Location: Trace File
122 Trx [%s] not scheduled - [%s] product key not active for this session. User = [%s], pid = [%d]. Type: WARNI NG 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
Release 10R3: October 31, 2005 D-36 Operational Messages / UACS UniAccess for OS 2200 System Administration Guide
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. The third %s is the affected user. The %d is the user’s PID. Action: If the client application is using the 9R1, or later, UniAccess ODBC Driver and a configured Data Source Name (DSN), verify that all services to be used by the application (UARS, UAHS, and/or UASL) are properly configured. If the client application is using the 9R1, or later UniAccess ODBC Driver and a DSN-less connection, verify that all services to be used by the application (UARS, UAHS, and/or UASL) are properly specified in the connection string. If the client application is using Open Client, or a pre-9R1 UniAccess ODBC Driver, verify that the DFLTTRAN parameter of the COMSRV statement has been configured to support the services (UARS, UAHS, and/or UASL) that are being used. Location: Trace File
123 [%s] product key expires in [%d] days. Type: WARNI NG Reason: UACS has detected that a product key is about to expire. The %s specifies the product whose product key is about to expire. The %d indicates the number of days until the product key expires. This message only appears when the number of days is 14 or less. Action: Contact AIS Technical Support to receive your permanent product key(s) or to renew your product key license(s). Location: Trace File
124 Client Abort disconnect received - Username = [%s], pid = [%d]. Type: WARNI NG Reason: UACS has encountered a situation requiring that the client connection be aborted. For example, UACS received a TCP/IP abort indication. Action: Check the UACS trace file and or communications logs (CMS, CPComm, etc.) for error indications. Location: Trace File
125 Bad/Latent qitem received - pid = [%d], current mmid = [%d], target mmid = [%d]. Type: ERROR Reason: UACS has received a qitem for an unused PID. The first %d is the PID that recieved the quitem. The second %d is the current message manager id. The third %d is the target message manager id.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACS D-37
Action: Please send the log file to AIS Technical Support at [email protected]. Location: Trace File
126 UACS system Logging switched [%s]. Type: WARNI NG Reason: The state of UACS security event logging has been changed via operator keyin. The %s is the new state of security event logging. Action: N/A Location: Trace File
Release 10R3: October 31, 2005 D-38 Operational Messages / Security Event Messages UniAccess for OS 2200 System Administration Guide
Security Event Log Messages
Security Event Log messages are a subset of the UACS Trace File messages specific to UACS security events. These messages are captured to the OS 2200 system log file when system logging is turned on, either by the COMSRV SYSLOG configuration parameter or by the UACS SYSLOG console command. For more information about configuring security event logging and about the format of security event logs, see page 19-33.
The following UACS Trace File messages are written to the system log file as UACS security events. For details concerning each individual message, please see the UACS Trace File and Console Messages that begin on page D-2.
19 Terminating with [%d] clients still active.
20 Terminating a client connection [%s] [%d].
24 Client login received - Username = [%s], pid = [%d], mmid = [%d], IP-addr = [%s].
27 Client disconnect received - Username = [%s], pid = [%d].
42 Signon failed. Illegal userid/passwd from Username = [%s], pid = [%d].
44 TIP Session Control has closed User = [%s] pid = [%d].
52 User validation for [%s] failed - User not located in UADT.
55 Client connection timeout [%s] on pid [%d].
62 Network read timeout [%s] on pid [%d].
63 Network write timeout [%s] on pid [%d].
66 MMQ received connect request for pid [%d].
67 MMQ received close request for Username = [%s], pid = [%d].
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / Security Event Messages D-39
75 Signon failed. User password has expired. Username = [%s], pid = [%d].
79 %s failed, [MCBERR: %o], of VAR security for %s, %d.
80 Logon failed. Illegal userid/passwd from Username = [%s], pid = [%d], comment = [%s].
81 Logon failed. User password has expired. Username = [%s], pid = [%d], comment = [%s].
82 Transaction request [%s] denied. Username = [%s], pid = [%d], comment = [%s].
83 User session timeout received. Username = [%s], pid = [%d], comment = [%s].
84 Unknown msg received from VAR security [%s]. Username = [%s], pid = [%d], comment = [%s].
85 VARSEC error: latent msg received. Username =[%s], pid = [%d], msg = [%s], comment = [%s].
116 TIP Session Control forced closure preventing scheduling of LOGOFF transaction, User = [%s] pid = [%d].
117 Signon failed. [%s] Username = [%s], pid = [%d].
121 Connection terminated - [%s] Product Key Limit reached. User = [%s], pid = [%d].
Release 10R3: October 31, 2005 D-40 Operational Messages / UACF UniAccess for OS 2200 System Administration Guide
UACF Error Messages
UACF messages are displayed on the terminal executing the UACF processor. They have the following format:
msgtext [msgcode] *ERROR*
where:
msgtext is the message text listed below
msgcode is the message code listed below
1 Configuration file build failed. Reason: An error occurred while writing the UniAccess Configuration File. Action: Check the status of the file being created. Repair the file problem.
2UADT load failed [%o]. Reason: An error occurred while attempting to load the UADT service of the UniAccess Fixed-gate shared subsystem (UAFG). The %o contains the error code returned from the service library storage management service. Action: Examine the %o value to determine the reason for the failure. The %o is a twelve digit octal number. The octal number should be interpreted as follows: — The first octal digit indicates the reported severity. A severity of 2 is informational. A severity of 3 is a warning. A severity of 7 is a failure. — The next 5 octal digits represent the Unisys software component reporting the error. This component information may be used by ELMS to customize the error message. — The last 6 octal digits represent the message number associated with the error. This message number may be used by ELMS to customize the error message. The twelve digit error code may be found in the Unisys OS 2200 System Services Programming Reference Manual. If you cannot resolve the error after consulting the Unisys documentation, deactivate and reinitialize UAFG (refer to Chapter 6 for details on these procedures).
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACF D-41
3UAMM initialization failed [%d] [%o]. Reason: An error occurred while attempting to initialize the UAMM service of the UniAccess Fixed-gate shared subsystem (UAFG). The %d is a UAMM detailed error code. The %o contains the error code returned from the service library storage management service. Action: Examine the %d field to determine the reason for the failure. The error code is documented on page D-50 under UAMM Detailed Error Messages. If the %o field is non-zero, examine the error code to determine the reason for the failure. The error code is documented in the Unisys OS 2200 Service Library (SLIB) Programming Reference Manual. Deactivate and reinitialize UAFG (refer to Chapter 6 for details on these procedures).
4 Invalid or missing command line option. Reason: An invalid command line option combination was entered on the UACF processor call. Action: Refer to Chapter 17 for UACF execution syntax.
5 Error accessing file [%s], [%s], os error [%s]. Reason: An error assigning, opening, or reading a file occurred. The first %s indicates the file with which the problem occurred. The second %s is the error encountered by UACF if any. The third %s describes either a system error number (such as for file open failure) or a facility error number (such as a file assign failure) if available. Action: Examine the file indicated in the first %s field and the description in the second and third %s fields to determine the reason for the access failure. Ensure that the file is not corrupt and that appropriate permissions exist to access the file.
6 Internal error. Reason: UACF encountered an unrecoverable error during execution. Action: Record the sequence of steps that caused the problem and contact AIS Technical Support.
7 Memory allocation failure. Reason: UACF failed to dynamically allocate memory. Action: This is an OS 2200 operating system error. Decreasing the size of the Site Configuration File may help this problem.
Release 10R3: October 31, 2005 D-42 Operational Messages / UACF UniAccess for OS 2200 System Administration Guide
8 Invalid token detected, line [%d]. Reason: An invalid statement type or parameter type token was detected while processing a source configuration file. The %d indicates the line number of the invalid token in a source configuration file. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the invalid token. Refer to Chapter 16 for a list of valid statements and their syntax.
9Missing comma after subtoken, line [%d]. Reason: A comma was not located after a parameter type token in a source configuration file. The %d indicates the line number of the invalid statement in the source configuration file. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the statement where the error was detected. Refer to Chapter 16 for a list of valid statements and their syntax.
10 Illegal use of continuation character, line [%d]. Reason: A continuation character was used at an inappropriate place in a source configuration file. The %d indicates the line number where the error was detected. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the statement where the error was detected. Refer to Chapter 16 for a list of valid statements and their syntax.
11 Overlapping PID range detected. Reason: More than one COMSRV statement is using the same PID in the Source Configuration File. Action: Examine all COMSRV PIDCNT and COMSRV PIDSTART parameters to locate the PID range that overlaps. Select a PID range that does not overlap with other PID ranges.
12 Invalid parameter specified, line [%d]. Reason: An invalid parameter value was detected in a source configuration file. The %d indicates the line number where the error was detected. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the statement where the error was detected. Refer to Chapter 16 for a list of valid statements and their syntax.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACF D-43
13 Maximum number of nodes has been exceeded [%s], line [%d]. Reason: The maximum number of statements in a source configuration file has been exceeded for the statement type indicated by the %s field. The %d indicates the line number where the error was detected. Action: Refer to Chapter 16 for a list of statement’s limits. Decrease the number of statements to a value less than or equal to the maximum number of statements allowed for the statement type indicated by the %s field.
14 Maximum message length has been exceeded, line [%d]. Reason: A text string was detected in a source configuration file that was longer than the maximum length allowable. The %d indicates the line number where the error was detected. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the statement where the error was detected. Refer to Chapter 16 to determine the maximum length for the errant parameter value and decrease the length of the statement to a length less than or equal to the maximum allowable length.
15 Terminating double quote missing, line [%d]. Reason: A text string was detected in a source configuration file that was not terminated with a double quote. The %d indicates the line number where the error was detected. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the statement where the error was detected. Terminate the string with a double quote.
16 Duplicate key detected [%s] - [%s], line [%d]. Reason: A duplicate parameter value was detected in a source configuration file for a statement where a unique value is required. The first %s is the parameter type token and the second %s is the statement token. The %d indicates the line number where the error was detected. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the statement where the error was detected. Change the parameter value to make it unique throughout the source configuration file.
Release 10R3: October 31, 2005 D-44 Operational Messages / UACF UniAccess for OS 2200 System Administration Guide
17 Missing required parameter [%s], line [%d]. Reason: A statement was detected in a source configuration file that was missing a required parameter. The %s field contains the name of the statement and parameter tokens of the missing required parameter. The %d indicates the line number where the error was detected. Action: Using the line number indicated by the %d field, examine the source configuration files to locate the statement where the error was detected. Specify a value for the required parameter.
18 Invalid configuration file version [%x] [%x], filename [%s]. Reason: The specified UniAccess Configuration File had an invalid version. The first %x is the file version the UACF processor is capable of processing. The second %x is the file version of the Configuration File specified on the UACF processor command line. The %s is the name of the Configuration File specified on the UACF processor command line. Action: Build a UniAccess Configuration File using the current version of the UACF processor and use that file on the subsequent UACF call.
19 Search for dependent field failed [%s] [%s] [%s]. Reason: A required related statement is missing. The first %s field is the parameter token of the statement for which the related search was being performed. The second %s field is the statement token for which the related search was being performed. The last %s field is the parameter value that was not located in the related statement list. Action: Define a related statement with a value indicated by the last %s field. Refer to Chapter 16 to determine the related statement.
20 Required source filename missing. Reason: A source file name was not specified on the UACF processor call when one was required. Action: Specify a source file name on the UACF processor call.
21 Invalid configuration file format [%s], [%s], os error [%s]. Reason: A file specified on the UACF processor call was not a valid UniAccess Configuration File. The first %s field is the name of the Configuration File specified on the UACF command line. The second %s field is the error encountered by UACF if any. The third %s describes either a system error number (such as for file open failure) or a facility error number (such as a file assign failure) if available.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACF D-45
Action: Specify a valid UniAccess Configuration File on the UACF processor call.
22 Invalid UAFG service version [%s] [%x] [%x]. Reason: An invalid UAFG (UniAccess Fixed-gate shared subsystem) service version was detected by the UACF processor. The %s is the name of the UAFG service being accessed. The first %x is the version of the service with which UACF is capable of interfacing. The second %x is the version of the UAFG service. Action: Use a version of the UACF processor that matches the UAFG version.
23 UADT dump failed. Reason: UACF failed to successfully dump the contents of the UADT service. The UniAccess Fixed-gate (UAFG) may be corrupt. Action: Deactivate and reinitialize UAFG (refer to Chapter 6 for details on these procedures).
24 Invalid configuration file name. Reason: UACF detected an incorrectly formatted configuration file name. Action: Specify a valid OS 2200 file name for the UniAccess Configuration File parameter. Specifying an element name will generate this error.
25 Required configuration filename missing. Reason: A configuration file name was not specified on the UACF processor call when one was required. Action: Specify a source file name on the UACF processor call.
26 Invalid product key [%s]. Reason: An error occurred while processing one of the product keys. The %s indicates which OSPARM product key was in error. Action: Ensure that the product key string was entered correctly. If the key has been entered correctly and the error persists, contact AIS Technical Support.
27 Product key has expired [%s]. Reason: A temporary product key has expired. The %s indicates which OSPARM product key has expired. Action: Replace the expired product key with a product key obtained from AIS Technical Support.
Release 10R3: October 31, 2005 D-46 Operational Messages / UACF UniAccess for OS 2200 System Administration Guide
28 Product key error [%s] - incorrect [%s]. Reason: A valid product key has been entered, but either the level or the product was incorrect. The first %s indicates which OSPARM product key was in error. The second %s indicates the cause of the error: [Level] - indicates that the product key is not correct for this UniAccess level. [Product] - indicates that the product key is valid but that the product does not match the product specified. [Date] - indicates that the temporary product key is valid, but the expiration date has expired. [MCN] - indicates that the product key is valid, but not for this system’s MCN. Action: Verify that the correct product keys are being used for the correct OSPARM parameters. If you have recently upgraded, please verify that the product keys received with the updated software are being used. If the software has been updated, but new product keys have not been received, or if it appears that the correct keys are being used, please contact AIS Technical Support for assistance.
29 UARS/UASL Product key mismatch - Contact AIS Technical Support. Reason: The supplied UARSPRODKEY and UASLPRODKEY are valid keys, but they create an internal conflict. Please Contact AIS Technical Support. Action: Contact AIS Technical Support, reporting the error number and the product keys being used. New product keys will be provided.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACF D-47
UACF Warnings
UACF warning messages will be displayed on the terminal executing the processor.
msgtext [msgcode] *WARNING*
where:
msgtext message text listed below
msgcode message code listed below
2 Default langtran type [%s] not configured [COMSRV %s] for [%s]. Reason: The value specified in the COMSRV DFLTTRAN parameter does not have a corresponding language transaction (COMSRV UAINTRAN, COMSRV UAHSTRAN, or COMSRV UARSTRAN) value configured (see Chapter 16). The first %s is the value of COMSRV DFLTTRAN. The second %s is the language transaction value that is not configured. The third %s is the COMSRV PROCNAME value. Action: Modify the value of COMSRV DFLTTRAN to be a configured language transaction or NONE, and ensure that you have an associated language transaction parameter configured.
3 [%s] statement is not supported and is ignored. Reason: A statement that was supported in a previous level of UACF is not supported in this level. The %s is the name of the UniAccess Configuration statement that is not supported. Action: Review the statement and the current READ.ME document to ensure a full understanding of the statement’s obsolescence. No remedial action is required. 4 [%s] parameter of [%s] statement is not supported and is ignored. Reason: A statement parameter that was supported in a previous level of UACF is not supported in this level. The first %s is the name of the UniAccess Configuration parameter that is not supported. The second %s is the name of the UniAccess Configuration statement to which the parameter was associated.
Release 10R3: October 31, 2005 D-48 Operational Messages / UACF UniAccess for OS 2200 System Administration Guide
Action: Review the statement parameter and the current READ.ME document to ensure a full understanding of the parameter’s obsolescence. No remedial action is required.
5 USEUAUSER set to NO for COMSRV [%s] and no Default USERID record configured. Reason: A COMSRV record has the USEUAUSER option set to NO and no UAUSER record has been configured with a USERID of "@@@@@@@@@@@@" (the default USERID). This condition will cause the UACS defined by this COMSRV record to login userids as if the COMSRV USEUAUSER option was set to YES. The %s is the COMSRV PROCNAME value. This warning will be repeated for each COMSRV definition that meets the above criteria. Action: If the resultant COMSRV action is not the desired action, then either set up a default UAUSER USERID record (see page 16-79) or ensure that all legal users have an associated UAUSER USERID configured.
6 DFLTTRAN service [%s] has been removed from COMSRV [%s} - No valid product key for [%s]. Reason: UACF has determined that a DFLTTRAN service has been specified for which there is no associated product key. The result is as if DFLTTRAN had been specified without the use of the specified service. The first %s identifies the service which has been removed. The second %s is the affected COMSRV. The third %s identifies the missing product key. Action: One of the following actions should be taken: 1) No action -- DFLTTRAN services are only used for pre-9R1 connections; 2) Update the COMSRV DFLTTRAN parameter (see page 16-21) to accurately reflect the configured product keys; 3) contact AIS Technical Support to renew product key license(s); and 4) include any missing product keys as OSPARM parameters (see page 16-48).
7 DFLTTRAN [%s] has been reset to [%s] for COMSRV [%s] - No valid product key for [%s]. Reason: UACF has determined that the specified DFLTTRAN language transaction type has no associated product key. In such cases, UACF replaces the specified DFLTTRAN language transaction type in the following order: UARSTRAN, UAHSTRAN, and finally NONE. The first %s identifies the DFLTTRAN language transaction type that has been replaced. The
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UACF D-49
second %s is the new DFLTTRAN language transaction type setting. The third %s is the affected COMSRV. The fourth %s identifies the missing product key. Action: One of the following actions should be taken: 1) Update the COMSRV DFLTTRAN parameter (see page 16-21) to accurately reflect the configured product keys; 2) contact AIS Technical Support to renew product key license(s); and 3) include any missing product keys as OSPARM parameters (see page 16-48).
Release 10R3: October 31, 2005 D-50 Operational Messages / UAMM UniAccess for OS 2200 System Administration Guide
UAMM Error Messages
The UniAccess Message Manager (UAMM) returns the following error codes that are embedded in Server 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]
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.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UAMM D-51
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 UniAccess 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.
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.
Release 10R3: October 31, 2005 D-52 Operational Messages / UAMM UniAccess for OS 2200 System Administration Guide
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 UniAccess 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.
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.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UAIR D-53
UAIR Error Messages
UAIR error messages are generated by the UniAccess Integrated Recovery processor and returned to the system administrator. UAIR errors cause UAIR to terminate abnormally; they concern problems with either the system administrator input or the UAIR environment. These messages are returned via the normal system print mechanism. They are built directly into the UAIR processor and are not modifiable by the system administrator.
UAIR error messages have the following format:
UAIR *ERROR (msgnum - msgtext)
where:
msgnum is the error message number listed below
msgtext is the message text listed below
1 Internal error. Reason: UACF encountered an unrecoverable error during execution. Action: Record the sequence of steps that caused the problem and contact AIS Technical Support.
2 UniAccess Configuration File name not included on UAIR processor call line. Reason: If UAIR is not executed from the default production mode installation file (SYS$LIB$*UAUTIL), the UniAccess Configuration File name must be supplied on the UAIR processor call line. The Configuration File is used to obtain information about the Application Group. Action: Re-execute UAIR and supply a valid UniAccess Configuration File name.
3 UniAccess Configuration File [%s] name format error - must be Q*F. Reason: The UniAccess Configuration File name must be in the standard format of “QUALIFIER*FILENAME.”. Action: Correct UniAccess Configuration File name and re-execute UAIR.
Release 10R3: October 31, 2005 D-54 Operational Messages / UAIR UniAccess for OS 2200 System Administration Guide
4 Error accessing UniAccess Configuration File [%s], [%d], os error [%o]. Reason: An error assigning, opening, or reading the specified UniAccess Configuration file occurred. The %s indicates the Configuration File name with which the problem occurred. The %d is the error encountered by UAIR if any. The %o describes either a system error number (such as for file open failure) or a facility error number (such as a file assign failure) if available. Action: Examine the file indicated in the %s field and the description in the second and third fields to determine the reason for the access failure. Ensure that the file is not corrupt and that appropriate permissions exist to access the file.
5 Invalid configuration file format [%s], [%d], os error [%d]. Reason: The configuration file specified on the UAIR processor call was not a valid UniAccess Configuration File. The %s field is the name of the configuration file specified on the UAIR command line. The first %d field is the error encountered by UAIR if any. The second %d describes either a system error number (such as a file open failure) or a facility error number (such as a file assign failure) if available. Action: Specify a valid UniAccess Configuration File on the UAIR processor call.
6 Invalid configuration file version [%x] [%x], filename [%s]. Reason: The specified UniAccess Configuration File had an invalid version. The first %x is the configuration file version the UAIR processor is capable of processing. The second %x is the configuration file version specified on the UAIR processor command line. The %s is the name of the configuration file specified on the UAIR processor command line. Action: Re-execute the current version of UAIR, supplying it with a UniAccess Configuration File that has a version level supported by UAIR.
7 No UDS configured application groups in UniAccess Configuration File [%s]. Reason: The UniAccess Configuration File designated by %s is a valid configuration file, but there are no applications groups in the APPINF sections that have a UDSBDI directive. UAIR only operates on application groups (APPINFs) that have an associated UDSBDI directive. Action: Review Configuration File directives to determine if UDSBDI has been omitted inadvertently and correct if necessary. Or supply UAIR with the correct UniAccess Configuration File name.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / UAIR D-55
8 Unable to retrieve PREPARED transactions for Application Group [%s], error = [%d]. Reason: UAIR has failed in its request to UDS to get the list of PREPARED transactions. The %s is the application group that UAIR was attempting to access. The %d is the status returned to UAIR. Action: Check that UDS is up and that the UDSBDI directives are correct in the UniAccess Configuration File. If these checks pass, record the sequence of steps that caused the problem and contact AIS Technical Support.
9 Index chosen [%d] out of range, legal range = [%d] -[%d]. Reason: UAIR has prompted the system administrator to supply an index to either a list of application groups or a list of prepared transactions, and the system administrator has supplied UAIR with an invalid response. The first %d is the system administrator’s invalid response. The %d - %d is the index range that UAIR has prompted the system administrator to choose from. Action: Re-execute UAIR and supply valid responses.
10 Invalid COMMIT/OMIT choice [%d], valid choices are 1 or 2. Reason: UAIR has prompted the system administrator to supply an index to its next course of action, either COMMIT (1) or OMIT (2), and the system administrator has supplied UAIR with an invalid response. The %d is the system administrator’s invalid response. Action: Re-execute UAIR and supply valid responses.
11 [%s] of PREPARED transaction id: [%s] FAILED, error = [%d] Reason: UAIR has failed to COMMIT or OMIT a transaction as directed by the system administrator. The first %s is the action attempted, either COMMIT or OMIT. The second %s is the standard UniAccess transaction identifier in the form: YYY-MM-DD HH:MM:SS 01234567-1234. The %d is the system error encountered in attempting the COMMIT or OMIT. Action: If the system error is 7, which indicates that the transaction is active, terminate the transaction and re-execute UAIR. If the transaction is not active, record the sequence of steps that caused the problem and contact AIS Technical Support.
Release 10R3: October 31, 2005 D-56 Operational Messages / SCHEMADEF UniAccess for OS 2200 System Administration Guide
SCHEMADEF Error Messages
SCHEMADEF messages concern problems with either the UAHS Meta Database (MDB) itself or the use of the MDB. The messages are displayed on the terminal executing the utility program.
SCHEMADEF error messages have the following format:
*ERROR* [msgcode] msgtext
where:
msgcode is the message code listed below
msgtext is the message text listed below
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
1 I-option requires schema input Reason: The @XQT,I option has been exercised, which will cause initialization of the MDB. The MDB contains all pertinent information for a single DMS schema. The symbolic source of the DMS schema has not been found. Action: @ADD the DMS symbolic source after the @XQT,I SCHEMADEF execution command line. (Refer to the SCHEMADEF section of Chapter 14 for a description of the execution syntax.)
2 Illegal DMS record location mode [%s] Reason: DMS supports the following record location modes: CALC, DIRECT, INDEX SEQUENTIAL, and VIA SET. The [%s] is the offending DMS record and its location mode. Action: Correct the DMS schema to fit the supported DMS location modes.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / SCHEMADEF D-57
3 Max AREAs on WITHIN clause has been exceeded [%s] Reason: UAHS supports a maximum of 12 AREAs on the WITHIN clause. If this limit is violated, SCHEMADEF will continue processing the DMS schema symbolic. However, if the record is included in a table/column definition, TABLEDEF will reject the definition and drop the table. The [%s] is the offending DMS record. Action: Restructure the DMS schema to fit the number of areas supported by UAHS.
4 The “USING” keyword is missing [%s] Reason: The DMS CALC and INDEX SEQUENTIAL records must specify record keys with the “USING…” syntax. The [%s] is the offending DMS record. Action: Correct the DMS schema to specify keys.
5 More than 10 keys defined for DMS record [%s] Reason: UAHS supports a maximum of 10 keys for a DMS record. If additional keys are included, SCHEMADEF will continue processing the DMS schema symbolic. However, if the record is included in a table/column definition, TABLEDEF will accept the definition, but will not allow the DMS keys to be used to access the record. The [%s] is the offending DMS record. Action: Restructure the DMS schema to fit the supported number of keys within UAHS.
6 INDEX AREA not found [%s] Reason: DMS INDEX SEQUENTIAL records must have an associated INDEX AREA . The [%s] is the offending DMS record. Action: Correct the DMS schema symbolic to specify the INDEX AREA for the record.
7 “PIC” size is non-numeric [%s] Reason: PIC (n) fields must have n as a numeric value (0-9). The [%s] is the offending DMS record and item. Action: Correct the DMS schema so that n is a numeric value.
Release 10R3: October 31, 2005 D-58 Operational Messages / SCHEMADEF UniAccess for OS 2200 System Administration Guide
8 Group Item key is not supported [%s] Reason: UAHS only supports elementary items. If this restriction is violated, SCHEMADEF will continue processing the DMS schema symbolic. However, if the record is included in a table/column definition, TABLEDEF will accept the definition, but will not allow the DMS keys to be used to access the record. The [%s] is the offending DMS record. Action: Correct the DMS schema so that only elementary items are used for keys.
80 Incompatible MDB Versions [%s] Reason: SCHEMADEF must be exercised against the MDB only when both have the same version (release) level. This error will occur only when a new release of SCHEMADEF has been made and this version has not been used to initialize the MDB. The [%s] is the current MDB and SCHEMADEF versions. Action: Initialize the MDB with @XQT,I SCHEMADEF. Note that when this done, then all tables must be recreated using the TABLEDEF utility.
81 An internal MDB error has been encountered [%s] Reason: The [%s] explains the possible cause. Action: Verify the MDB with @XQT,MR SCHEMADEF. If this fails, make a copy of the bad MDB for further analysis and re-initialize the MDB by @XQT,I SCHEMADEF. Note that if the MDB is re-initialized, all tables must be recreated using the TABLEDEF utility.
82 Open MDB List File error: [%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 (see Step 3 of UAHS Meta Database Procedures in Chapter 14).
83 MDB FCSS 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
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / SCHEMADEF D-59
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 (see Step 3 in UAHS Meta Database Procedures of Chapter 14). If a hardware error has occurred, recover the MDB after the hardware error has been resolved. If a system error has occurred, consult with your systems group for a resolution.
Release 10R3: October 31, 2005 D-60 Operational Messages / TABLEDEF UniAccess for OS 2200 System Administration Guide
TABLEDEF Error Messages
TABLEDEF messages concern problems with either the UAHS Meta Database (MDB) itself or the use of the MDB. The TABLEDEF utility is exercised after the SCHEAMDEF utility has initialized and populated the MDB with pertinent DMS schema information. The messages are displayed on the terminal executing the utility program.
SCHEMADEF error messages have the following format:
*ERROR* [msgcode] msgtext where:
msgcode is the message code listed below
msgtext is the message text listed below
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
1 Unknown CREATE entity: [%s] must be TABLE Reason: Only the CREATE TABLE command is supported. The [%s] is the entity processed. Action: Check the spelling and syntax of CREATE.
2 CREATE TABLE syntax error [%s] Reason: Incorrect syntax. The [%s] is the correct syntax. Action: Correct the CREATE TABLE syntax. (Refer to the Table Definition Entry section of Chapter 14 for the CREATE TABLE format.)
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / TABLEDEF D-61
3 Database not defined: [%s] Reason: The database name specified in the command cannot be found in the MDB. A previous DEFINE DATABASE has not been issued for a database with this name. The [%s] is the offending database name. Action: Check the spelling of the database name or define the database.
4 The table is already defined in this database: [%s] Reason: The table name submitted as part of the CREATE TABLE command already exists. Table names must be unique within a database. The [%s] is the offending table. The table is dropped automatically. Action: Check the spelling the table name, use DROP TABLE to remove table from its associated database in the MDB, or assign the new table a new name.
5 RECORD does not exist in DMS Schema: [%s] Reason: The record name specified in the command does not exist. The record name may have been misspelled. The table is dropped automatically. The [%s] is the offending DMS record. Action: Correct the spelling of the record name.
6 Column definition error [%s] Reason: The keyword of COLUMN is missing. The table is dropped automatically. The [%s] is the offending processed token. Action: Correct the COLUMN definition syntax.
7 The column is already defined in this cable: [%s] Reason: Column names must be unique within a table. The table is dropped automatically. The [%s] is the offending column. Action: Rename the column.
8 Limit of 5 records per table exceeded: %s Reason: UAHS limits the number of DMS records that may be associated with a table. Currently, the maximum number is 5. TABLEDEF has determined that the creation of the table would violate this limit. The table is dropped automatically. The [%s] is offending table. Action: Redefine the table and its constituents.
Release 10R3: October 31, 2005 D-62 Operational Messages / TABLEDEF UniAccess for OS 2200 System Administration Guide
9 Column definition syntax error [%s] Reason: Incorrect syntax. The table is dropped automatically. The [%s] is the correct syntax. Action: Correct the COLUMN syntax. (Refer to the Table Definition Entry section of Chapter 14 for the CREATE TABLE format.)
10 Item: [%s] does not exist in DMS Record: [%s], Column: [%s] Reason: The item name specified in the column definition does not exist in the DMS record. The record name or item name may have been misspelled. The table is dropped automatically. The first [%s] is the offending DMS item. The second [%s] is the offending DMS record. The third [%s] is the offending column. Action: Correct the spelling of the item name.
11 Group-items cannot be defined as columns — Record: [%s], Item: [%s] Reason: UAHS only supports elementary items as columns. The table is dropped automatically. The first [%s] is the offending DMS record. The second [%s] is the offending DMS item. Action: Redefine the table and its columns to use elementary items.
12 Subscript out of range for this DMS Item: [%s] — Subscript value = [%s], Maximum Subscript value = [%s] Reason: The subscript value is bound by the DMS schema item definition. The table is dropped automatically. The first [%s] is the offending DMS item. The second [%s] is the offending subscript. The third [%s] is the maximum subscript value possible. Action: Correct the subscript value to be legal value.
13 Substring not allowed for this field — Item = [%s], Picture clause: [%s] Reason: The substring value is only legal for alpha display fields, that is, PIC X(n) and PIC A(n). The table is dropped automatically. The first [%s] is the offending DMS item. The second [%s] is the offending DMS item picture clause. Action: Remove the substring designation.
14 Substring out of range for this field — Item: [%s], Picture clause: [%s] Reason: The substring value is bound by the DMS schema item definition. The substring value supplied goes beyond the value of the Picture Clause. The
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / TABLEDEF D-63
table is dropped automatically. The first [%s] is the offending DMS item. The second [%s] is the offending DMS item Picture Clause. Action: Correct substring designation to legal values.
15 Unknown DROP entity: %s Reason: An unrecognized DROP entity has been submitted. Legal entities are TABLE, ALL, and DATABASE. The [%s] is the offending DROP entity. Action: Correct the DROP entity name.
16 DROP TABLE syntax error [%s] Reason: Illegal DROP syntax has been submitted. The [%s] is the correct syntax. Action: Correct the DROP TABLE syntax.
17 Table does not exist in database: [%s] Reason: The table name submitted as part of the DROP TABLE command does not exist. The [%s] is offending table. Action: Correct the spelling of table name.
18 DROP ALL syntax error [%s] Reason: Illegal DROP ALL TABLES syntax has been submitted. The [%s] is the correct syntax. Action: Correct the DROP ALL TABLES syntax.
19 Unknown DEFINE entity: [%s] Reason: An unrecognized DEFINE entity has been submitted. Only databases may be defined. The [%s] is the offending DEFINE entity. Action: Correct the DEFINE syntax.
20 DMS SUBSCHEMA not defined Reason: The DMS SUBSCHEMA subclause has been omitted from the DEFINE syntax. Action: Correct the DEFINE syntax.
21 DMS SCHEMA not defined Reason: The DMS SCHEMA subclause has been omitted from the DEFINE syntax. Action: Correct the DEFINE syntax.
Release 10R3: October 31, 2005 D-64 Operational Messages / TABLEDEF UniAccess for OS 2200 System Administration Guide
22 DMS QUALIFIER not defined Reason: The DMS QUALIFIER subclause has been omitted from the DEFINE syntax. The DMS QUALIFIER is required only if the DMS schema does not reside in a TIP file. Action: Correct the DEFINE syntax.
23 DMS FILE not defined Reason: The DMS FILE or DMS TIP FILE subclause has been omitted from the DEFINE syntax. Action: Correct the DEFINE syntax.
24 Unknown subclause to DEFINE command: [%s] Reason: An unrecognized subclause has been included in the DEFINE syntax. The [%s] is the offending sub-clause. Action: Correct the DEFINE syntax.
25 Non-numeric TIP file number: [%s] Reason: The TIP file number must be numeric. The [%s] is the offending TIP file number. Action: Correct the TIP file number.
26 Illegal DMS subclause: [%s], [%s] Reason: An invalid DMS subclause has been included in the DEFINE syntax. The first [%s] is the offending subclause. The second [%s] is the correct syntax. Action: Correct the DMS subclause.
27 DMS schema is not defined: [%s] Reason: The DMS schema cannot be found in the MDB. The [%s] is the offending DMS schema. Action: Correct DMS schema name.
28 DMS schema may not be changed Reason: UAHS only supports one DMS schema in the MDB file. Action: None.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / TABLEDEF D-65
29 Non-numeric subscript: [%s] Reason: Subscripts may be numeric only. The table is dropped automatically. The [%s] is the offending subscript. Action: Correct the subscript to a numeric value.
30 Missing right parenthesis: [%s] Reason: The subscript must be closed by a right parenthesis. The table is dropped automatically. The [%s] is the offending closing token. Action: Correct the subscript to add the right parenthesis.
31 Non-numeric substring: [%s]: [%s] Reason: The substring designations may be numeric only. The first [%s] is the offending first substring designator. The second [%s] is the offending second substring designator. Action: Correct the substring designators to numeric values.
32 Missing right bracket: [%s] Reason: The substring must be closed by a right bracket. The table is dropped automatically. The [%s] is the offending closing token. Action: Correct the substring to add the right bracket.
33 Table name must begin with a letter: [%s] Reason: Table names must begin with an alpha character. The table is dropped automatically. The [%s] is the offending table. Action: Correct the table name to a legal name.
34 TABLEDEF reserved word [%s] not allowed as table name Reason: A table name may not be a TABLEDEF reserved word. Refer to Chapter 14 for the list of TABLDEF reserved words. The table is dropped automatically. The [%s] is the offending table. Action: Correct the table name to a legal name.
35 Column name must begin with a letter: [%s] Reason: Column names must begin with an alpha character. The table is dropped automatically. The [%s] is the offending column. Action: Correct the column name to a legal name.
Release 10R3: October 31, 2005 D-66 Operational Messages / TABLEDEF UniAccess for OS 2200 System Administration Guide
36 TABLEDEF reserved word [%s] not allowed as column name Reason: A column name may not be a TABLEDEF reserved word. Refer to Chapter 14 for the list of TABLDEF reserved words. The table is automatically dropped. The [%s] is the offending column. Action: Correct the column name to a legal name.
37 Illegal character in table name: [%s] Reason: Table name characters are restricted to the following characters: underscore ( _ ), alphabetics (a—z, A—Z) , and numerics (0—9). The table is dropped automatically. The [%s] is the offending table. Action: Correct the table name to legal name.
38 Illegal character in column name: [%s] Reason: Column name characters are restricted to the following characters: underscore ( _ ), alphabetics (a—z, A—Z) , and numerics (0—9). The table is dropped automatically. The [%s] is the offending column. Action: Correct the column name to legal name.
39 Keys will not be used for record: [%s] Reason: During SCHEMADEF processing, a DMS record was processed that exceeded the UAHS supported maximum number of DMS keys for a record or that used a group item as a key. SCHEMADEF marked the record as eligible for inclusion in a table, but its keys may not be used to access the record directly since some key information was lost. The [%s] is the offending record. Action: Redefine the DMS schema to adhere to UAHS DMS key conventions or accept that access to the record will always use the area search and will not use the keys.
40 Incomplete area information captured for record: [%s] Reason: During SCHEMADEF processing, a DMS record was processed that exceeded the UAHS supported maximum number of DMS areas for a record. SCHEMADEF marked the record as ineligible for inclusion in a table since some area information was lost. The [%s] is the offending record. The table is dropped automatically. Action: Redefine the DMS schema to adhere to UAHS DMS area conventions.
Release 10R3: October 31, 2005 UniAccess System Messages Operational Messages / TABLEDEF D-67
41 Unsupported ITEM: [%s] , ITEM-USAGE: [%s], [%s] Reason: A non-supported COBOL item has been included as part of a column definition. UAHS only supports items with a usage of COMP, DISPLAY, COMP-1 and COMP-2 as column data. (Refer to Chapter 9 in the UniAccess for OS 2200 Client Guide for a description of DMS 2200 datatypes supported by UAHS.) The table is dropped automatically. The first [%s] is the offending item. The second [%s] the offending usage code. The third [%s] identifies the offending column and record. Action: Redefine the table to remove the offending column.
42 Table: [%s] has no columns Reason: A table with no associated columns has been created in the MDB. The table is dropped automatically. The [%s] is the offending table. Action: Redefine the table to include the column definitions.
43 The database is already defined in the MDB: [%s] Reason: A database being defined already exists in the MDB. The [%s] is the offending database. Action: Drop the database before redefining it. [or check spelling]
44 Invalid path for table records —Database: [%s], Table: [%s] Reason: A DMS access path does not exist for the DMS records in the table, that is, the DMS records in the table are not related by DMS SETs. The table is dropped automatically. The first [%s] is the offending database. The second [%s] is the offending table. Action: Redefine the table to produce a legal root DMS record.
45 Invalid DMS AREASEARCH — Invalid path for table records —Database: [%s], Table: [%s] Reason: A DMS access path exists for the DMS records in the table, but the default area search record is not at the top or bottom of the DMS hierarchy. Area searches are only legal for DMS paths where the start (root) record is either at the top or bottom of the DMS hierarchy. The table is dropped automatically. The first [%s] is the offending database. The second [%s] is the offending table. Action: Redefine the table to produce a legal root DMS record.
Release 10R3: October 31, 2005 D-68 Operational Messages / TABLEDEF UniAccess for OS 2200 System Administration Guide
80 Incompatible MDB versions [%s] Reason: A TABLEDEF must be exercised against the MDB only when both have the same version (release) level. This error will occur only when new releases of SCHEMADEF and TABLEDEF have been made and the latest versions have not been used to initialize the MDB. The [%s] is the current MDB and TABLEDEF versions. Action: Initialize the MDB with @XQT,I SCHEMADEF. Note that when this done, all tables must be recreated using the TABLEDEF utility.
81 An internal MDB error has been encountered [%s] Reason: The [%s] explains the possible cause. Action: Verify the MDB with @XQT,R TABLEDEF. If this fails, make a copy of the bad MDB for further analysis and re-initialize the MDB with @XQT,I SCHEMADEF. Note that if the MDB is re-initialized, all tables must be recreated using the TABLEDEF utility.
82 Open MDB List File error: [%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.
83 MDB FCSS 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.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-69
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.
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.
The variables listed below are used in message text:
%s string %d decimal number %o octal number
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.
Release 10R3: October 31, 2005 D-70 Server Program Messages UniAccess for OS 2200 System Administration Guide
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 (RDMS 2200) SQL Programming Reference Manual for valid RDMS 2200 SQL syntax and resubmit the SQL command. 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 (RDMS 2200) SQL Programming Reference Manual for valid RDMS 2200 SQL syntax and resubmit the SQL command. 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 (RDMS 2200) SQL Programming Reference Manual for valid RDMS 2200 SQL syntax and resubmit the SQL command. 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.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-71
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.
Release 10R3: October 31, 2005 D-72 Server Program Messages UniAccess for OS 2200 System Administration Guide
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 the command. Applies: UARS only.
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). 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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-73
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). 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 Chapter 4 of the UniAccess for OS 2200 Client Guide for details. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
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 the command. Applies: UARS only.
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.
Release 10R3: October 31, 2005 D-74 Server Program Messages UniAccess for OS 2200 System Administration Guide
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). 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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
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.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-75
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)
Release 10R3: October 31, 2005 D-76 Server Program Messages UniAccess for OS 2200 System Administration Guide
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). 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 for details. Applies: UARS, UAHS, and UAINFO only.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-77
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 of the UniAccess for OS 2200 Client Guide. For UAHS supported commands, refer to Chapters 9 and 10 of the UniAccess for OS 2200 Client Guide. 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 for information about configuring application group information and loading it into UADT. Applies: UARS and UAHS only.
Release 10R3: October 31, 2005 D-78 Server Program Messages UniAccess for OS 2200 System Administration Guide
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. Applies: UARS and UAHS only.
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, refer to Chapter 7 and Chapter 10 respectively of the UniAccess for OS 2200 Client Guide. Applies: UARS and UAHS only.
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 of the UniAccess for OS 2200 Client Guide. For UAHS supported commands, refer to Chapters 9 and 10 of the UniAccess for OS 2200 Client Guide. Applies: UARS and UAHS only.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-79
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.
Release 10R3: October 31, 2005 D-80 Server Program Messages UniAccess for OS 2200 System Administration Guide
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 in the UniAccess for OS 2200 Client Guide 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 in the UniAccess for OS 2200 Client Guide for a list of supported RDMS stored procedure datatype conversions. Applies: UARS only.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-81
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). 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 in the UniAccess for OS 2200 Client Guide for a list of valid UARS RPC requests (Catalog RPCs) and their correct calling sequence. For UAHS, refer to Chapter 11 in the UniAccess for OS 2200 Client Guide. If the request was initiated by the UniAccess ODBC Driver, please report the problem to AIS. Applies: UARS and UAHS only.
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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
Release 10R3: October 31, 2005 D-82 Server Program Messages UniAccess for OS 2200 System Administration Guide
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 valid Reason: 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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
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 session Reason: 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 the list of detailed UAMM error messages, beginning on page D-50, to determine the meaning of particular UAMM error codes. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-83
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 unavailable Reason: 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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
33812 UACS error: Maximum number of concurrent sessions for this application group has been reached Reason: 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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
Release 10R3: October 31, 2005 D-84 Server Program Messages UniAccess for OS 2200 System Administration Guide
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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
33816 UACS error: COMSRV entry (%s) is not configured Reason: 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 for a description of these configuration parameters.) Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
33818 UACS error: (%s) permission is required Reason: 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.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-85
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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
33819 UACS error: Transaction timeout detected (%s), connection aborted Reason: 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). Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
33820 UACS error: Catalog requests not supported by configured language transaction Reason: 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). 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 of the UniAccess for OS 2200 Client Guide). 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 configuration Reason: 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). 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 of the UniAccess for OS 2200 Client Guide). If this is No Language Transaction, the above error will result. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
Release 10R3: October 31, 2005 D-86 Server Program Messages UniAccess for OS 2200 System Administration Guide
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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
33823 Distributed transaction completed. Enlist this session in a new transaction or the NULL transaction Reason: 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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages D-87
33825 Connection terminated - Configured session limit has been exceeded Reason: 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). Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
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. Applies: Any Server-Library transaction, including UARS, UAHS, and UAINFO.
Release 10R3: October 31, 2005 D-88 Server Program Messages / UAHS UniAccess for OS 2200 System Administration Guide
UAHS Error Messages
This section lists, in numeric order, error messages generated by the UniAccess Hierarchical Server (UAHS) transaction and returned to the client application embedded within Server Program Messages. These messages are unique to UAHS. They 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
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
1 Invalid command verb Reason: 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 error Reason: 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.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages / UAHS D-89
3 Internal error Reason: UAHS has encountered an internal error. Action: Contact AIS Technical Support.
4 Select list arithmetic expressions are not supported Reason: 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 supported Reason: As stated. Action: Correct the SELECT request to specify legal select list criteria and resubmit the request.
6 Select list parenthesis are not supported Reason: As stated. Action: Correct the SELECT request to specify legal select list criteria and resubmit the request.
7 Select list signed expressions are not supported Reason: As stated. Action: Correct the SELECT request to specify legal select list criteria and resubmit the request.
8 Only 1 ORDER BY column is supported Reason: UAHS only supports 1 column when producing ordered rows. Action: Correct the SELECT request to specify only 1 ORDER BY column and resubmit the request.
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.
Release 10R3: October 31, 2005 D-90 Server Program Messages / UAHS UniAccess for OS 2200 System Administration Guide
10 Parse stack overflow Reason: 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.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages / UAHS D-91
15 Limit of [%d] tables exceeded Reason: 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 name Reason: 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 unique Reason: 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 column Reason: 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.
Release 10R3: October 31, 2005 D-92 Server Program Messages / UAHS UniAccess for OS 2200 System Administration Guide
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 database Reason: 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.
Release 10R3: October 31, 2005 UniAccess System Messages Server Program Messages / UAHS D-93
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.
Release 10R3: October 31, 2005 D-94 Client Program Messages UniAccess for OS 2200 System Administration Guide
Client Program Messages In the UniAccess System, client program messages are those returned by UniAccess Transaction Client to the Client-Library application. These messages are handled differently than messages from other UniAccess System for OS 2200 products.
Server Messages returned by Client-Library
UniAccess Client-Library returns server error messages from SQL Servers, Open Servers, and the UniAccess Transaction Server or ODBC Server. Server error messages are retrieved with Client-Library’s CTBDIAG function using a SERVERMSG structure. This structure contains two key fields that should be processed by the application program. These fields are:
• SMSG-MSGNO, which contains the error message number from the SQL Server, Open Server, or UniAccess Transaction Server
• SMSG-TEXT, which contains the actual error message text.
For a list of server messages returned by Client-Library, refer to the following sources:
SQL Servers — query and/or print the SQL Server’s SYSMESSAGES table, which contains copies of all the error messages SQL Server can return.
Open Servers —are defined by the application.
UniAccess Transaction Server or ODBC Server — consult the list of Server Program Messages contained in this appendix.
Client Messages returned by Client-Library
Client error messages are generated internally by Client-Library when it detects an error locally. They are retrieved with the CTBDIAG function call using a CLIENTMSG structure. This structure contains two key fields that should be processed by the application program:
• CMSG-OC-MSGNO contains the error message number that was generated locally by Client-Library when it detected an error. CMSG-OC-MSGNO is an encoded field consisting of four bytes. The four bytes are explained below.
Release 10R3: October 31, 2005 UniAccess System Messages Client Program Messages D-95
Byte One. Byte 1 (the high-order byte) represents the Client-Library layer that is reporting the error. Normally, this byte is only used internally by UniAccess Client-Library.
Byte Two. Byte 2 represents the message’s origin and is used internally by UniAccess Client-Library.
Byte Three. Byte 3 denotes the severity of the error. The following table lists the legal values for CMSG-SEVERITY.
Table D-1: Values for CLIENTMSGs CMSG-SEVERITY Field
Value of SEVERITY Meaning
CS-SV-INFORM No error — the message is informational. CS-SV-CONFIG-FAIL Configuration error. CS-SV-RETRY-FAIL An operation has failed, but it can be retried. CS-SV-API-FAIL A Client-Library routine generated an error. This error is typically caused by a bad parameter or calling sequence. The server connection is probably salvageable. CS-SV-RESOURCE-FAIL Resource error. This error is typically caused by an allocation error, a lack of file descriptors, or time-out error. The server connection is probably not salvageable. CS-SV-COMM-FAIL Unrecoverable error in the server communication channel. The server connection is not salvageable. CS-SV-INTERNAL-FAIL Internal Client-Library error. CS-SV-FATAL Serious error. All server connections are unusable.
Byte Four. Byte 4 (the low-order byte) denotes the specific error Client-Library detected.
• CMSG-OC-MSGTEXT contains the error message text.
The text for all client messages generated by Client-Library’s CLIENTMSG structure can be found in the localization file for your language /character set.
Release 10R3: October 31, 2005 D-96 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 E System Tables E UniAccess System Tables
This appendix explains how to modify and maintain the UniAccess System tables SPT_PROCEDURE_COLUMNS and SPT_PROCEDURES. Information in this appendix is relevant to sites using both UniAccess Transaction Server and UniAccess ODBC Server for RDMS 2200.
Sections Page
Overview of AIS-Created RDMS 2200 Tables E-1 UniAccess ODBC Server for RDMS 2200 E-2 Environment UniAccess Transaction Server with ODBC Server for E-2 RDMS 2200 Environment SPT_PROCEDURE_COLUMNS E-3 SPT_PROCEDURES E-6
Overview of AIS-Created RDMS 2200 Tables The primary purpose of the SPT_PROCEDURE_COLUMNS and SPT_PROCEDURES tables is to supply information about site-written UASL transactions to ODBC client applications. Since these are RDMS 2200 tables, they are accessed through the UniAccess Relational Service (UARS).
When the UARS transaction is installed, the installation creates the UNIACCESS1S1 schema. This schema contains numerous tables and views used to support ODBC catalog procedure routines (see Chapter 8 in the UniAccess for OS 2200 Client Guide). Two of the tables, SPT_PROCEDURE_COLUMNS and SPT_PROCEDURES, can be updated by the system administrator using RDMS 2200 SQL commands.
Release 10R3: October 31, 2005 E-2 UniAccess for OS 2200 System Administration Guide
The following sections explain the system administrator’s responsibilities in maintaining and/or updating the tables in various UniAccess environments.
UniAccess ODBC Server for RDMS 2200 Environment
Sites using UniAccess Relational Service without UniAccess Server-Library (UniAccess ODBC Server for RDMS 2200 without UniAccess Transaction Server) should maintain the SPT_PROCEDURE_COLUMNS and SPT_PROCEDURES tables (back up and recover them) as if they were non-updatable RDMS internal tables.
The UniAccess ODBC Server for RDMS 2200 does not allow the creation of Server- Library transactions. Therefore, these sites to not need to update these tables.
Note Information about RDMS stored procedures does not need to be placed into these tables. UARS uses the RDMS tables RDMS_ROUTINES and RDMS_PARAMETERS to obtain information about RDMS stored procedures.
UniAccess Transaction Server with ODBC Server for RDMS 2200 Environment
If the site desires to allow ODBC client applications to request information about Server- Library transactions that can be initiated by ODBC requests, these AIS defined RDMS tables should be updated. To use these tables, the site must have both the UniAccess Transaction Server and the UniAccess ODBC Server for RDMS 2200 (that is, the UniAccess Server-Library and UniAccess Relational Service components must be installed on the OS 2200 host and the UniAccess ODBC Driver installed on the client.)
In addition to the information about RDMS catalog stored procedures that is placed in the tables when they are created, the system administrator can add information about site- written UASL transactions. SPT_PROCEDURES lists the transactions that may process ODBC client applications. The information in the table will be returned by the SQLProcedures ODBC function. SPT_PROCEDURE_COLUMNS defines the list of input and output parameters of a transaction as well as its result set. The information will be returned by the SQLProcedureColumns ODBC function.
Release 10R3: October 31, 2005 UniAccess System Tables E-3
Note An ODBC client can execute any UniAccess Server-Library transaction regardless of the contents of the tables SPT_PROCEDURE_COLUMNS and SPT_PROCEDURES. These tables simply contain information to describe the transaction.
SPT_PROCEDURE_COLUMNS and SPT_PROCEDURES are defined in the sections that follow.
SPT_PROCEDURE_COLUMNS
Schema Name: UNIACCESS1S1
Table Name: SPT_PROCEDURE_COLUMNS
Purpose: Defines the list of input and output parameters. Also defines the columns that make up the result set for the specified procedure that is returned by the SQLProcedureColumns ODBC function.
Definition: See Table E-1.
Table E-1: SPT_PROCEDURE_COLUMNS Definition
Column Name Datatype Comments
PROCEDURE_QUALIFIER CHAR(30) The procedure qualifier identifier. Used as a comment. Will not be searched. NULL is allowed. PROCEDURE_OWNER CHAR(30) The procedure owner identifier. Used as a comment. Will not be searched. NULL is allowed. PROCEDURE_NAME CHAR(30) The procedure identifier. COLUMN_NAME CHAR(30) The procedure column identifier. COLUMN_SEQ_NUM SMALLINT Defines the column sequence within a particular COLUMN_TYPE. Can be used to maintain the correct order of parameters and result set columns. NULL is allowed.
Release 10R3: October 31, 2005 E-4 UniAccess for OS 2200 System Administration Guide
Column Name Datatype Comments
COLUMN_TYPE SMALLINT Defines the procedure columns as parameter or result set columns. 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 The SQL datatype. One of the following values:
1 SQL_CHAR 2 SQL_NUMERIC 3 SQL_DECIMAL 4 SQL_INTEGER 5 SQL_SMALLINT 6 SQL_FLOAT 7 SQL_REAL 8 SQL_DOUBLE 9 SQL_DATE 10 SQL_TIME 11 SQL_TIMESTAMP 12 SQL_VARCHAR -2 SQL_BINARY -3 SQL_VARBINARY -6 SQL_TINYINT -7 SQL_BIT -95 SQL_UNICODE TYPE_NAME CHAR(30) The data-source-dependent datatype name; for example, CHAR, DATE, or TIMESTAMP. PREC INT The precision of the procedure column. NULL should be specified for a datatype where precision is not applicable. LENGTH INT The length in bytes of the procedure column.
Release 10R3: October 31, 2005 UniAccess System Tables E-5
Column Name Datatype Comments
SCALE SMALLINT The scale of the procedure column. NULL should be specified for a datatype where scale is not applicable. RADIX SMALLINT For numeric datatypes, either 10 or 2. If RADIX is 10, the values in PRECISION and SCALE should give the number of decimal digits allowed for the procedure column. If RADIX is not applicable, NULL should be specified. NULLABLE SMALLINT Indicates whether or not the procedure column accepts a NULL value. One of the following values:
0 The procedure column does not accept NULL values.
1 The procedure column accepts NULL values.
2 It is not know whether or not the procedure column accepts NULL values. REMARKS CHAR(254) A description of the procedure column. NULL is allowed. PARAM_SEQ_NUM SMALLINT Defines the order of procedure parameters across all parameter types. This column can be used to specify the absolute order of input and input/output parameters (COLUMN_TYPE of 1 and 2). This ordering is used when the sp_sproc_columns @sequence_params parameter is non-zero. NULL is allowed.
Release 10R3: October 31, 2005 E-6 UniAccess for OS 2200 System Administration Guide
SPT_PROCEDURES
Schema Name: UNIACCESS1S1
Table Name: SPT_PROCEDURES
Purpose: Defines the list of procedures returned by the SQLProcedures ODBC function.
Definition: SPT_PROCEDURES is defined in Table E-2.
Table E-2: SPT_PROCEDURES Definition
Column Name Datatype Comments
PROCEDURE_QUALIFIER CHAR(30) The procedure qualifier identifier. Used as a comment. Will not be searched. NULL is allowed. PROCEDURE_OWNER CHAR(30) The procedure owner identifier. Used as a comment. Will not be searched. NULL is allowed. PROCEDURE_NAME CHAR(30) The procedure identifier. NUM_INPUT_PARAMS INT The number of input parameters. NUM_OUTPUT_PARAMS INT The number of output parameters. NUM_RESULT_SETS INT The number of result sets returned. REMARKS CHAR(254) A description of the procedure. NULL is allowed. PROCEDURE_TYPE SMALLINT 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.
Release 10R3: October 31, 2005 F Troubleshooting F Troubleshooting and Problem Reporting
The troubleshooting section of this appendix can assist you in resolving commonly encountered errors in using UniAccess for OS 2200 environment prior to calling UniAccess Technical Support. The problem reporting section provides information on how to report unresolved problems to UniAccess Technical Support to assist in providing timely problem resolution.
This appendix is organized into the following sections.
Sections Page
Troubleshooting UniAccess F-2 UniAccess Tools for Locating Problems F-2 Post Installation Issues F-3 Configuration Issues F-3 Starting UACS F-5 Transaction Client Issues F-6 UniAccess Server Issues F-7 UniAccess ODBC Server for RDMS 2200 Issues F-11 UniAccess ODBC Server for DMS 2200 Issues F-13 Accessing LINC Data F-13 Debugging UniAccess Programs F-15 Problem Reporting F-16 Diagnostic File Information F-17 Problem Reporting Form F-20
Release 10R3: October 31, 2005 F-2 UniAccess for OS 2200 System Administration Guide
Troubleshooting UniAccess This section contains solutions to common errors encountered using UniAccess in the OS 2200 environment. The section covers the troubleshooting topics listed in the chapter outline on the preceding page. (For information on troubleshooting in UniAccess in the PC environment, see Appendix D of the UniAccess for OS 2200 Client Guide. For the latest knowledge base updates, product release announcements, product-related articles, and online demos, visit our web site at http://www.uniaccess.com.)
UniAccess Tools for Locating Problems
UniAccess provides several methods of helping the system administrator determine the cause of problems that can occur in the UniAccess operating environment.
UniAccess Trace File
A UniAccess trace file provides error, warning, and informational messages. The TRACE commands allow administrators to turn off tracing, turn on, and/or adjust the level of traces, and to close and cycle a trace file. Instructions for adjusting and viewing the trace file can be found on page 19-27.
UniAccess Language Trace File
UniAccess provides a language trace file to assist application developers in debugging their programs. The language trace file captures all language requests submitted to the language transaction. The LANGUAGE commands allow administrators to turn language tracing on or off, and to close and cycle a language trace file. Instructions for adjusting and viewing the language trace file can be found on page 19-7.
UAHS Debug Information
UAHS provides a debug facility to complement the Language Trace File. The Language Trace File, when enabled, 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. See the description of the HIERSRV DEBUG parameter for host configuration information and Chapter 9 of the UniAccess for OS 2200 Client Guide for client-side information.
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-3
UACS Status Information
The STATUS commands display current summary and detailed operating information for a single UACS while it is running. Refer to page 19-10 for information that can be obtained from this keyin.
Post Installation Issues
The following are solutions to commonly reported errors after the installation of UniAccess.
! Problem: After UniAccess has been installed, starting UACS results in the following message: “TSAM Error CM_TCPATTACH failed for PID 0 730612010000.”
Solution: Ensure that you have the UACS TSAM process configured in the CMS or CPComm configuration file.
! Problem: UACS background run causes a COMMON BANK ERROR 9. The BDI that it is attempting to reference is 0402756.
Solution: The BDI 0402756 belongs to TIPUTIL. TIPUTIL must be installed in mode UCS to create the common banks.
! Problem: Corrupt data is being delivered to UniAccess due to CPComm 4R1 not verifying the checksum on IP, TCP, and UDP input packets.
Solution: Apply the fix associated with CPCOMM PLE 18011506, located at: https://www.support.unisys.com. (You will need a userid and password to access this site.)
Configuration Issues
The following are solutions to commonly reported errors in configuring UniAccess.
! Problem: UniAccess 10R3 Product Key Compatibility with ClearPath Systems Running EXEC 46R4, 46R5, or 46R6.
Release 10R3: October 31, 2005 F-4 UniAccess for OS 2200 System Administration Guide
This problem occurs because the UniAccess Product Keys use the MCN (Manufacture Control Number, a.k.a. serial number) on systems that support the Software Controlled Performance (SCF) feature of the EXEC. However, the name of the dynamic configuration parameter that returns the MCN varies on systems running EXEC level 46R4, 46R5, or 46R6, depending upon the changes that have been applied to the EXEC.
Note: This problem does not apply to systems that do not support SCP (i.e., older machines such as the 2200/500).
Solution: This problem is addressed in EXEC PLE 17809229, which calls for applying changes 74845 and 75442 to EXEC levels 46R4 and 46R5, and change 75442 to EXEC level 46R6. (Change 75422 corrects a warning message issued by SOLAR.)
• Sites wishing to run UniAccess on systems that support the SCP feature running EXEC levels 46R4, or 46R5 should install change 00006 74845 PCR, but not 00006 75442 PCR.
• Sites wishing to run UniAccess on systems that support the SCP feature running EXEC level 46R6 should not install change 00006 75442 PCR.
! Problem: After the UniAccess Configuration File has been updated, the change does not take affect.
Solution: Make sure you have processed the UniAccess Configuration File with the proper options. See Table 18-1 in Chapter 18 for the correct procedures to initially execute and reconfigure the UACF processor.
To verify that the changes to UADT have taken effect, use the ‘D’ option on the UACF processor to dump the contents of UADT. To verify that the changes to the COMSRV statement have been processed, use the ‘B’ option on the UACF processor to dump the contents of the UniAccess Configuration File. (Changes to the COMSRV statement require that the appropriate communications server be stopped and re-started.)
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-5
! Problem: The trace file displays the following message: “TIP$SM call [%s] failed [%o] affecting User = [%s], pid = [%d].”
Solution: This error message is documented in the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual. The message indicates an invalid application name. Verify that the APPINF settings are correct in the UniAccess Configuration File.
! Problem: After UACS has been executed, UARS (or any RPC) returns the following message: “[14] Basic Mode CMS call error [cmstor] [400000001006].”
Solution: Verify that the OSPARM SESSCTRL parameter is valid in the UniAccess Configuration File. YES indicates that TIP session control is configured. NO indicates that TIP session control is not configured. Defaults to NO.
! Problem: After UACS has been executed, it returns the following message: “UACS*PID ASSIGN/RELEASE ERROR [42] [12]”.
Solution: UACS Console Message #12 (documented on page D-7) directs the reader to the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual for information on error 42. The section titled TIP/CMS Interfaces of that manual describes error 42 as: “A CMS program has attempted to assign this range of PIDs while it is assigned to some other CMS program.”
Verify that the PID range configured for UniAccess does not conflict with the CMS and MAPPER PIDs.
Starting UACS
The following are solutions to commonly reported errors in running UACS (the UniAccess Communication Server).
! Problem: When UACS is executed, a Basic Mode CMS Call Error [CMINIT] with a status of 4000000000001 is received.
Solution: Verify that MCB is active in the appropriate application group.
Release 10R3: October 31, 2005 F-6 UniAccess for OS 2200 System Administration Guide
! Problem: ST UACS results in: "No product service permissions exist in product key [92] ERROR."
Solution: Verify that the correct value was entered for the product key parameter(s) (UACLPRODKEY, UAHSPRODKEY, UARSPRODKEY, and/or UASLPRODKEY ) of the OSPARM statement. If necessary, update the value(s) in the Site Configuration File; then deactivate and reactivate the UniAccess Fixed-gate. If this does not resolve the problem, please contact UniAccess Support (see page F-16 for contact information.)
The verification of the product key in the Fixed-gate with the product key(s) in the UniAccess Configuration File is a UniAccess security feature.
! Problem: ST UACS results in: "Invalid product key. [94] ERROR."
Solution: UniAccess 10R3 requires a new product key. Update the OSPARM product key parameter(s) in the UniAccess Site Configuration File with the new product key(s); then deactivate and reactivate the UniAccess Fixed-gate.
Transaction Client Issues
The following are solutions to commonly reported errors in the UniAccess Transaction Client environment.
! Problem: UniAccess Transaction Client (UACL) program receives “Receive request failed - library error 31” on a ct_results function call. The identical select statement works using ISQL against SQL Server.
Solution: UAMM Error 31 is the result of a network error (see the UAMM Error Messages on page D-50). Check the UACS trace file for error information. If the UACS trace file indicates a network read time-out error, try increasing the NWRTIMOUT and NWWTIMOUT parameters values. This is particularly an issue if very large or extremely complex requests are being issued.
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-7
! Problem: When an ISQL logon is issued, the following message is received: “ct_connect(); network packet layer: internal net library error: Specified CT-Library call to ct_connect failed.”
Solution: When a user executes ISQL, if the userid check is not bypassed, the userid and server information are immediately validated with the UAUSER and SERVER entries in the UniAccess Configuration File. If either the specified UAUSER or SERVER entries do not exist in the Configuration File, this message will be generated.
! Problem: After logging in using @ISQL, the following message is displayed: “CT_CONNECT() network packet layer: internal net library error: specified server name attribute could not be found.”
Solution: Verify that the server environment has been successfully configured in the UniAccess Configuration File. The SERVER configuration statement defines the server to which a client application will connect. This name is case sensitive and must match the server name specified on the @ISQL call as well as in the interfaces file. (See page 16-65 for a description of the SERVER configuration statement.)
UniAccess Server Issues
The following are solutions to commonly reported errors in a UniAccess server environment. UniAccess servers include the UniAccess Transaction Server, the UniAccess ODBC Server for RDMS 2200, and the UniAccess ODBC Server for DMS 2200. This section first lists solutions to reported errors common to all three environments. Then solutions to reported errors in specific UniAccess server environments are listed.
! Problem: If the RELSRV WAITTIME or HIERSRV WAITTIME parameters are set to a non-zero value, the language transaction may appear to stall until the RELSRV or HIERSRV WAITTIME expires. UniAccess Server-Library programs using the high performance logic may appear to stall until the wait time specified when TDINIT is called expires. The apparent stall of the UniAccess Server-Library or language transaction may cause the client application to indicate that the server has timed out.
Release 10R3: October 31, 2005 F-8 UniAccess for OS 2200 System Administration Guide
Solution: The resolution for the apparent transaction stall is to change the VALTAB to indicate that the transaction should run in TIP-memory-compatible mode. This is specified by the O option in the VALTAB indicator field. For additional information please see the Unisys OS 2200 Transaction Processing Administration and Operations Reference Manual that corresponds to the System Base installed on your system.
For better performance, the VALTAB program type for the language transaction should be reentrant (PRG,3), and the FLAGBOX bit for STICKING should be set (FB ON STICKING). Additional performance gains can be made by making the transaction a resident transaction. Resident online programs (RTPS feature) are loaded either by TP keyin or RPINIT utility request.
! Problem: RPCs receive an error when an update is attempted. The UACS trace file indicates the following: “[14] Basic mode CMS call error [cmstor] [400000072006].”
Solution: This error indicates invalid message/program options. Check the VALTAB settings for the RPCs, particularly the REC option. If recovery is not configured in the EXEC, make sure this option has the value of NONE.
! Problem: The UniAccess trace file occasionally displays a TSAM error 030612000004: “Error Indication Received From TCP.”
Solution: This indicates that, although everything is set up properly, CMS or CPComm could not get a message to the destination. The problem could be with a router or getting to a router. Run a sniffer on the line and determine where the errors are.
! Problem: The following error appears in the UniAccess Trace file: “Failed in function [mmopen] in UAMM, pid [pid #], other info [7] in trace file”.
! Solution: This error indicates that a PID is not able to initiate with UAMM (i.e., mmopen). Any attempt to open a PID will result in a UAMM error 7, which is unable to allocate a MMPROC. There are two situations that can cause a UAMM process (mmproc) to hang:
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-9
• If UniAccess aborts the connection and does not receive an abort confirm [see the Unisys OS 2200 Communications Management System (CMS 1100) Programming Reference Manual or the Unisys Cooperative Processing Communications Platform (CPComm) Programming Reference Manual] , the PID and mmproc will remain busy. Some cases in which UniAccess will attempt to abort the connection are when a PID is terminated with the operator keyin (UACS TERM PID,
• If a transaction errors without the UniAccess contingency routine getting control, the mmproc will remain busy. (For example, a transaction may error prior to connecting to the UniAccess Fixed- gate subsystem--UAFG.) If this situation occurs, a print file should be created for the erring transaction.
Since the UAMM process slots are maintained in UAFG, they are not released when UACS is terminated. Therefore, hung mmprocs can collect over time. The only way to release the hung mmproc is by deactivating the UniAccess Fixed-gate subsystem and reloading it. (See page 6-7 for information on activating and deactivating UAFG and page 6-12 for information on reinitializing UAFG following a UAFG deactivation.)
Note that the number of UAMM process slots is defined by the PROCCNT parameter of the UAMM configuration statement.
! Problem: A UACS TERM PID,
Solution: The following scenarios can lead to a PID being placed into an ERROR state that will not be automatically resolved:
• UACS successfully schedules the transaction, but the transaction does not execute.
• UACS successfully schedules the transaction, but the transaction error terminates prior to performing the TDINIT call. When the
Release 10R3: October 31, 2005 F-10 UniAccess for OS 2200 System Administration Guide
transaction errors prior to performing the TDINIT call, the UniAccess Fixed-gate subsystem has not been registered for contingency notification and, therefore, must assume that the transaction is still active.
Execute the TERM PID,
! Problem: There are a number of situations that may result in hung PIDs. The hung PID may initially be identified as a problem connecting additional client applications or as the result of a UACS STATUS keyin. The most common of these situations are:
• UACS TERM PID,
• UACS successfully schedules a UASL transaction, but the transaction does not execute.
• UACS successfully schedules a UASL transaction, but the transaction error terminates prior to performing the TDINIT call.
• The client application terminates without notifying the server.
Solution: Both the client and server side of a UniAccess transaction must be closed to release a PID. There are a number of configuration parameters that can detect a potentially hung PID and automatically resolve the problem. These parameters are:
• CONTIMOUT on the COMSRV statement
• KEEPALIVE on the COMSRV statement
• NWRTIMOUT on the COMSRV statement
• NWWTIMOUT on the COMSRV statement.
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-11
When it becomes necessary to terminate a PID using the UACS TERM PID,
The UniAccess Trace File, with traces on HIGH, will provide information that is useful in determining the cause of hung PIDs.
UniAccess ODBC Server for RDMS 2200 Issues
The following are solutions to commonly reported UniAccess server errors specific to the UniAccess ODBC Server for RDMS 2200 environment. See the preceding section UniAccess Server Issues for other reported errors.
! Problem: UniAccess Relational Service Transaction (UARS) does not receive RDMS table information when used with RDMS 12R2, 13R1, 13R1A, or 14R1. In addition, Open Client applications may intermittently display an error message "EX 26270 Table, Qualifier, version, schema and storage-area may not contain leading or embed blanks".
Solution: The resolution is to apply the changes associated with PLE 18167832, "Various problems when using LIKE with embedded SQL," located at: https://www.support.unisys.com. (You will need a userid and password to access this site.)
! Problem: UARS transaction receives an out-of-memory error (RDM error 50000).
The VALTAB O indicator option causes the UARS transaction to run in TIP-compatible-memory. The EXEC prevents the attempts to expand or contract application level backs for transactions in "TIP memory".
Solution: Any of the following will resolve the problem.
• Apply the changes associated with EXEC PLE 17074075.
• Move to EXEC level 45R2A, or later. EXEC level 45R2A is supplied with SB7.1 and HMP-IX3.1.
Release 10R3: October 31, 2005 F-12 UniAccess for OS 2200 System Administration Guide
• Remove the O indicator option from the UARS VALTAB and set the RELSRV WAITTIME to zero (0).
! Problem: 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 deleted manually before attempting to recreate the table. Implicit storage area creation can be overridden by specifying a Storage Area when a UniAccess data source is configured. This storage area must be created by the OS 2200 system administrator before any table creation commands can be issued. All tables that are created using the UniAccess data source will be placed in the storage area specified in the Storage Area field. 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.
! Problem: UARS receives the following message: "APP x DCS EX 20120 This run is not configured in UDS to pass a caller certified user-id. The BEGIN THREAD command is ignored."
This error will occur when TIP session control is not active and MASTER- RUN-USERID does not equal @@@@@@@@@@@@.
Solution: Use @DD to update the UREP Configuration MASTER-RUN-USERID attribute in the application group that UARS is executing to “@@@@@@@@@@@@”. (See page 4-10 for information on updating the UREP configuration MASTER-RUN-USERID attribute.)
! Problem: Table or column information is not being returned to the ODBC client.
Solution: When UREP is installed, it defaults to partial options set for RDMS. If this is the case, table and column names will not be maintained. The runstream UNIACCESS/CREATE (beginning with UniAccess 7R1) or UASCHEMA/BUILD (for UniAccess levels prior to 7R1) modifies the repository to capture complete table information for all future tables created. These runstreams are located in the file SYS$LIB$*UAUTIL
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-13
(or SYS$LIB$*UAUTILT for test mode installations). However, any tables created prior to adding this runstream are not automatically updated in the repository. To update the repository with the complete table information, perform the following:
@DD,E,appname PROCESS TABLE tablename FOR SCHEMA schemaname ATTACH.
Note that if there are foreign key relationships between tables, you must ATTACH the parent table first.
UniAccess ODBC Server for DMS 2200 Issues
The following are solutions to commonly reported UniAccess server errors specific to the UniAccess ODBC Server for DMS 2200 environment. See the preceding section UniAccess Server Issues for other reported errors.
! Problem: Attempts to access DMS data result in an error message “UA service DMS error (23 - DMS DML error [%s]).” The error text [%s] indicates that a DML error 008, 105, 107, 108, 117, 118, 119, 122, 137, or 140 occurred.
Solution: The most likely cause of these errors is that the DMS schema has been modified without reprocessing the trivial subschema via SDDL and the schema via SCHEMADEF, and without recreating the tables via TABLEDEF.
Accessing LINC Data
The following are solutions to commonly reported problems in accessing LINC data.
! Problem: RDMS tables created by LINC commonly include a column (GLB_DTIME) that is incorrectly defined to RDMS. The column GLB_DTIME is used by LINC to join tables and profiles. The column is generally of no value to a client application.
The RDMS definition of this column is CHARACTER. The data is actually a 72 bit binary value. Attempts to retrieve this column are likely to cause an
Release 10R3: October 31, 2005 F-14 UniAccess for OS 2200 System Administration Guide
error. The error encountered will vary depending upon the content of GLB_DTIME.
Solution: Do not retrieve the column GLB_DTIME using UARS. UARS will describe the column using the RDMS definition, which is incorrect.
Create views of the LINC generated RDMS tables without the column GLB_DTIME and have the users access the views and not the underlying table in order to prevent accidental attempts to retrieve this column. The VIEWS function of the LINC Runtime Utility will build elements that will create or drop views. For additional information, please see the Unisys OS 1100 LINC II Installation and Operations Guide.
You can output the column GLB_DTIME from a UASL transaction by describing the column as a datatype that will hold the 72 bit binary value.
! Problem: Access to RDMS tables created by LINC is very slow if a profile is not being used.
Solution: Create a view that will join the table and the profile. The VIEWS function of the LINC Runtime Utility will build elements that will create or drop views. For additional information, please see the Unisys OS 1100 LINC II Installation and Operations Guide.
For example, if TABLE1 exists with a single key GLB_DTIME and the profile TABLE1P exists with an index on EMPLOYEE_ID, the following view would allow access to data in TABLE1 using the index from TABLE1P. CREATE VIEW EMPLOYEE_INFO (NAME, EMPLOYEE_ID, POSITION)AS SELECT TABLE1.NAME, TABLE1P.EMPLOYEE_ID, TABLE1.POSITION WHERE TABLE1P.GLB_DTIME=TABLE1.GLB_DTIME
TABLE1 TABLE1P
GLB_DTIME GLB_DTIME NAME EMPLOYEE_ID EMPLOYEE_ID POSITION
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-15
! Problem: LINC documentation explicitly states in multiple locations that you must not use other tools to update your OS 1100 LINC II database, as this may lead to corruption of your LINC system. However, the views used to provide efficient access to LINC data contain two tables. RDMS does not allow views containing more than one table to be updated. How can data in RDMS tables created by LINC be updated?
Solution: The correct procedure to update your LINC database is to write a Server- Library transaction that will initiate your existing LINC logic. It is possible to write a Server-Library transaction to directly update the LINC database. Note Extreme caution should be used if you decide to update your LINC database using dynamic SQL.
Debugging UniAccess Programs
The following steps will provide additional diagnostic information to assist in debugging programs using the UniAccess System.
1. Turn UACS tracing on high and review the contents of the trace file after executing the failed program. The trace file will contain error, warning and informational messages to assist in debugging. The list of all Trace File messages begins on page D-2.
2. If ODBC calls are being issued, the UADriver Tracing utility (started in the ODBC Administrator) provides a method for logging function calls and function results between an ODBC application and the UniAccess ODBC Driver. UADriver tracing is described in Appendix D of the UniAccess for OS 2200 Client Guide.
3. If distributed transactions are being issued, the UADTC log file provides valuable information regarding the interaction between UADTC and MSDTC. The UADTC log file has 3 settings for capturing this interaction: Low, Medium, and High. The UADTC logging is described in Appendix D of the UniAccess for OS 2200 Client Guide.
4. Review the sequence of library calls to ensure that they are in the proper order. Typically, commands that are not in the correct sequence will result in a return
Release 10R3: October 31, 2005 F-16 UniAccess for OS 2200 System Administration Guide
code indicating the incorrect state. However, a valid state that is different from the expected state may return unexpected results.
5. Review the program to ensure that the return status is checked after every library call. A bad return code from one library call can result in an error on subsequent calls.
6. Ensure that parameters are properly aligned. Including the debug version of the appropriate stub will verify correct alignment (UACLSTUBDBG/OBJ, UASLSTUBDBG/OBJ, or UASLSTUBDBG/REL).
7. Identify the statement causing the error and verify that all of the parameters contain the expected values prior to the call. DISPLAY or PRINTF statements are typically used in debugging. PADS can be to debug programs.
If the problem still cannot be resolved, please provide as much information as possible when reporting the problem to Applied Information Sciences, Inc. The form on page F-20 identifies the information that may be required to resolve a problem.
Problem Reporting Applied Information Sciences, Inc. makes every effort to ensure that UniAccess for OS 2200 is delivered bug free. However, if you encounter a problem, we will attempt to determine the cause and provide a resolution. The information requested in the Problem Reporting Form (page F-20) will assist us in providing timely problem resolution.
Problems can be reported via Email, fax, telephone, or mail.
E-mail: [email protected]
Fax: (703) 860-7820
Telephone: (703) 860-7808
Mail and overnight delivery: UniAccess Support Applied Information Sciences, Inc. 1850 Centennial Park Drive Reston, VA 20191
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-17
Diagnostic File Information
When an error occurs within the Fixed-gate subsystem, AIS will require a copy of the program as it existed in memory after execution (the DIAG$ file) and information regarding the Bank Descriptor Indices (BDIs) assigned to the banks within the UniAccess Fixed-gate subsystem. • To obtain the DIAG$ file, please refer to the section Reporting Problems with Demand and Batch Programs or Reporting Problems with Transaction Programs in this chapter.
• To obtain information regarding the BDIs assigned to the banks within the UniAccess Fixed-gate Subsystem, please execute the Unisys utility program SSINFO. The following example shows how to call SSINFO.
@ssinfo,1 uniaccess
For additional information on SSINFO, please see the Unisys OS 2200 Linking System Subsystems Programming Guide.
Reporting Problems with Demand and Batch Programs
For demand and batch programs, the DIAG$ file can be copied immediately after the program execution, or created by attaching a use name of DIAG$ to any write-enabled file on the system. The following ECL sections are examples of saving the DIAG$ file for later examination.
Example 1
@cat,p savefile.,///1000 @xqt file.program @copy diag$.,savefile.
Example 2
@free diag$.. Free system DIAG$ @cat,p mydiag$file(+1).,///1000 . Create a file @use diag$.,mydiag$file.. Use it for DIAG$ @asg,a diag$..
Release 10R3: October 31, 2005 F-18 UniAccess for OS 2200 System Administration Guide
@xqt file.program. @free diag$.. Don't overwrite @asg,t diag$.,///1000. Temp DIAG$
Reporting Problems with Transaction Programs
A diagnostic file can be created for a TIP Transaction that terminates in error by setting either the T or Z option on the VALTAB OPT parameter and by setting the FLAGBOX bit TIPTRACE.
Processing UACS Dumps
The standard UACS runstream catalogues the DIAG$FILE and executes the UACS object module from TPFS. The catalogued DIAG$FILE can be analyzed using PADS. If a copy of the UACS object module is available in TPF$ when PADS is called, PADS will use the copy to resolve addresses, which will assist in problem analysis.
In some situations, additional diagnostic entries will be written to the DIAG$FILE. If a canned a runstream or addstream is used to process the PADS dump, it should be designed to handle twice as many diagnostic entries as there are UACS activities. If a DIAG$FILE contains fewer diagnostic entries than the runstream is attempting to process, PADS will continue processing after issuing the following message:
*E7117 There is no 'prior' activity in the DIAG file.
The sample PADS runstream can be used to process a UACS DIAG$FILE for a COMSRV that is using the default number of activities (TIPQCNT and TSAMCNT).
Sample PADS runstream
@RUN UACSD,0,UNIACCESS @ . ************************************************************* @ . @ . The standard UACS runstream catalogues the DIAG$FILE and @ . executes UACS from TPF$. @ . @ . This runstream copies the UACS zoom to a temporary SYS$*TPF$ @ . so PADS will use the copy in SYS$*TPF$ to resolve addresses @ . @ . Please be sure to change SYS$LIB$*UAUTIL to SYS$LIB$*UAUTILT
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-19
@ . if you are using a mode C or D install. @ . @ . Since UACS has multiple activities, the PADS statement @ . SELECT PRIOR DIAG$ ENTRY @ . must be performed to capture the contingency information for @ . each activity. UACS has a minimum of 4 activities. @ . Additional activities are started based on the values of the @ . TIPQCNT and TSAMCNT parameters of the COMSRV configuration @ . statement @ . @ . The following should be updated to reflect: @ . 1. The EXEC file name containing the UACS zoom @ . 2. The EXEC file name containing the DIAG$FILE @ . 3. The number of select prior diag entries should be @ . equal to: @ . (2 * TIPQCNT) + (2 * TSAMCNT) + 2 @ . 4. The number of dump$wback$ entries should be equal to: @ . (2 * TIPQCNT) + (2 * TSAMCNT) + 3 @ . ************************************************************* @ . @FREE TPF$. . @ASG,T SYS$*TPF$.,F/200//500 @COPY,A SYS$LIB$*UAUTIL.UACS,SYS$*TPF$. @PADS DIAG,UACS*DIAG$FILE. dump$wback$ select prior diag entry dump$wback$ select prior diag entry dump$wback$ select prior diag entry dump$wback$ select prior diag entry dump$wback$ select prior diag entry dump$wback$ select prior diag entry dump$wback$ diag$ @FIN
Release 10R3: October 31, 2005 F-20 UniAccess for OS 2200 System Administration Guide
Problem Reporting Form
Site Name: ______Contact Name: ______Phone Number: ______E-mail Address: ______Tracking Number ______
Description of the problem: ______
Component exhibiting the error: ______UACS ______UniAccess Transaction Client ______UniAccess Transaction Server ______UniAccess ODBC Server for RDMS 2200 ______UniAccess ODBC Server for DMS 2200 ______UADTC ______ISQL ______UADriver ______unknown
Release 10R3: October 31, 2005 Troubleshooting and Problem Reporting F-21
OS 2200 Series Software levels: UniAccess Level: ______EXEC Level: ______MCB Level: ______RDMS Level: ______UREP Level: ______URTS Level: ______CMS Level: ______CPComm Level: ______System Base: ______
For problems encountered in UACS, list any PCRs applied to CMS or CPComm: ______
If the error is encountered using a program that accesses the UniAccess Transaction Client or the UniAccess Transaction Server, please indicate the following: Compiler (e.g., UCOB):______Compiler Level: ______
If you are using UniAccess Transaction Client, please describe your server environment: Operating System: ______Hardware: ______Server Type (e.g., MS SQL Server): ______Server Level: ______
Release 10R3: October 31, 2005 F-22 UniAccess for OS 2200 System Administration Guide
If you are using UniAccess Transaction Server or UniAccess ODBC Server, please describe your client environment: Operating System: ______Hardware: ______Client Application: ______Client Application Level: ______Custom Application Language: ______Compiler/Interpreter Level: ______UADriver Level: ______
Indicate which, if any, additional information you have included: ______Processed DIAG$ File ______Program Listing ______Program Source ______UACS Trace File ______UAHS Debug Information ______UniAccess Configuration File ______UADriver Trace File ______UADTC Log File ______other
Release 10R3: October 31, 2005 G References G 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.
Topics Page
AIS References G-1 Microsoft References G-2 Sybase References G-2 Unisys References G-2
AIS References UniAccess 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.
Release 10R3: October 31, 2005 G-2 UniAccess for OS 2200 System Administration Guide
Microsoft References For 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 References For 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 References The 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.
Release 10R3: October 31, 2005 References G-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.
Release 10R3: October 31, 2005 G-4 UniAccess for OS 2200 System Administration Guide
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.
Release 10R3: October 31, 2005 References G-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.
Release 10R3: October 31, 2005 G-6 UniAccess for OS 2200 System Administration Guide
Release 10R3: October 31, 2005 Glossary H 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.
ASCII COBOL interface. Translation routines from the basic mode environment to the extended mode environment that allow basic mode ASCII COBOL programs to use the extended mode UniAccess Fixed-gate subsystem.
Release 10R3: October 31, 2005 H-2 UniAccess for OS 2200 System Administration Guide
ATMCA. (Asynchronous Transfer Mode Channel Adapter). The ATM Channel Adapter (ATM CA) provides access to an ATM network for Unisys CSBus II/III capable hosts. Connection of the ATM CA to the network is made through a local (private) switch. In the context of this manual, the ATMCA and a router connect the UniAccess System on the OS 2200 host to the LAN on which clients and SQL Servers reside. 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. 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.
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. character set. A set of specific (usually standardized) characters with an encoding scheme that uniquely defines each character. ASCII and ISO 8859-1 (Latin 1) are two common character sets. character set conversion. Changing the encoding scheme of a set of characters on the way into or out of a server. Conversion is used when a server and a client communicating with it use
Release 10R3: October 31, 2005 Glossary H-3
different character sets.
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. 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. (See also CPComm.)
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. common bank. A bank that resides in the OS 2200 host’s common address space, which enables multiple applications to share the same software modules. Use of common banks saves memory since multiple applications do not have to load their own copies of commonly used software modules. 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.
Release 10R3: October 31, 2005 H-4 UniAccess for OS 2200 System Administration Guide
These commands are used to manage and derive status information from UACS.
CPComm (Cooperative Processing Communications Platform). A high-performance alternative to CMS 1100 software. CPComm connects application programs in an OS 2200 environment with end users and peer applications over a data communications network. Unlike CMS 1100, CPComm enables applications to take advantage of the queuing architecture of newer 2200 systems. The queuing architecture can result in faster throughput, especially for applications that send or receive large messages or a large number of messages. (See also CMS 1100.)
D
data definition command. (See TABLEDEF data definition command.)
datatype. A defining attribute that describes the values and operations that are legal for a variable.
DCP (Distributed Communications Processor). A front-end processor (FEP) acting as an intermediate network node or as a remote concentrator. It contains the software (Telcon) that provides network communication in a Distributed Communications Architecture (DCA) network.
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
Release 10R3: October 31, 2005 Glossary H-5
2200 databases. UAHS translates SQL to DML.
DMR (Data Management Routine). The DMS online management routine that accesses and updates the DMS database.
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.)
E
elementary item. A data item that does not have subordinate items. It has a PICTURE and/or USAGE clause that defines a datatype.
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.
Ethernet CA (Channel Adapter). The Ethernet channel adapter enables hosts using a channel service bus to interface directly to an industry-standard 802.3 LAN. The channel adapter implementation conforms to the applicable domestic and international 802.3 standards. In the context of this manual, the Ethernet channel adapter connects UniAccess System on the OS 2200 host to the LAN on which clients and SQL Servers reside.
Release 10R3: October 31, 2005 H-6 UniAccess for OS 2200 System Administration Guide
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.
front-end processor. A specialized computer whose function is to offload many of the data communications functions from the host computer, thus enabling the host to commit more of its resources to data processing. Front-end processors typically perform a variety of functions, including routing messages and multiplexing input from terminals into a single stream to the host.
H
hierarchical database. A data model or database that represents entities as owner-member record structures. (Contrast with relational database.)
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.
HVTIP transaction. A specialized technique used for applications requiring a high rate of throughput, and whose processing of a transaction may pass through an arbitrary sequence of subprograms.
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
Release 10R3: October 31, 2005 Glossary H-7
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.
Integrated Recovery Utility (IRU). The standard OS 2200 processor that coordinates or performs all aspects of OS 2200 application group recovery.
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).
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
Release 10R3: October 31, 2005 H-8 UniAccess for OS 2200 System Administration Guide
LAN (Local Area Network). A private network with a limited geographic range, typically a single building or campus. Individual computers attach to the LAN to communicate with each other and, in the context of the UniAccess documentation, with the OS 2200 system. 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. link. The process of executing a linkage editor to create an executable program. 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
Release 10R3: October 31, 2005 Glossary H-9
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.) multi-level table. A UAHS table defined from more than one DMS record and the sets related to it. (Contrast with single-level table.)
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.
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.) operational message. Any error that is generated by a UniAccess System component but not
Release 10R3: October 31, 2005 H-10 UniAccess for OS 2200 System Administration Guide
returned to a client application.
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.
processor. Any program executed using the syntax @,program-name. A processor has the ability to obtain parameters from the @
product key. A customer-specific string provided to each UniAccess customer. It activates the
Release 10R3: October 31, 2005 Glossary H-11
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. real time. A mode of operation in which the system’s response to input is immediate. In the real- time mode, the program generally has exclusive use of a processor.
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.
Release 10R3: October 31, 2005 H-12 UniAccess for OS 2200 System Administration Guide
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.
RTPS (Resident Transaction Program System). A TIP feature that allows transaction programs to be loaded and permanently stuck in real-time position in main storage. The program can then process incoming transactions without constant program reloading. (See TIP.)
S
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.)
SDDL (Subschema Data Definition Language). The DMS processor and language used to define subschemas.
SDF images (System Data Format). OS 2200 file format that can contain ASCII data.
Release 10R3: October 31, 2005 Glossary H-13
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.
single-level table. A UAHS table defined from a single DMS record. (Contrast with multi-level table.)
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.)
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.)
Release 10R3: October 31, 2005 H-14 UniAccess for OS 2200 System Administration Guide
Step control. The OS 2200 recovery component that uses queues and queue items to record and update the current state of all programs accessing the database within a recoverable application group. Step control provides central control information for the other recovery components.
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.)
TABLEDEF data definition command. A command used to define the relational-type items that will be accessible to client applications using the UAHS service. These commands essentially map DMS hierarchical entities to relational counterparts in the 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.
Telcon. The DCP communications software product that performs most of the communications processing tasks of a DCA network. Telcon software provides wide area network management functions and enables the DCP to connect to a host, to other DCPs, to terminals, to remote concentrators, and to other communications devices.
Release 10R3: October 31, 2005 Glossary H-15
TICRI. The absolute element UDS$TCLCDICR contains the table control intercept and connect routine (TICRI). UDS intercept and control routines (ICRs) link user programs with UDS Control code. ICRs examine user requests entering UDS Control and obtain information about the existing thread environment. Specifically, ICRs perform the following tasks: (1) direct the user program call to the UDS code; (2) post all user call parameters into the UDS environment.
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
Release 10R3: October 31, 2005 H-16 UniAccess for OS 2200 System Administration Guide
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. trivial subschema. A subschema that includes the entire database.
TSAM (Transport Service Access Method). A program interface that allows user-written applications to access the communications services of CMS 1100 at the transport layer. TSAM provides access to CMS 1100 DCA and TCP/IP protocol stacks.
TSAM keep-alives. A CMS TSAM feature that periodically probes the other end of an idle TCP connection. If the other end of the connection fails to respond after the configured number of probes, it is assumed that the connection has been abandoned. Abandoned connections are automatically aborted. 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.)
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. (See also UAHS TIP file.)
Release 10R3: October 31, 2005 Glossary H-17
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.
UAHS TIP file. The TIP file containing the UAHS Meta Database. (See also UAHS Meta Database).
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
Release 10R3: October 31, 2005 H-18 UniAccess for OS 2200 System Administration Guide
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.)
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 that act together as a server on the OS 2200 host, and the UniAccess ODBC Driver for client workstations.
Release 10R3: October 31, 2005 Glossary H-19
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
Release 10R3: October 31, 2005 H-20 UniAccess for OS 2200 System Administration Guide
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-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.
VINDEX. The VALTAB index table, which allows the system to locate the VALTAB entry associated with a transaction code.
Release 10R3: October 31, 2005 Index I Index ......
Numerics UAHS performance optimization 8-11 2PC (two-phase commit) use in data retrieval for UAHS 14-32 definition 15-3 ASCII COBOL level recommended 3-7 A ASCII COBOL interface activity configuring 4-15 configuration relationships B-11 in UASL 1-9 Adaptive Server Enterprise—ASE installing 4-15 (see Sybase SQL Server) Audit control APPINF (configuration statement) description 15-6 description 16-10 UAHSTIPF 5-6 B application basic mode definition xxi ASCII COBOL interface 1-9 development 2-1 batched SQL statements application groups processing with translation routines 12-8 adding a UACS 18-10 BDI (bank descriptor index) adding another UACS 18-7 (see MCBBDI, UDSBDI) characteristics defined 5-5 BEGIN TRAN (see user-defined transactions) defining 16-10 BLOBs recovery of 15-7 setting maximum blobsize 16-55, 16-86 variable relationships B-9 blocked PIDs Applied Information Sciences managing 16-20 copyright information 0-ii references G-1 C area searches cabinet numbers allowing for UAHS 16-38, 16-83 configuring 16-13 limiting 14-32 CABNUM (configuration statement) description 16-13
Release 10R3: October 31, 2005 I-2 UniAccess for OS 2200 System Administration Guide
CALC keys client applications use in keyed fetches 14-30 general discussion 2-6 Cannot Notify Aborted state remote 2-6 of distributed transaction participants 15-4 returning messages to 10-1 Cannot Notify Committed state UniAccess Transaction Client 2-9 of distributed transaction participants 15-4 client messages catalog RPCs fields D-94 map records for 16-60 client requests supported by AIS defined tables E-1 comparison 2-3 UAHS support for UADriver 14-2 direct vs. indirect 2-4 use with translation routines 12-9 language requests 2-2 for UAHS 12-11 RPCs 2-2 for UARS 12-9 client users character set preparation checklist 7-1 defining 16-14 values required by 7-6 double-byte conversion 12-3 Client-Library Kanji characters (see also UACL) presenting 12-3 error messages D-95 of localization files 16-42 CLIENTMSG translation definition 16-76 CMSG-SEVERITY values D-95 character strings clients altering with translation routines 12-9 definition xxi, 1-2 integer datatypes converted to types of 1-5 for UARS 16-53, 16-84 client/server architecture returning as ODBC SQL_UNICODE advantages of 1-4 16-53, 16-84 general discussion 1-2 character strings, long model 1-3 returning as ODBC client/server components SQL_LONGVARCHAR 16-54, 16-85 remote 1-14 returning error messages 16-20 CMS 1100 truncating 16-20 acknowledging connection failure 19-2 CHARSET (configuration statement) acknowledging loss for UACS 19-2 description 16-14 configuration example B-6 ClearPath IX level required 3-6 allowable Unisys system for UniAccess 3-6 test mode installation for 4-7 memory utilization 8-16 used by UACS 1-18 use with UniAccess 1-16 used by UniAccess System 1-16
Release 10R3: October 31, 2005 Index I-3
Collector CPComm level recommended 3-8 acknowledging connection failure 19-2 communication link protocols acknowledging loss for UACS 19-2 for the UniAccess System 1-15 configuration example B-16 communications services level required 3-6 (see CMS 1100, CPComm) linking UACS to at installation 4-9 COMSRV (configuration statement) used by UACS 1-18 description 16-16 used by UniAccess System 1-16 PRIORITY 8-2 CP-IX TIPQCNT 8-2 requirement 3-6 TSAMCNT 8-2 CTBDIAG UACSTYPE 5-5 retrieves server messages for Client- UARSTRAN 8-8 Library applications D-94 configuration of OS 2200 components D example B-3 data definition entries overview 5-1 database definition entry 14-44 relationship tables B-9 deleting mappings 14-47 requirements checklist 5-3 reserved words 14-48 troubleshooting F-3 rules 14-43 UniAccess System B-1 table definition entry 14-45 configuration file data management systems (see UniAccess Configuration File, see also (see also RDMS 2200, DMS 2200) Site Information File, UA Information available through UniAccess 1-17 File) database performance 8-4 configuration statements DCP effected by reconfigurations 18-2 configuration B-17 format of 16-2 debug tracing (UACS) list of UniAccess statements 16-8 command 19-27 notation conventions 16-7 debug tracing (UAHS) summary of statement requirements 16-94 configuring 16-38, 16-83 console commands description F-2 format 19-4 debugging from remote consoles 19-4 UniAccess Programs F-15 help 19-6 deferred updates 8-5 listed 19-4 direct client requests 2-4 control characters distributed transaction ID conversion by UAHS 16-39, 16-89 (see transaction ID) conversion by UARS 16-56, 16-89
Release 10R3: October 31, 2005 I-4 UniAccess for OS 2200 System Administration Guide
distributed transactions E (see also UADTC, UAIR) error messages allowing clients to participate 16-84 (see messages) definition xxii UniAccess Transaction Server D-69 discussion 15-1 ERs (executive requests) 9-9 participating UASL transactions EXEC configuration manual intervention 15-4 example B-7 recovery of 15-3 for each application group 3-12 sample program C-12 level required 3-7 statistical information returned by security issues 9-1 UACS 19-16 extended mode processing MCB configured in 3-14 UDSBDI for 16-11 TIP requirement 3-12 DMS 2200 UniAccess environment 1-9 level recommended 3-11 extended session transactions meta-schema information defined 16-11 description 19-16 security with UAHS 14-33 sample program C-11 UAHS for 2-15 statistical information returned by UACS DMS 2200 schema 19-16 (see also UAHS tables) defining for UAHS 16-39, 16-88 F definition 14-3 fixed-gate definition element mapping for UAHS description 6-7 column definition 14-27 database definition 14-15 H mapping guidelines 14-37 hardware overview 14-5, 14-9 requirements 3-4 retrieval methods 14-30 sample configuration B-2, B-18 sample 14-9 HELP command schema entity restrictions 14-36 parameter description 19-6 table definition 14-16 HIERSRV (configuration statement) UAHS support 14-35 AREASEARCH 14-32 double-byte character set conversion description 16-36 use of translation routines 12-3 use of 5-10 Dynamic Memory Bank Configuration Report WAITTIME 8-11 description and example 8-22 host generating 17-4 (see also OS 2200) components for the UniAccess System 1-16
Release 10R3: October 31, 2005 Index I-5
data management systems 1-17 UAINFO 4-14 definition xxi UARS 4-11 host file UniAccess 4-5 configuration example B-8 UniAccess samples 4-15 host name installation files definition 16-66 production modes A and B A-2 host performance test modes C and D A-7 I/O utilization 8-16 installation modes 4-4 memory utilization, ClearPath IX, 2200/ integer datatypes 500, and 2200/900 8-16 converted to character strings processor utilization 8-16 for UARS 16-53, 16-84 HVTIP transactions interface memory size 8-15 definition 1-2 using 8-13 Interfaces file configuration example B-8 I internationalization I/O utilization 8-16 variable relationships B-10 In Doubt state Internet address of distributed transactions 15-4 (see IP address) index sequential keys IP address use in keyed fetches 14-30 configured in CMS or CPComm 3-14 indirect client requests 2-4 configuring multiple 16-25 installation defining for UACL 5-11 (see also pre-installation) reporting to client users 7-3 checklist 4-2 IRU (Integrated Recovery Utility) modes description 15-6 batch mode 4-6 recovering updates by 15-9 CMS test mode 4-7 role in recovery 15-7 demand mode 4-6 ISQL (Interactive SQL Parser for OS 2200) Mode A 4-5 a component of UniAccess Transaction Mode B 4-5 Client xvii Mode C 4-7 entering commands 13-3 Mode D 4-7 executing 13-2 production 4-5 general discussion 13-1 test modes 4-7 included with UACL 2-9 troubleshooting F-3 viewing data results 13-3 UniAccess products ASCII COBOL interface 4-15 UAHS 4-9
Release 10R3: October 31, 2005 I-6 UniAccess for OS 2200 System Administration Guide
K representing through translation routines Kanji characters 12-3 designating a character set 16-57, 16-90 Linking System (LINC) using translation routines to present 12-3 errors encountered in accessing F-13 keyed fetches level recommended 3-8 use in data retrieval for UAHS 14-30 local definition xxi L LOCALE (configuration statement) LAN connectivity 3-6 description 16-42 LANGUAGE command localization information CLOSE 19-9 defining 16-42 description 19-7 logoff transaction OFF 19-8 configuring 11-10, 16-24 ON 19-8 discussion 11-4 language requests logon transaction compared to RPCs 2-3 configuring 11-10, 16-24 general discussion 2-2 discussion 11-4 processed by UniAccess Server System LOOPBACK LINK 2-12 example B-16 sending from remote clients 2-7 need for 16-28 sending from UniAccess Transaction looping structure Client 2-9 example 8-14 LANGUAGE statement LSS command 19-7 level recommended 3-8 language trace file defining 16-24 M description 19-7 machine model numbers language transactions configuring 16-13 (see UAHS, UARS, user-written language manual sets 14-25 transactions) map definitions configuring 5-8 AIS-defined 16-60, 16-73 default changing mappings 10-6 assigning 5-9 discussion 10-5 definition 16-21 for message records 16-73 reporting to client users 7-3 for RDMS error codes 16-73 processing language requests 2-12 for RPC names 16-60 LETS-J Kanji code MAPPER 2-3 designating for Kanji characters 16-57, MAX-THREADS 16-90 configuring 16-12
Release 10R3: October 31, 2005 Index I-7
MCB (Message Control Bank) server program D-69 acknowledging initialization loss 19-3 Server-Library generated configuration definitions 10-8 example B-6 description 10-5 for each application group 3-14 UniAccess System D-1 in extended mode 3-14 defining 16-68 level required 3-7 definitions 10-7 with UDS 3-13 description 10-3 description 1-16 mapping 10-5 used by UACS 1-18 types of D-2 MCBBDI Microsoft assigned for each application group 5-6 references G-2 defining 16-11 Microsoft Distributed Transaction Coordinator memory blocks, UAMM (MS DTC) allocating 16-70 communication problems 15-5 defining size of 16-71 role in distributed transaction support 15-2 determining maximum number 16-71 Microsoft Open Database Connectivity optimizing configuration 8-3 (ODBC) 1-7 status of 19-31 Microsoft SQL Server memory utilization (see also SQL Server) general discussion 8-16 configuration B-8 report of 8-22 use in server-to-server requests 2-4 UACS exclusive memory 8-21 use with UACL 16-67 UAFG shared memory 8-17 multiple page sizes 8-5 message definitions multiple requests changing messages 10-7 transactions for 8-12 configuration statement 16-68 discussion 10-7 N variable relationships B-14 network address message text variables variable relationships B-13 syntax of 16-6 network-read-timeout messages defining 16-25 (see also operational messages, program network-write-timeout messages) defining 16-26 for translation routines 12-16 NULLs security in UAHS tables 14-29 security API 11-2 security log D-38
Release 10R3: October 31, 2005 I-8 UniAccess for OS 2200 System Administration Guide
O PC Client Programs object module file 9-8 description C-16 ODBC (Open Database Connectivity) setting up C-23 definition 1-7 PCIOS 1-17, 2-3 ODBC users performance optimization (see client users) database 8-4 Open Client host 8-16 definition xxi, 1-14 UACS 8-2 sample programs C-16 UAHS 8-9 Open Client users UAMM 8-2 (see client users) UARS 8-7 operational messages UASL program design 8-12 defined D-2 pfNativeError 10-6 SCHEMADEF D-56 PID definition security log D-38 range assigned 16-26 TABLEDEF D-60 range defined 5-7 UACF starting PID assigned 5-7, 16-27 errors D-40 variable relationships B-14 warnings D-47 PIDs UACS console D-2 automatically closing hung PIDs 16-20 UACS Trace File D-2 ERROR state 19-25 UAMM D-50 hung 8-8, 8-12 OS 2200 managing blocked PIDs 16-20 configuration example B-3 terminating 19-25 environment 1-9 ports, for UACL host xxi assigning 5-11, 16-67 required hardware and software levels 3-4 configuration relationships B-14 OSPARM (configuration statement) ports, for UACS description 16-44 assigning 5-8, 16-23 SESSCTRL 5-8 configuration relationships B-13 IANA assigned 16-23 P reporting to client users 7-3 password (TSAM) pre-installation assigning for each UACS 5-5 Checklist 3-4 configured in CMS or CPComm 3-14 PREPARED state passwords (user) definition 15-3 content of 11-7 recovery of transactions in 15-3 security through 9-6 priority level switching 16-27
Release 10R3: October 31, 2005 Index I-9
privileges Q for UACS console commands 9-10 queue items Unisys OS 2200 9-9 committing or aborting 15-9 problem reporting recovering active 15-8 general procedures F-16 role in recovery 15-6 reporting form F-20 process name R assigning for each UACS 5-5 RDMS 2200 configured in CMS or CPComm 3-14 error codes mapped 16-73 defining 16-28 level recommended 3-11 process password schema defined for UARS 16-56, 16-87 defining 16-28 UARS for 1-7, 2-13 process slots, UAMM version defined for UARS 16-58, 16-92 number defined 16-71 RDMS 2200 catalog information status of 19-30 supported by UARS 2-14 processors (UniAccess System) RDMS 2200 storage areas general discussion 17-1 explicitly controlled 4-13 product key implicitly controlled 4-13 adding a new key to the Configuration File reporting name to client users 7-4 18-5 RDMS 2200 stored procedures compatibility issues F-3 mapping RPCs to 16-60 connection states 19-31 RPC processing environment 16-47 definition 16-44 supported by UARS 2-14 obtaining 5-4 RDMS 2200 tables (for ODBC) using 5-4 defined by AIS 2-14 program design discussion E-1 Server-Library 8-12 SPT_PROCEDURE_COLUMNS E-3 program messages SPT_PROCEDURES E-6 client real-time-level defined D-2 switching 16-27 discussion D-94 receive call 2-10, 2-17 severity D-95 reconfiguration server adding a UACS 18-10 defined D-2 adding another UACS 18-7 definition D-69 adding new users 18-6 discussion 10-1 by configuration statements 18-2 listed D-69 by system component severity 10-8 UACS 18-3
Release 10R3: October 31, 2005 I-10 UniAccess for OS 2200 System Administration Guide
UADT 18-3 rows UAMM 18-4 maximum number defined upgrading product key 18-5 for UAHS 16-38, 16-87 reentrant transactions for UARS 16-56, 16-87 using 8-13 RPCMAP (configuration statement) references description 16-60 AIS (Applied Information Sciences) G-1 RPCs Microsoft G-2 compared to language requests 2-3 Sybase G-2 default processing environment 5-9, 16-47 Unisys G-2 definition xxii registering general discussion 2-2 transactions 8-6 mapping 16-60 RELSRV (configuration statement) minimizing 16-45 description 16-50 variable relationships B-12 use of 5-10 processed by UniAccess Transaction WAITTIME 8-8 Server 2-13 remote sending from UniAccess Transaction components for the UniAccess System Client 2-9 1-14 RSA worksize definition xxi defined for UARS 16-59, 16-92 remote applications RTPS (Resident Transaction Program System) client 2-6 for UAHS transactions 8-12 server 2-11 for UARS transactions 8-9 remote procedure calls for UASL transactions 8-13 (see RPCs) remote servers S defining for UACL 16-65 sample programs role in server-to-server requests 2-4 components of C-3 selecting communications protocol for databases C-4 16-67 installing 4-15 selecting UACS for 16-83 PC Client C-16 use with UACL 2-11 security 11-10 resource manager setting up C-16 description 15-1 SQL server stored procedures C-9 root records Transaction Client C-12 for UAHS tables 14-21 Transaction Server C-10 in optimizing UAHS performance 8-10 translation routines 12-13 subordinate 14-22 schema superior 14-22 (see DMS 2200 schema, RDMS 2200)
Release 10R3: October 31, 2005 Index I-11
schema banks 8-5 server applications SCHEMADEF general discussion 2-11 description 14-38 remote 2-11 error messages D-56 server messages example 14-40 (see also program messages) execution syntax 14-38 handled by UniAccess System 10-2 overview 14-3 returned to Client-Library applications security D-94 OS 2200 options 9-8 server name third-part security with UniAccess 9-6 defining for UACL 5-11 UniAccess System Server-Library transactions passwords 9-6 (see also distributed transactions) TIP session control 9-5 definition xxii UACS security logging 19-23, 19-33 example UAHS 14-33 general programming sequence for UAUSER definitions 9-6 multiple requests 8-13 UniAccess Security API 11-2 HVTIP 8-13 userid 9-6 messages returned by 10-8 Unisys with UniAccess program design guidelines 8-15 console commands recovery of 15-3 privileges 9-10 application group 15-7 security options 9-8 OS 2200 15-6 TIP session control 9-8 reentrant 8-13 UACS background 9-9 registering 8-6 security logging RTPS 8-13 discussion 19-33 sample initial configuration 16-28 language processing C-10, C-21 messages logged D-38 RPC processing C-10, C-19 through console command 19-23 self-initializing 8-12 security transactions servers logoff 11-4 defining logon 11-4 for UACL 16-65 self-initializing transactions definition xxi, 1-2 using 8-12 types of 1-4 send call 2-10, 2-17 server-to-server SERVER (configuration statement) definition 2-4 defining for servers used by UACL 5-11 services description 16-65 assigning 5-9 definition 16-21
Release 10R3: October 31, 2005 I-12 UniAccess for OS 2200 System Administration Guide
reporting availability to client users 7-3 SQL Server session (see also Microsoft SQL Server, Sybase variable relationships B-11 SQL Server) severity definition xxi level of 10-9 description 1-14 shared object module mapping of error messages for 10-2 description 6-6 sample client programs using C-1 Shift-JIS Kanji code use of Interactive SQL 13-1 designating for Kanji characters 16-57, use with UACL 2-9, 2-11 16-90 SQL text representing through translation routines altering with translation routines 12-8 12-3 rules for UAHS 14-37 SIMAN SQL_LONGVARCHAR configuration example B-7 returning long character strings as 16-54, Site Information File 16-85 building from the UniAccess Configuration SQL_UNICODE File 17-3 character strings returned as 16-53, 16-84 configuration example B-3 STATUS command contents 16-9 ALL 19-15 discussion 5-1 description 19-10 processing syntax 17-3 EXTENDED 19-16 role in configuration management 6-3 PID 19-18 syntax checking 17-4 RESET 19-21 template options 5-2 RESET,GLOBAL 19-21 software SUMMARY 19-10 required levels 3-4 general statistics 19-11 SOLAR UATC statistics 19-14 level recommended 3-9 UATS statistics 19-12 registering the UniAccess tape with 4-5 USER 19-21 SORT Step control recommended level 3-9 description 15-6 source configuration files role in recovery 15-6 description 16-9 storage areas role in configuration management 6-3 (see also RDMS 2200 storage areas) SPT_PROCEDURE_COLUMNS configuring to improve performance 8-5 defined E-3 stored procedures SPT_PROCEDURES (see also RDMS 2200 stored procedures) defined E-6 definition 2-4
Release 10R3: October 31, 2005 Index I-13
subsystem definition module TDSNDMSG description 6-6 defines messages for Server-Library SUPUR files 8-7 transactions 10-8 Sybase TERM command references G-2 confirmation of unsolicited keyins 16-21 SYBASE Open Client 1-14 description 19-24 SYBASE Open Server 1-14 PID, parameter description 19-25 Sybase SQL Server UACS, parameter description 19-24 a.k.a. Adaptive Server Enterprise—ASE timeout xxi network read 16-25 not used in server-to-server requests 2-5 network write 16-26 UNIX configuration specifying frequency of timeout checks host file B-8 16-29 interfaces file B-8 TIP SYSLOG command configuration OFF 19-23 example B-6 ON 19-23 configuring 3-12 system log file enabling 3-12 format of 19-33 installation requirement 3-12 security events written to 19-23 TIP environment system reboot description 1-16 steps following 6-10 TIP file control description 15-6 T TIP session control TABLEDEF configuring 5-8, 9-8 (see also data definition entries) indicating setting 16-47 description 14-40 security through 9-5 error messages D-60 site-specific modifications 16-44 execution syntax 14-41 TIP transactions overview 14-3 (see also distributed transactions, language TABLEDEF reserved words 14-48 transactions, Server-Library TCP/IP transactions, UAHS, UARS, UAINFO connectivity 3-6 transaction, user-written language definition 1-15 transactions) used by UACS 1-18 definition xxii TDS (Tabular Data Stream) in the UniAccess System 1-9 description 1-10 registering 8-6 role in the UniAccess System 1-15
Release 10R3: October 31, 2005 I-14 UniAccess for OS 2200 System Administration Guide
reporting available services to client users compiling 12-17 7-3 configuring types supported by UniAccess 8-15 for UAHS 16-40, 16-90 TIP-FCSS 2-3 for UARS 16-57, 16-89 TIPQ tasks definition 12-4 defining 16-29 discussion 12-2 TIPUTIL installing 12-17 installation mode 3-11 processing catalog RPCs 12-9 level recommended 3-9 UAHS catalog RPCs 12-11 TRACE command UARS catalog RPCs 12-9 CLOSE 19-28 processing result column values 12-9 description 19-27 processing SQL statements 12-8 HIGH 19-28 batched 12-8 LOW 19-28 sample routines 12-13 MEDIUM 19-28 troubleshooting OFF 19-28 accessing LINC data F-13 trace file configuration issues F-3 defining 16-29 debugging UniAccess programs F-15 description 19-27 post installation issues F-3 messages D-2 starting UACS F-5 trailing spaces tools for locating problems F-2 truncated by UAHS 16-39, 16-88 UniAccess Servers truncated by UARS 16-56, 16-88 general issues F-7 transaction ID UniAccess ODBC Server for DMS definition 19-17 2200 F-13 information returned by UACS 19-17, UniAccess ODBC Server for RDMS 19-20 2200 F-11 transaction manager UniAccess Transaction Client F-6 description 15-1 TSAM transactions keep-alives option 16-23 (see TIP transactions) number of tasks 16-30 translation routines variable relationships B-10 (see also UAClientToHost, two-phase commit (2PC) UAHostToClient) definition 15-3 coding assigning a return code 12-16 U handling errors 12-15 UA Information File modifying data 12-14 building from the UniAccess Configuration selecting an error message 12-16 File 17-4
Release 10R3: October 31, 2005 Index I-15
configuration example B-4 adding 18-7, 18-10 contents 16-9 administering 19-3 discussion 5-1 application information for 5-5 processing syntax 17-3 attachment states 19-30 role in configuration management 6-3 communications environment 1-19 syntax checking 17-4 COMSRV statement 16-16 UACF (UniAccess Configuration utility) configuration statements relevant to 18-2 description 6-3 console commands error messages D-40 format of 19-4 execution process 6-4 listed 19-4 execution steps privileges 9-10 initial 6-8 console messages D-2 subsequent 6-10 direct access to CPComm 4-9 execution syntax 17-3 executing 6-5, 6-10 modes of operation 17-2 execution syntax 17-6 role in UniAccess System management 6-3 general discussion 1-18 warnings D-47 management 19-2 UACL (UniAccess Client-Library) memory banks 8-21 a component of UniAccess Transaction multiple 1-20 Client xvii operational characteristics 16-16 description 1-9 performance optimization 8-2 general discussion 2-9 reconfiguring 18-3 interaction with UniAccess components role in UniAccess System management 6-3 1-21 starting 17-6 sample programs with a batch runstream 17-7 language C-12 with default runstreams 17-7 RPC C-12 terminating 19-24 server definition 16-65 troubleshooting F-5 UACS definition 16-83 type of UniAccess processing available use of UACS 1-20 16-30 user definition relationships B-15 UADriver (UniAccess ODBC Driver) UAClientToHost description 1-7, 1-14 definition 12-4 error message handling for 10-2 discussion 12-2 inclusion in UniAccess product packages sample routine 12-13 xviii security through 9-4 setup options UACS (UniAccess Communication Server) IP address and port 7-3 acknowledging communications server name of the machine for UADTC loss 19-2 service 7-5
Release 10R3: October 31, 2005 I-16 UniAccess for OS 2200 System Administration Guide
RDMS storage area 7-4 description of 8-19 transaction service selection 7-4 organization of 8-18 UAHS 16-36 UAHostToClient UARS 16-50 definition 12-5 UADT (UniAccess Data Manager) discussion 12-2 configuration statements relevant to 18-2 sample routine 12-13 description 1-21 security through 9-4 dumping contents of 17-3 UAHS (UniAccess Hierarchical Service for maintains map definitions 10-5 DMS 2200) maintains message definitions 10-7 (see also DMS 2200 schema, reconfiguring 18-3 SCHEMADEF, TABLEDEF, UAHS role in UniAccess System 6-5 databases, UAHS Meta Database, UADT dynamic banks 8-20 UAHS tables) UADTC (UniAccess Distributed Transaction a component of UniAccess ODBC Server Coordinator) for DMS 2200 xviii communication problems 15-5 building the UAHS repository description 1-7 overview 14-3 providing users with name of UADTC host procedures 14-4 7-5 code definition 16-30 role in distributed transaction support 15-2 configuring UAFG (UniAccess Fixed-gate) network addresses B-13 activating 6-7 the UAHS transaction 2-16 as a component of UniAccess configuration VALTAB information B-11 management 6-3 data retrieval methods 14-30 deactivating 6-7 area searches 14-32 description 6-5 keyed fetches 14-30 implementation 6-5 debug tracing initializing configuring 16-38, 16-83 command 17-4 description F-2 discussion 6-5 default name 4-9 managing 6-5 default operational characteristics 5-10 reinitializing 6-12 description 1-8 re-loading 17-4 DMS meta-schema information defined services in 6-5 16-11 shared memory 8-17 DMS schema defined 16-39, 16-88 shared subsystem overview 6-6 DMS schema mapping 14-9 UAFG data banks error messages D-88 creation and modification of 8-17 general discussion 2-15, 14-2
Release 10R3: October 31, 2005 Index I-17
guidelines and restrictions UAHS tables DMS Schema/Subschema Support array mapping 14-28 14-35 column definition 14-27 relational mapping guidelines 14-37 defining 14-16 schema entities 14-36 manual sets 14-25 SQL Syntax Rules 14-37 member-driven style 14-22 UAHS functionality 14-35 multi-level 14-19 installing 4-9 NULLs 14-29 interaction with UniAccess components owner-driven style 14-22 1-23 root records 14-21 operational characteristics 16-36 set mapping 14-19 optimizing performance single-level 14-17 area searches 8-11 UAHS transaction HIERSRV WAITTIME 8-11 (see UAHS) RTPS 8-12 UAIN transaction table definition 8-10 (see UAINFO transaction) UAHS Meta Database 8-10 UAINFO transaction VALTAB settings 8-9 code definition 16-31 security configuring 5-9 DMS security support 14-34 default name 4-14 UAHS mapping techniques 14-33 installing 4-14 translation routines 12-1 use with UADriver 1-7 user, map and message data 2-16 UAIR (UniAccess Integrated Recovery Utility) UAHS databases BDI for 16-11 defining 14-15 execution syntax 15-10 definition 14-3 interactive mode 15-11 UAHS Meta Database ‘H’ option 15-14 definition 14-3 commit and omit of PREPARED optimizing performance 8-10 transactions 15-15 overview 14-3 large number of PREPARED procedures for creating 14-4 transactions 15-17 adjusting the TIP file size 14-8 manual intervention for distributed building 14-8 transaction participants 15-4 creating relational mappings 14-5 UAMESG (configuration statement) creating the TIP file 14-7 description 16-68 estimating the TIP file size 14-6 UAMM (configuration statement) TIP file number configured 16-11 description 16-70 TIP file number for 5-6
Release 10R3: October 31, 2005 I-18 UniAccess for OS 2200 System Administration Guide
UAMM (UniAccess Message Manager) installing 4-11 configuration statements relevant to 18-2 interaction with UniAccess components description 1-21 1-23 error messages multiple transactions 8-8 detailed D-50 operational characteristics 16-50 general D-50 optimizing performance initializing RELSRV WAITTIME 8-8 command 17-4 RTPS 8-9 discussion 6-5, 6-7 VALTAB settings 8-7 memory allocation 16-70 support for UADriver 2-14 optimizing performance 8-2 translation routines 12-1 primary storage parameters 8-2 updating the UREP configuration 4-10 process slot states 19-30 user definition relationships B-15 reconfiguring 18-4 user, map and message data 2-15 used by UACS 1-18 user-defined transactions 16-58, 16-92 UAMM command UARS transaction SUMMARY 19-29 (see UARS) UAMM dynamic banks 8-19 UASAMPLE database (RDMS 2200) UAMMAP (configuration statement) description C-4 description 16-73 setting up C-17 UAMMAP record uasample database (SQL Server) defining 16-73 description C-4 discussion 10-5 setting up C-18 UAOM (shared object module) UASL (UniAccess Server-Library) 1-8 description 6-6 a component of UniAccess Transaction UARS (UniAccess Relational Service for Server xviii RDMS 2200) ASCII COBOL interface 1-9 a component of UniAccess ODBC Server description 1-8 for RDMS 2200 xviii general discussion code definition 16-31 Server-Library transactions concurrent copies 16-31 general discussion 2-16 configuring interaction with UniAccess components network addresses B-13 1-22 the UARS transaction 2-14 processing procedures 2-17 VALTAB information B-11 programming languages supported 1-9 default name 4-11 sample programs 2-17 default operational characteristics 5-10 use UAINFO transaction with 4-14 description 1-7 user definition relationships B-15 general discussion 2-13
Release 10R3: October 31, 2005 Index I-19
UASLCS (configuration statement) UniAccess Language Service Translation description 16-76 Routines UAUSER (configuration statement) (see translation routines) AREASEARCH 14-32 UniAccess ODBC Driver description 16-78 (see UADriver) UAUSER definitions UniAccess ODBC Server for DMS 2200 defining for each user 5-10 (see also UAHS) security through 9-6 components of xviii UCS C definition xxi level recommended 3-10 discussion 1-8 UCS COBOL installation 4-2 level recommended 3-10 programs 2-12 UDS (Universal Data System) troubleshooting F-13 begin thread access mode UniAccess ODBC Server for RDMS 2200 defining 16-53, 16-82 (see also UARS) begin thread recovery options components of xviii defining 16-86 definition xxi configuration discussion 1-6 example B-7 installation 4-2 for each application group 3-13 programs 2-12 description 15-6 troubleshooting F-11 thread banks 8-5 UniAccess Security API using to optimize database performance 8-4 configuring 11-10 UDS Control discussion 11-2 level recommended 3-10 message formats role in recovery 15-6 notification 11-7 UDSBDI request 11-5 assigned for applications groups 5-6 message types defining 16-11 described 11-2 used by UAIR 15-10 illustrated 11-3 UniAccess 10R3 PC Client CD sample programs 11-10 copyright information 0-i security transactions 11-4 sample programs included 2-7 UniAccess System for OS 2200 UniAccess Configuration File configuration B-1 description 6-3 configuration checklist 5-3 generating 6-4, 6-9 definition xx command syntax 17-2 description of components 1-17 modifying 18-1 documentation xviii, G-1
Release 10R3: October 31, 2005 I-20 UniAccess for OS 2200 System Administration Guide
environment 1-11 description C-10 execution steps setting up C-19 initial 6-8 UAINFO transaction for subsequent 6-10 Unisys general discussion 1-6 references G-2 hardware requirements 3-4 Unisys Security Planning and Administration illustration 1-13 Reference Manual D-34 installation checklist 4-2 UREP operating system characteristics defined creating storage areas 4-13 16-44 level recommended 3-11 product installation 4-5 populating the repository 4-14 product installation files A-1 preparing the repository 4-13 product suite xvii updating the configuration 4-10 software requirements 3-4 URTS steps in administrating 3-2 required level 3-7 UniAccess Transaction Client URTS$TABLES (see also UACL) memory size 8-15 applications 2-9 user definitions components of xvii adding new definitions 18-6 definition xx configuration statement 16-78 general discussion 1-9 variable relationships B-15 I.P. relationships B-13 user-defined transactions installation 4-2 allowing for UARS 16-58, 16-92 network address relationships B-13 userid sample programs content of 11-7 description C-12 defining 16-91 setting up C-22 security through 9-6 troubleshooting F-6 setting default for UACL 16-92 UniAccess Transaction Server userid validation (see also UASL) bypassing 16-33 AIS defined RDMS tables for E-1 setting 16-33 components of xviii useroverride definition xx setting for UAHS 16-36 general discussion 1-8 setting for UARS 16-50 installation 4-2 setting for user definitions 16-78 network address relationships B-13 use of 5-10 programs 2-12 user-written language transactions sample programs (see also Server-Library transactions)
Release 10R3: October 31, 2005 Index I-21
code definition 16-32 reporting availability to client users 7-3 sample C-10 use of 2-12
V VALTAB configuration example B-6 recommended settings UAHS 8-9 UARS 8-7 requirements for TIP transactions 8-6 VALTAB transaction codes mapping RPCs to 16-60
W waittime defined for UAHS 16-40 for UARS 16-58 defining UACS 16-33 WAN connectivity 3-6
Release 10R3: October 31, 2005