Administering UniData on Windows Platforms versions/v7.2...Administering UniData on Windows...

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\ADMINNT\ADMINNTTITLE.fmMarch 5, 2010 12:39 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniData

Administering UniData on Windows Platforms

UDT-720-IM-1

ii Administering Un

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\ADMINNT\ADMINNTTITLE.fmMarch 5, 2010 12:39 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Notices

EditionPublication date: July, 2008Book number: UDT-720-IM-1Product version: UniData 7.2

Copyright© Rocket Software, Inc. 1988-2008. All Rights Reserved.

TrademarksThe following trademarks appear in this publication:

Trademark Trademark Owner

Rocket Software™ Rocket Software, Inc.

Dynamic Connect® Rocket Software, Inc.

RedBack® Rocket Software, Inc.

SystemBuilder™ Rocket Software, Inc.

UniData® Rocket Software, Inc.

UniVerse™ Rocket Software, Inc.

U2™ Rocket Software, Inc.

U2.NET™ Rocket Software, Inc.

U2 Web Development Environment™ Rocket Software, Inc.

wIntegrate® Rocket Software, Inc.

Microsoft® .NET Microsoft Corporation

Microsoft® Office Excel®, Outlook®, Word Microsoft Corporation

Windows® Microsoft Corporation

Windows® 7 Microsoft Corporation

Windows Vista® Microsoft Corporation

Java™ and all Java-based trademarks and logos Sun Microsystems, Inc.

UNIX® X/Open Company Limited

iData on Windows Platforms

The above trademarks are property of the specified companies in the United States, other countries, or both. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names as designated by the companies who own or market them.

License agreementThis software and the associated documentation are proprietary and confidential to Rocket Software, Inc., are furnished under license, and may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice. This software and any copies thereof may not be provided or otherwise made available to any other person. No title to or ownership of the software and associated documentation is hereby transferred. Any unauthorized use or reproduction of this software or documentation may be subject to civil or criminal liability. The information in the software and documentation is subject to change and should not be construed as a commitment by Rocket Software, Inc.

Restricted rights notice for license to the U.S. Government: Use, reproduction, or disclosure is subject to restrictions as stated in the “Rights in Technical Data-General” clause (alternate III), in FAR section 52.222-14. All title and ownership in this computer software remain with Rocket Software, Inc.

NoteThis product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product.

Please be aware: Any images or indications reflecting ownership or branding of the product(s) documented herein may or may not reflect the current legal ownership of the intellectual property rights associated with such product(s). All right and title to the product(s) documented herein belong solely to Rocket Software, Inc. and its subsidiaries, notwithstanding any notices (including screen captures) or any other indications to the contrary.

Contact informationRocket Software275 Grove Street Suite 3-410Newton, MA 02466-2272 USA Tel: (617) 614-4321 Fax: (617) 630-7100Web Site: www.rocketsoftware.com

Administering UniData on Windows Platforms iii

http://www.rocketsoftware.com

http://www.rocketsoftware.com

Table of Contents

:\ProgMarch

Table of Contents

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Chapter 1 IntroductionIn This Introduction . . . . . . . . . . . . . . . . . . 1-2About This Manual . . . . . . . . . . . . . . . . . . 1-3

Excluded Commands . . . . . . . . . . . . . . . . 1-3Reserved Characters . . . . . . . . . . . . . . . . 1-4Case Sensitivity . . . . . . . . . . . . . . . . . . 1-5Symbolic Links . . . . . . . . . . . . . . . . . . 1-6Phantom Command . . . . . . . . . . . . . . . . . 1-6Dynamic Files . . . . . . . . . . . . . . . . . . 1-7Deleting Files. . . . . . . . . . . . . . . . . . . 1-7PCPERFORM Command . . . . . . . . . . . . . . . 1-8Shell Command Differences . . . . . . . . . . . . . . 1-8Use of Semicolon . . . . . . . . . . . . . . . . . 1-9

Notes About Terminal Devices and Tape Drives . . . . . . . . . 1-11Terminal Devices . . . . . . . . . . . . . . . . . 1-11Tape Devices . . . . . . . . . . . . . . . . . . . 1-11

Printing in UniData for Windows Platforms . . . . . . . . . . . 1-13

Chapter 2 Migrating Applications to UniData for Windows PlatformsMigrating Applications to UniData for Windows Platforms . . . . . . 2-3Process Overview . . . . . . . . . . . . . . . . . . . 2-4UniData Migration Tools . . . . . . . . . . . . . . . . . 2-6

NTMIGRATE File . . . . . . . . . . . . . . . . . 2-6Copy the NTMIGRATE File . . . . . . . . . . . . . . 2-7Create VOC Entry and DICT for NTMIGRATE . . . . . . . . 2-7Set Pointers to NTMIGRATE. . . . . . . . . . . . . . 2-8Compile the UniBasic Tools Programs . . . . . . . . . . . 2-8

Special Considerations for UniData SQL. . . . . . . . . . . . 2-9Migrating Schema and Dictionaries . . . . . . . . . . . . 2-9Migrating privilege Tables. . . . . . . . . . . . . . . 2-10

ram Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\ADMINNT\ADMINNTTOC.fm (bookTOC.template)5 2010 12:42 pm

NT_SCOUT . . . . . . . . . . . . . . . . . . . . . 2-12Output . . . . . . . . . . . . . . . . . . . . . 2-13NTMIGRATE.LOC . . . . . . . . . . . . . . . . . 2-13Using NT_SCOUT . . . . . . . . . . . . . . . . . 2-13

NT_CATALOG_MAP. . . . . . . . . . . . . . . . . . 2-17Output . . . . . . . . . . . . . . . . . . . . . 2-17Using NT_CATALOG_MAP . . . . . . . . . . . . . . 2-18

TAR2FTP . . . . . . . . . . . . . . . . . . . . . 2-19Output . . . . . . . . . . . . . . . . . . . . . 2-19Using TAR2FTP . . . . . . . . . . . . . . . . . . 2-20

convcode, convdata, convidx . . . . . . . . . . . . . . . 2-24Purpose . . . . . . . . . . . . . . . . . . . . . 2-24Using convcode, convdata, and convidx . . . . . . . . . . 2-24

NT_UPDATE_PATHS. . . . . . . . . . . . . . . . . . 2-27Using NT_UPDATE_PATHS . . . . . . . . . . . . . . 2-27

NT_RECATALOGGER . . . . . . . . . . . . . . . . . 2-29Using NT_RECATALOGGER . . . . . . . . . . . . . 2-29

SQL_UNIX_2_NT . . . . . . . . . . . . . . . . . . . 2-30Using SQL_UNIX_2_NT . . . . . . . . . . . . . . . 2-30

Chapter 3 Managing and Using the UDTelnet ServiceIntroduction . . . . . . . . . . . . . . . . . . . . . 3-3

Requirements for the UDTelnet Service. . . . . . . . . . . 3-3Overview of Features . . . . . . . . . . . . . . . . . . 3-5

Configurability . . . . . . . . . . . . . . . . . . 3-5Direct Access to UniData . . . . . . . . . . . . . . . 3-5Security. . . . . . . . . . . . . . . . . . . . . 3-5Secure Sockets Layer . . . . . . . . . . . . . . . . 3-6Terminal Emulation . . . . . . . . . . . . . . . . . 3-6Integration with UniData Serial Terminal Support . . . . . . . 3-7

Configuring the UDTelnet Service . . . . . . . . . . . . . . 3-8Service Options . . . . . . . . . . . . . . . . . . 3-10User Profiles . . . . . . . . . . . . . . . . . . . 3-13Customizing User Profiles . . . . . . . . . . . . . . . 3-15Generated Profiles . . . . . . . . . . . . . . . . . 3-18

Starting, Stopping and Pausing UDTelnet . . . . . . . . . . . . 3-20Controlling UDTelnet from UniData Admin . . . . . . . . . 3-20Controlling UDTelnet from the Control Panel . . . . . . . . . 3-21

Configuring SSL for Telnet . . . . . . . . . . . . . . . . 3-22

Table of Contents v

vi Adm

Chapter 4 Managing and Using the UDSerial ServiceIntroduction . . . . . . . . . . . . . . . . . . . . 4-3

Requirements . . . . . . . . . . . . . . . . . . 4-3Overview of Features . . . . . . . . . . . . . . . . . 4-5

Security . . . . . . . . . . . . . . . . . . . . 4-5Terminal Emulation . . . . . . . . . . . . . . . . 4-5Logging . . . . . . . . . . . . . . . . . . . . 4-6Integration with UniData Telnet Service . . . . . . . . . . 4-6

Configuring the UniData Terminal Server . . . . . . . . . . . 4-7Service Option . . . . . . . . . . . . . . . . . . 4-8Port Configuration . . . . . . . . . . . . . . . . . 4-9Control Keys . . . . . . . . . . . . . . . . . . 4-12Modem Options. . . . . . . . . . . . . . . . . . 4-13Logon Script. . . . . . . . . . . . . . . . . . . 4-15Auto Connection . . . . . . . . . . . . . . . . . 4-16

Starting and Stopping the UniData Terminal Server . . . . . . . . 4-18Controlling UDSerial from UniAdmin . . . . . . . . . . 4-18Controlling UDSerial from the Control Panel . . . . . . . . 4-19

Chapter 5 UniData and ServicesUniData and Services . . . . . . . . . . . . . . . . . 5-2What Is a Service? . . . . . . . . . . . . . . . . . . 5-3Principal UniData Services . . . . . . . . . . . . . . . . 5-4

Shared Basic Code Server (sbcs) . . . . . . . . . . . . 5-4Shared Memory Manager (smm) . . . . . . . . . . . . 5-5Clean Up (cleanupd) . . . . . . . . . . . . . . . . 5-6

Monitoring UniData Services . . . . . . . . . . . . . . . 5-7Log Files . . . . . . . . . . . . . . . . . . . . 5-8

Chapter 6 UniData and MemoryWindows Platforms and Shared Memory . . . . . . . . . . . 6-3UniData and Shared Memory . . . . . . . . . . . . . . . 6-4

smm and Shared Memory . . . . . . . . . . . . . . 6-4Learning about Global Pages . . . . . . . . . . . . . 6-10Learning about Local Control Tables . . . . . . . . . . . 6-11sbcs and Shared Memory . . . . . . . . . . . . . . . 6-13Self-Created Segments . . . . . . . . . . . . . . . 6-13

Chapter 7 Configuring Your UniData System Configuring Your UniData System . . . . . . . . . . . . . 7-2

inistering UniData on Windows Platforms

Configuration Procedure . . . . . . . . . . . . . . . . . 7-31. Identify Disk Requirements . . . . . . . . . . . . . 7-32. Identify Memory Requirements. . . . . . . . . . . . 7-33. Verify Version Compatibilities . . . . . . . . . . . . . 7-44. Check/Reset System-Level Parameters . . . . . . . . . . 7-45. Check/Reset UniData Configuration Parameters . . . . . . . 7-46. Define Peripherals within UniData . . . . . . . . . . . 7-57. Create UniData Accounts . . . . . . . . . . . . . . 7-58. Add Windows Users . . . . . . . . . . . . . . . . 7-69. Set Environment Variables . . . . . . . . . . . . . . 7-610. Review UniData Security . . . . . . . . . . . . . . 7-811. Convert Data Files . . . . . . . . . . . . . . . . 7-812. Review Backup Procedures . . . . . . . . . . . . . 7-9

Chapter 8 Starting, Stopping, and Pausing UniDataNormal Operation . . . . . . . . . . . . . . . . . . . 8-3

UniData Log Files . . . . . . . . . . . . . . . . . 8-3Start UniData with startud . . . . . . . . . . . . . . . 8-4Stop UniData with stopud . . . . . . . . . . . . . . . 8-5

Pausing UniData . . . . . . . . . . . . . . . . . . . 8-6The dbpause Command . . . . . . . . . . . . . . . . 8-6The dbpause_status Command . . . . . . . . . . . . . 8-7Resuming Processing . . . . . . . . . . . . . . . . 8-8

Additional Commands. . . . . . . . . . . . . . . . . . 8-9Stopping a User Process with stopudt . . . . . . . . . . . 8-9Stopping a User Process with deleteuser . . . . . . . . . . 8-10Displaying ipc Facilities with ipcstat . . . . . . . . . . . 8-11Stopping UniData with stopud -f . . . . . . . . . . . . . 8-12

Chapter 9 Managing UniData AccountsWhat Is a UniData Account?. . . . . . . . . . . . . . . . 9-3Creating a UniData Account . . . . . . . . . . . . . . . . 9-4Deleting an Account . . . . . . . . . . . . . . . . . . 9-8Clearing Space in UniData Accounts . . . . . . . . . . . . . 9-9

CLEAR.ACCOUNT. . . . . . . . . . . . . . . . . 9-9

Chapter 10 Managing UniData SecurityCustomizing Permissions . . . . . . . . . . . . . . . . . 10-3Customizing a VOC File . . . . . . . . . . . . . . . . . 10-6

Removing Entries . . . . . . . . . . . . . . . . . 10-6

Table of Contents vii

viii Adm

Customizing UniData . . . . . . . . . . . . . . . . . 10-8Remote Items . . . . . . . . . . . . . . . . . . . . 10-10The SETFILE Command . . . . . . . . . . . . . . . . 10-12LOGIN and LOGOUT Paragraphs . . . . . . . . . . . . . 10-13UniData SQL Privileges. . . . . . . . . . . . . . . . . 10-16Field-Level Security for UniQuery . . . . . . . . . . . . . 10-17

Points to Remember about Field-Level Security . . . . . . . 10-17The QUERY.PRIVILEGE File . . . . . . . . . . . . . 10-18UniQuery Processing . . . . . . . . . . . . . . . . 10-20Turning on Field-Level Security . . . . . . . . . . . . 10-20

Chapter 11 Managing UniData FilesUniData Hashed Files . . . . . . . . . . . . . . . . . 11-4Static Hashed Files . . . . . . . . . . . . . . . . . . 11-5Dynamic Hashed Files . . . . . . . . . . . . . . . . . 11-6

Dynamic Files and Overflow . . . . . . . . . . . . . 11-6When Dynamic Files Are Created . . . . . . . . . . . . 11-9Tips and Constraints for Creating a Dynamic File . . . . . . . 11-10Dynamic Files and Disk Space . . . . . . . . . . . . . 11-11

Sequentially Hashed Files . . . . . . . . . . . . . . . . 11-17The over001 File . . . . . . . . . . . . . . . . . 11-17The gmekey File . . . . . . . . . . . . . . . . . 11-18

DIR-Type Files . . . . . . . . . . . . . . . . . . . 11-20Multilevel Directory Files . . . . . . . . . . . . . . . . 11-23Index Files and Index Log Files . . . . . . . . . . . . . . 11-25

Index-Related Files for a Static Hashed File . . . . . . . . . 11-26Index-Related Files for a Dynamic Hashed File . . . . . . . . 11-26

File-Handling Commands . . . . . . . . . . . . . . . . 11-28File Corruption . . . . . . . . . . . . . . . . . . . 11-31

What Causes File Corruption? . . . . . . . . . . . . . 11-31Preventing File Corruption . . . . . . . . . . . . . . 11-31

UniData Detection Tools . . . . . . . . . . . . . . . . 11-33guide . . . . . . . . . . . . . . . . . . . . . 11-33guide_ndx . . . . . . . . . . . . . . . . . . . 11-38

UniData Recovery Tools . . . . . . . . . . . . . . . . 11-42dumpgroup . . . . . . . . . . . . . . . . . . . 11-42fixgroup . . . . . . . . . . . . . . . . . . . . 11-44fixfile . . . . . . . . . . . . . . . . . . . . . 11-45

Detection and Repair Examples . . . . . . . . . . . . . . 11-50How to Use guide. . . . . . . . . . . . . . . . . . . 11-54Error Messages . . . . . . . . . . . . . . . . . . . 11-57


File Access Messages . . . . . . . . . . . . . . . . 11-57Block Usage Messages . . . . . . . . . . . . . . . . 11-57Group Header Messages . . . . . . . . . . . . . . . 11-58Header Key Messages . . . . . . . . . . . . . . . . 11-58Other Header Messages. . . . . . . . . . . . . . . . 11-58Free Block Messages . . . . . . . . . . . . . . . . 11-59Long Record Messages . . . . . . . . . . . . . . . . 11-60Dynamic File Messages. . . . . . . . . . . . . . . . 11-61

Chapter 12 Managing UniData LocksThe Global Lock Manager . . . . . . . . . . . . . . . . 12-3

How GLM Works . . . . . . . . . . . . . . . . . 12-3Locking in UniBasic . . . . . . . . . . . . . . . . . . 12-5

How Locks Work. . . . . . . . . . . . . . . . . . 12-5Locking Commands . . . . . . . . . . . . . . . . . 12-6

Resource Locks . . . . . . . . . . . . . . . . . . . . 12-8Listing Locks . . . . . . . . . . . . . . . . . . . . 12-9

LIST.READU . . . . . . . . . . . . . . . . . . . 12-9LIST.LOCKS . . . . . . . . . . . . . . . . . . . 12-11LIST.QUEUE . . . . . . . . . . . . . . . . . . . 12-11Parameters . . . . . . . . . . . . . . . . . . . . 12-12LIST.QUEUE Display . . . . . . . . . . . . . . . . 12-13

Commands for Clearing Locks . . . . . . . . . . . . . . . 12-17SUPERCLEAR.LOCKS Command . . . . . . . . . . . . 12-17SUPERRELEASE Command . . . . . . . . . . . . . . 12-18

Procedure for Clearing Locks . . . . . . . . . . . . . . . 12-19

Chapter 13 Managing UniData UsersAdding Users . . . . . . . . . . . . . . . . . . . . 13-3

User Groups . . . . . . . . . . . . . . . . . . . 13-3Home Directories . . . . . . . . . . . . . . . . . 13-4Logon Scripts . . . . . . . . . . . . . . . . . . . 13-5

Monitoring User Processes . . . . . . . . . . . . . . . . 13-7UniData Commands . . . . . . . . . . . . . . . . . 13-7

Stopping User Processes . . . . . . . . . . . . . . . . . 13-9Using TIMEOUT . . . . . . . . . . . . . . . . . 13-9

Chapter 14 Managing Printers in UniDataConfiguring and Troubleshooting a Printer . . . . . . . . . . . 14-3

Physical Configuration . . . . . . . . . . . . . . . . 14-3

Table of Contents ix

x Admi

Troubleshooting . . . . . . . . . . . . . . . . . 14-3Definition in UniData . . . . . . . . . . . . . . . . 14-7Default Printers . . . . . . . . . . . . . . . . . . 14-8

Spooling From UniData . . . . . . . . . . . . . . . . . 14-9The Spooling Process . . . . . . . . . . . . . . . . 14-9UniData for Windows Platforms Specifics . . . . . . . . . 14-9Creating a Local Printer . . . . . . . . . . . . . . . 14-9

Creating a Form . . . . . . . . . . . . . . . . . . . 14-20Defining a Printer Unit in UniData . . . . . . . . . . . . . 14-24

Examples . . . . . . . . . . . . . . . . . . . . 14-29Printing to the _HOLD_ File . . . . . . . . . . . . . 14-33Selecting a Spooler Mode . . . . . . . . . . . . . . 14-34Redefining the Default UniData Print Unit . . . . . . . . . 14-37Submitting Concurrent Print Jobs . . . . . . . . . . . . 14-37

UniData Printing Commands . . . . . . . . . . . . . . . 14-38

Chapter 15 Managing Cataloged ProgramsUniBasic Source and Compiled Programs . . . . . . . . . . . 15-3

UniBasic Compiled Programs . . . . . . . . . . . . . 15-3Cataloging UniBasic Programs . . . . . . . . . . . . . . 15-4

Direct Cataloging . . . . . . . . . . . . . . . . . 15-4Local Cataloging . . . . . . . . . . . . . . . . . 15-4Global Cataloging . . . . . . . . . . . . . . . . . 15-5

Managing Global Catalogs . . . . . . . . . . . . . . . . 15-7Contents of a Global Catalog . . . . . . . . . . . . . 15-7Verifying a Program Version. . . . . . . . . . . . . . 15-8Activating Newly Cataloged Programs and Subroutines . . . . . 15-10

Listing Programs in Use. . . . . . . . . . . . . . . . . 15-14Creating an Alternate Global Catalog Space . . . . . . . . . . 15-15

Files and Directories Created by newhome . . . . . . . . . 15-16Procedure for Creating an Alternate Global Catalog Space . . . . 15-17

Chapter 16 Managing and Using Tape DevicesUniData Tape Handling Commands . . . . . . . . . . . . . 16-3

SETTAPE . . . . . . . . . . . . . . . . . . . 16-4Steps for Tape Device Use . . . . . . . . . . . . . . . . 16-6

Chapter 17 CallC and CallBasicCALLC and CallBasic . . . . . . . . . . . . . . . . . 17-2Dynamic Link Libraries (DLLs) and UniData . . . . . . . . . . 17-3

nistering UniData on Windows Platforms

Calling External Routines From UniData . . . . . . . . . . . . 17-4Requirements for CALLC . . . . . . . . . . . . . . . 17-4Steps for CALLC. . . . . . . . . . . . . . . . . . 17-4CALLC and UDT.OPTIONS 88 . . . . . . . . . . . . . 17-5CALLC Syntax and Data Types . . . . . . . . . . . . . 17-6E Type VOC Entries . . . . . . . . . . . . . . . . . 17-7Examples . . . . . . . . . . . . . . . . . . . . 17-8

CALLC Example Programs . . . . . . . . . . . . . . . . 17-9C Example . . . . . . . . . . . . . . . . . . . . 17-10C++ Example . . . . . . . . . . . . . . . . . . . 17-14Pascal Style Example . . . . . . . . . . . . . . . . 17-18

Accessing UniData From an External Program . . . . . . . . . . 17-21How CallBasic Works . . . . . . . . . . . . . . . . 17-21Examples . . . . . . . . . . . . . . . . . . . . 17-22

Sample Programs . . . . . . . . . . . . . . . . . . . 17-24C Program Example . . . . . . . . . . . . . . . . . 17-24UniBasic Subroutine Example . . . . . . . . . . . . . 17-28

Steps for CallBasic . . . . . . . . . . . . . . . . . . . 17-30

Chapter 18 Monitoring and Tuning UniDataMonitoring Your Windows System . . . . . . . . . . . . . . 18-3UniData Performance Factors . . . . . . . . . . . . . . . 18-4

Database Design Considerations . . . . . . . . . . . . . 18-4Using Alternate Key Indexes . . . . . . . . . . . . . . 18-4Sizing Static Hashed Files . . . . . . . . . . . . . . . 18-4Sizing Dynamic Hashed Files . . . . . . . . . . . . . . 18-5UniBasic Coding Tips . . . . . . . . . . . . . . . . 18-5

UniBasic Profiling . . . . . . . . . . . . . . . . . . . 18-7UniData Performance Monitoring . . . . . . . . . . . . . . 18-11

UniData Dynamic Array Statistics . . . . . . . . . . . . 18-13UniData File I/O Statistics . . . . . . . . . . . . . . . 18-15UniData Index Statistics . . . . . . . . . . . . . . . 18-17UniData Lock Statistics . . . . . . . . . . . . . . . . 18-19UniData Program Control Statistics . . . . . . . . . . . . 18-21

ECL Process Monitoring Commands . . . . . . . . . . . . . 18-23Examples . . . . . . . . . . . . . . . . . . . . . . 18-26

Appendix A UniData Configuration Parameters

Table of Contents xi

xii Adm

Appendix B Environment Variables for UniData


1Chapter

Introduction

About This Manual . . . . . . . . . . . . . . . . . . 1-3 Product Basis . . . . . . . . . . . . . . . . . . 1-3 Excluded Commands . . . . . . . . . . . . . . . . 1-4 Reserved Characters . . . . . . . . . . . . . . . . 1-4 Case Sensitivity. . . . . . . . . . . . . . . . . . 1-5 Symbolic Links . . . . . . . . . . . . . . . . . . 1-7 Phantom Command . . . . . . . . . . . . . . . . 1-7 Dynamic Files . . . . . . . . . . . . . . . . . . 1-8 Deleting Files . . . . . . . . . . . . . . . . . . 1-8 PCPERFORM Command. . . . . . . . . . . . . . . 1-9 Shell Command Differences . . . . . . . . . . . . . . 1-9 Use of Semicolon . . . . . . . . . . . . . . . . . 1-10Notes About Terminal Devices and Tape Drives . . . . . . . . . 1-12 Terminal Devices . . . . . . . . . . . . . . . . . 1-12 Tape Devices . . . . . . . . . . . . . . . . . . 1-12Printing in UniData for Windows Platforms . . . . . . . . . . 1-14

In This IntroductionThis introduction provides an overview of the information in this manual and describes the conventions it uses.

1-2 Administering UniData on Windows Platforms

About This ManualThe purpose of this manual is to collect, in a single book, as much information as possible about activities needed to administer a UniData installation on Windows platforms. This manual repeats some information presented elsewhere in the UniData documentation set. Certain command descriptions and examples have been amplified or modified in this manual to increase their usefulness to system administrators as opposed to end users.

AudienceAdministering UniData on Windows Platforms is intended for people whose respon-sibilities include the following:

Tasks performed at the operating system levelModifying file permissionsAdding usersCreating directoriesStarting and stopping UniDataBacking up UniData files

Tasks performed within UniDataCreating and managing UniData accountsOptimizing UniData configurationCustomizing securityManaging filesMonitoring and accessing files, peripherals, and system resources

Excluded CommandsThe following commands are not supported on UniData for Windows platforms:

acctrestoreACCT.SAVEkp

About This Manual 1-3

nusersshmconfshowudsmmtestsystestudstatudtinstall

Reserved CharactersUniData for Windows platforms does not allow the use of the following characters in a file or directory name:

“ (double quotation mark)| (pipe sign)* (asterisk)/ (slash): (colon)< (less than sign)> (greater than sign)? (question mark)\ (backslash)

You may use the reserved characters in a file specification. For instance, C:\IBM\ud72\DEMO\INVENTORY is an acceptable file specification. The reserved characters : and \ are used as delimiters in the file specification. However, they may not be used within the name of a file or directory. DEM:O or INVEN\TORY are unacceptable.

Note: If your application uses any of these characters in file or directory names, you need to substitute other characters. See “Migrating Applications to UniData for Windows Platforms” for information about tools that locate these special characters within your accounts.


Case SensitivityWindows platforms do not distinguish between uppercase and lowercase, except in a user’s password, which is case sensitive. UniData is case sensitive. This difference creates a number of impacts. See Chapter 2, “Migrating Applications to UniData for Windows Platforms” for information about tools to report all instances in your file and record names where case insensitivity could cause problems.

File Names

On Windows platforms, you cannot have two files whose names are identical except for case. For example, if your application creates files such as “aatemp” and “AATEMP”, you must modify the application since Windows platforms will not allow both to exist.

Record Names

You cannot have two records in the same DIR or MULTIDIR file whose names are identical except for case. The following screen illustrates one effect of this limitation:

:CREATE.FILE DIR TEST_DIRCreate DIR type file TEST_DIR.Create file D_TEST_DIR, modulo/1,blocksize/1024Hash type = 0Added "@ID", the default record for UniData to DICT TEST_DIR.:SELECT VOC WITH F1=PA 7 records selected to list 0. >COPY FROM VOC TO TEST_DIRget id's from select list:LISTPEQS(y/n)?YLISTDICT exists in TEST_DIR, cannot overwrite6 records copied:

UniData could not copy the LISTDICT record because a record called listdict already was copied. Since each record in a DIR (or MULTIDIR) file is an NTFS file, Windows platforms treat listdict and LISTDICT as the same file. You need to consider this limitation if your application:

Creates records with names differing only in case in a DIR file or multilevel subdirectory.Copies records from a hashed file, where the limitation does not exist, into a DIR file or multilevel subdirectory.


Index Files and Index Log Files

On UniData for UNIX, the index file and the index log file for a static hashed file are named X_filename and x_filename, respectively. On UniData for Windows platforms, the index file and index log file for a static hashed file are named X_FILENAME and L_FILENAME, respectively.

Warning: The Windows operating system does not distinguish between X_filename and x_filename. If you copy an index file and an index log file to your Windows machine, Windows platforms may overwrite the first one you copied with the second, and you could lose information. When you are migrating your application, consider removing the index log files for your static files, or renaming them to the Windows platforms convention, before physically moving them to the Windows machine.

savedlists File

By default, a UniData account on UNIX contains a SAVEDLISTS file for saving SELECT lists, and a savedlists file for storing temporary information for BY.EXP sorts.

At the operating system level, the file named savedlists on UniData for UNIX is called the SAVEDLISTSL file on UniData for Windows platforms. However, the VOC file contains an entry for savedlists pointing the correct file, so you should not have to modify your application. You must change the name of the savedlists file in any UniData account you are moving from UNIX to Windows platforms.

Symbolic LinksWindows platforms, unlike UNIX, do not support symbolic links. If your application has identified files by using symbolic links at the operating system level, you must restructure your UniData accounts to eliminate them. You can use environment variables in VOC pointers, or set new pointers with SETFILE, just as you can in UniData for UNIX.

Phantom CommandOn UniData for Windows platforms, the PHANTOM command behaves differently, depending from where you execute it.


If you execute PHANTOM from a UniData session at the console, then end the UniData session, the phantom job completes.If you execute PHANTOM from a telnet session, the phantom job continues until it completes. This behavior matches the behavior of PHANTOM on UniData for UNIX.

Dynamic FilesThe dynamic file implementation on UniData for Windows platforms differs slightly from the implementation on UniData for UNIX. On UniData for Windows platforms, the “parts” of a large dynamic file must remain in the same partition where the file was created. Because of this, the “part table” is not relevant to UniData for Windows platforms. The size of each part file is limited by the configuration parameter MAX_FLENGTH in udthome\include\udtconfig.

Deleting FilesWindows platforms do not allow a process to delete a file if any other process has that file open. This operating system limitation significantly affects the behavior of the ECL DELETE.FILE command. To minimize the impact of this restriction, DELETE.FILE only removes the DICT portion and VOC entry for a file if it has successfully removed the DATA portion of the file. However, the operating system restriction still results in the following behaviors in UniData:

If one process executes DELETE.FILE filename, and another process has the DATA portion of filename open, or both the DICT and the DATA portions of filename open, the DELETE.FILE fails with an error, and no component of the file is deleted.If one process executes DELETE.FILE filename, and another process has only the DICT portion of filename open, the DELETE.FILE removes only the data portion of the file, leaving the VOC entry and the DICT portion intact, and displaying an error.

In UniData on UNIX, DELETE.FILE would succeed in both cases. If your appli-cation depends on the UNIX-style behavior, you need to rework the application.


PCPERFORM CommandThe UniBasic PCPERFORM command allows users to execute an operating system command from within a UniBasic program. In UniData for Windows platforms, only MS-DOS commands can be executed with PCPERFORM. In some cases (for instance, the echo command) there are MS-DOS commands named like the UNIX versions (although their behavior may differ somewhat). In other cases (for instance, who, ls, ps) you must identify replacements. Refer to your Windows platform and UNIX documentation for information about system-level commands.

UniData supplies a suite of tools to automate some application analysis tasks. You can use the NT_SCOUT tool to report all instances of the PCPERFORM command in your UniBasic programs, PROCS, and paragraphs. See Chapter 2, “Migrating Applications to UniData for Windows Platforms” for information about NT_SCOUT.

Tip: If you are migrating your application to a Windows machine that has certain third-party applications (for instance, the MKS Toolkit) installed, consider whether your production system will have that software installed. MKS Toolkit and similar software products provide a UNIX-like environment to help you with migration tasks. They include UNIX-like commands that may not exist in MS-DOS or may function differently from the MS-DOS versions. PCPERFORM executes the MS-DOS version of the command, provided a DOS version exists. If no DOS version exists, PCPERFORM executes the third-party version. Make sure you test your application in an environment that matches your production environment.

Shell Command Differences

echo

The MS-DOS echo command behaves differently from UNIX in the following ways:

Quotes are echoed. In UNIX, the command echo ‘text’ displays the string text. In MS-DOS, echo ‘text’ displays ‘text’.In MS-DOS, echo displays the input starting from one space after the command on the command line, as shown in the following example:


Warning: In UNIX, the three commands in the example are equivalent. If your application depends on comparing the output from echo to another string, make sure your echo command is formatted correctly.

If you direct the output to a file, echo displays everything between its starting point and the redirection character (>). The two commands echo abc>file and echo abc >file, equivalent on UNIX, are not equivalent on Windows platforms. The second command produces a 4-character string, with a space as the fourth character.

Use of SemicolonIn UNIX, the semicolon is recognized as a command separator, so users can enter multiple commands on a single command line. This functionality is lacking in MS-DOS. This particular operating system difference can cause unexpected results, as shown in the following example:


On UNIX, the command line entry would echo the string abc to the file named file, then attempt to execute the dir command.


Notes About Terminal Devices and Tape DrivesThis sections discusses terminal and tape devices.

Terminal DevicesUniData for Windows Platforms records and displays a “tty” for a UniData process. The tty is formed by appending the UDTNO (from LISTUSER) to the string “pts/”. This tty can be used with the !portnumber option in the ECL MESSAGE command, to send a message to a specific terminal or window. A number of ECL commands (LISTUSER, MYSELF, WHO, and STATUS) display the tty number for each UniData session.

Tape DevicesWhen you use UniData tape commands (for instance, SETTAPE), you must use the Universal Naming Convention (UNC) format for device identifiers. UNC names are in the form \\server\device. The following example shows the SETTAPE, T.ATT, and T.STATUS commands on UniData for Windows Platforms:

:SETTAPE 0unit # = 0.non rewind device:\\.\tape0rewind device :r\\.\tape0block size =4096:T.ATT 0tape unit 0 blocksize = 4096.:T.STATUS UNIT STATUS UDTNO USER CHANNEL ASSIGNED NUMBER NAME NAME BLOCKSIZE 0 ASSIGNED 65 terric \\.\tape0 4096:

The device identifier \\.\TAPE0 indicates the current server (.), device TAPE0.

Notes About Terminal Devices and Tape Drives 1-11

You can identify a disk file as a tape device by entering a path and file name (not in UNC format) on the SETTAPE command line. If you do not use UNC format, UniData checks for a path and file that matches your entry. If the file exists, UniData writes to the file as a “tape device”. Otherwise, SETTAPE fails with an error message.UniData stores tape definition information in a file called udthome\sys\tapeinfo. This is a text file, which you can view with any text editor.

You must log in as a member of the Administrators group to define a tape device with the SETTAPE command.


Printing in UniData for Windows PlatformsWindows platforms allow users to print to printers (which are simply drivers that control print devices). A printer may control a network print device or a local print device. Microsoft applications, through their own print menus, allow users to incor-porate printing options (like font selections, orientation, duplex mode, and so forth) within their application. UNIX spoolers, on the other hand, allow users to select many of these options outside of their application, on the command line of the spooler. The Windows spooler allows users to write data, including device-specific escape sequences, to a print device (RAW mode), or to incorporate pre-defined printing options (WINDOW) mode. Within a UniData session, the SETPTR command identifies a print unit with a default spooler mode of RAW. If the output from your application contains escape sequences for formatting, you do not need to specify printing options when you define a print unit with SETPTR. If you are not using escape sequences, you can specify printer options in a quoted string on the SETPTR command line. UniData then passes that information to the Windows spooler.

Printing in UniData for Windows Platforms 1-13

2Chapter

Migrating Applications to UniData for Windows Platforms

Process Overview . . . . . . . . . . . . . . . . . . 2-4UniData Migration Tools . . . . . . . . . . . . . . . . 2-6 NTMIGRATE File . . . . . . . . . . . . . . . . . 2-6 Copy the NTMIGRATE File . . . . . . . . . . . . . . 2-7 Create VOC Entry and DICT for NTMIGRATE . . . . . . . 2-7 Set Pointers to NTMIGRATE . . . . . . . . . . . . . 2-8 Compile the UniBasic Tools Programs . . . . . . . . . . 2-8Special Considerations for UniData SQL . . . . . . . . . . . 2-9 Migrating Schema and Dictionaries . . . . . . . . . . . 2-9 Migrating privilege Tables . . . . . . . . . . . . . . 2-10NT_SCOUT . . . . . . . . . . . . . . . . . . . . 2-12 Output. . . . . . . . . . . . . . . . . . . . . 2-13 NTMIGRATE.LOC . . . . . . . . . . . . . . . . 2-13 Using NT_SCOUT. . . . . . . . . . . . . . . . . 2-13NT_CATALOG_MAP . . . . . . . . . . . . . . . . . 2-17 Output. . . . . . . . . . . . . . . . . . . . . 2-17 Using NT_CATALOG_MAP . . . . . . . . . . . . . 2-18TAR2FTP . . . . . . . . . . . . . . . . . . . . . 2-19 Output. . . . . . . . . . . . . . . . . . . . . 2-19 Using TAR2FTP . . . . . . . . . . . . . . . . . 2-20convcode, convdata, convidx . . . . . . . . . . . . . . . 2-24 Purpose . . . . . . . . . . . . . . . . . . . . 2-24 Using convcode, convdata, and convidx . . . . . . . . . . 2-24NT_UPDATE_PATHS . . . . . . . . . . . . . . . . . 2-27 Using NT_UPDATE_PATHS . . . . . . . . . . . . . 2-27NT_RECATALOGGER . . . . . . . . . . . . . . . . 2-29 Using NT_RECATALOGGER . . . . . . . . . . . . . 2-29

2-2 Adm

SQL_UNIX_2_NT . . . . . . . . . . . . . . . . . . 2-30 Using SQL_UNIX_2_NT. . . . . . . . . . . . . . . 2-30


Migrating Applications to UniData for Windows PlatformsThis chapter describes the process for moving a UniData application from a UNIX platform, where the application is installed and running, to a Windows platform. The chapter describes how to use the migration tools provided with UniData for Windows Platforms.

Tip: IBM strongly recommends you read this entire chapter before you begin migrating your application.


Process OverviewThis overview presents a high-level view of the migration process. The remainder of the chapter describes the tools in detail. The process sequence follows:

1. After you install UniData for Windows Platforms, copy the tools from the Windows platform to UNIX. The directory udthome\NTMIGRATE contains the UniBasic tool programs NT_scout, NT_CATALOG_MAP, Tar2ftp, SQL_UNIX_2_NT, and NT_UPDATE_PATHS, and also contains input files needed for the programs. For more information about these programs, see “UniData Migration Tools” on page 2-6.

2. Complete these UNIX steps in the following order for each UniData account:

Run NT_scout in the account to identify migration items. Resolve migration items that would cause data loss. This is a required step. For more information, see “NT_SCOUT” on page 2-12.Run NT_CATALOG_MAP in the account to create a VOC paragraph that compiles and catalogs UniBasic programs on Windows platforms. This is an optional step. You may recompile and catalog programs manually if you prefer. For more information, see “NT_CATALOG_MAP” on page 2-17.Run Tar2ftp in the account to create a script for moving the programs and data files to Windows platforms via FTP. This is an optional step. You can move the account via tape or FTP the account manually, if you prefer. For more information, see “TAR2FTP” on page 2-19.Move the FTP script (output from Tar2ftp) to the Windows machine. This is a required step only if you executed Tar2ftp.

Process Overview 2-4

3. Complete these steps in the following order for each UniData account:Move the programs and data files from your UNIX machine. This is a required step. Edit and use the output from Tar2ftp if you are using FTP. For more information, see “TAR2FTP” on page 2-19.Convert machine format in programs, data and indexes. This is a required step if you are migrating from a high-byte UNIX system AND you did not use Tar2ftp. For more information, see “convcode, convdata, convidx” on page 2-24.Run NT_UPDATE_PATHS in the account to update paths in VOC entries. This ia a required step. For more information, see “NT_UPDATE_PATHS” on page 2-27.Compile and catalog the application. This is a required step. If you executed NT_CATALOG_MAP on UNIX, execute NT_RECATALOGGER. For more information, see “NT_RECATALOGGER” on page 2-29.Convert the UniData SQL privilege table into the Windows platform format. This is a required step if the account is a UniData SQL account. For more information, see “SQL_UNIX_2_NT” on page 2-30.

4. After you have completed the sequence for each UniData account, begin testing your application.


UniData Migration ToolsThis section describes the tools UniData provides to migrate your application.

NTMIGRATE FileWhen you install UniData on your Windows system, the installation creates a directory in your IBM UniData folder called NTMIGRATE, which contains a group of tools to assist you with application migration tasks. The following table describes these tools.

Tool Description

NT_SCOUT UniBasic preprocessor. Run this program in each UniData account on UNIX to identify migration issues.

ALT.ECL.CMDS List of ECL commands that are known to be excluded on UniData for Windows Platforms or behave differently on UniData for Windows Platforms. NT_SCOUT uses this file to analyze your application.

ALT.BP.CMDS List of UniBasic commands known to perform differently on UniData for Windows Platforms. NT_SCOUT uses this file to analyze your application.

RESERVED.CHARS List of Windows platforms reserved characters. NT_SCOUT uses this file to analyze your application.

TAR2FTP UniBasic program that produces a directory listing in valid FTP syntax. Run this program in each UniData account on UNIX, then transfer the output to your Windows machine to FTP the contents of the UniData account.

NT_CATALOG_MAP UniBasic program that builds a paragraph to catalog programs on your Windows machine. Run this program in each UniData account on UNIX. Execute the paragraph to catalog your programs after moving to the Windows platform.

UniData Migration Tools

UniData Migration Tools 2-6

Copy the NTMIGRATE FileCopy the directory NTMIGRATE from your Windows system to your UNIX system. You can use FTP, or you can copy the directory to a diskette and load it into a UniData account directory on your UNIX machine. In the following examples, the NTMIGRATE directory was copied to the UniData demo account on a UNIX computer.

Create VOC Entry and DICT for NTMIGRATENTMIGRATE is a DIR-type file. You need to create its VOC entry and create a dictionary, as shown in the following example:

:SETFILE NTMIGRATE NTMIGRATEEstablish the file pointerTree name NTMIGRATEVoc name NTMIGRATEOk to establish pointer(Y/N) = YSETFILE completed.:CT VOC NTMIGRATEVOC: NTMIGRATE:DIRNTMIGRATE:CREATE.FILE DICT NTMIGRATECreate file D_NTMIGRATE, modulo/1,blocksize/1024Hash type = 0Added "@ID", the default record for UniData to DICT NTMIGRATE.

NT_UPDATE_PATHS UniBasic program that allows you to make global substitutions for paths or subpaths in VOC entries. Execute this program in each UniData account after moving to the Windows platform.

BUILD.FULL.PATH UniBasic subroutine used by NT_UPDATE_PATHS to generate Windows-style path specifications.

SQL_UNIX_2_NT UniBasic program that converts a privilege table from UNIX style to the Windows platform style.

Tool Description

UniData Migration Tools (continued)


Set Pointers to NTMIGRATEThe tools in the NTMIGRATE file are executed one UniData account at a time. In each UniData account you want to preprocess, set a pointer to the NTMIGRATE file, as shown in the following screen:

:SETFILE /usr/ud72/demo/NTMIGRATE NTMIGRATEEstablish the file pointerTree name /usr/ud72/demo/NTMIGRATEVoc name NTMIGRATEDictionary name /usr/ud72/demo/D_NTMIGRATEOk to establish pointer(Y/N) = YSETFILE completed.:CT VOC NTMIGRATEVOC: NTMIGRATE:DIR/usr/ud61/demo/NTMIGRATE/usr/ud61/demo/D_NTMIGRATE:

Compile the UniBasic Tools ProgramsYou must compile the following UniBasic programs in the NTMIGRATE file:

NT_SCOUTBUILD.FULL.PATHTAR2FTPNT_CATALOG_MAP

You do not need to compile NT_UPDATE_PATHS or SQL_UNIX_2_NT at this time, because you execute those programs on your Windows platform.

UniData Migration Tools 2-8

Special Considerations for UniData SQLThe UniData migration tools can move all components of a UniData SQL account from UNIX to the Windows platform. Components include dictionaries, schema, and privilege tables. UniData also supplies the SQL_UNIX_2_NT tool to convert a privilege table from UNIX format to the Windows platform format. This section describes considerations specific to migrating the components of a UniData SQL account.

Migrating Schema and DictionariesUniData supports the ability to migrate schema and dictionaries generated under release 3.3.x or above of UniData on UNIX. However, you may encounter difficulties if you rename one or more data or dictionary files to resolve naming conflicts. Naming conflicts arise because Windows platforms are case insensitive. If you have two files on UNIX whose names differ only by case, you must rename one before moving your account to the Windows platform.

It is important to remember that case insensitivity affects views as well as base tables. For instance, if a UNIX account has a view called RENTALS and a view called Rentals, the names of their dictionaries are in conflict. The dictionary names (D_DV_RENTALS and D_DV_Rentals) differ only in case. You should rename one of the views before moving the account to the Windows platform.

Warning: Renaming a file or view does not update any views (or schema) generated using that file or view, so UniData SQL access may be disrupted when you resolve naming conflicts.

If NT_SCOUT identifies a catastrophic problem such as a file naming conflict, and views were generated on an affected file, the warning message includes the infor-mation that the problem will impact UniData SQL. Even after you resolve the file name conflict, you need to regenerate views and schema against one or more data files. IBM recommends you perform these steps before you move the account to the Windows platform. The following example shows the error message generated when a catastrophic problem affects UniData SQL:

...CATASTROPHIC -- Directory/file name conflict in 'Student' Name conflicts with 'STUDENT' and WILL affect your sql views...


If you fail to resolve a catastrophic item, you will lose data when moving your account to the Windows platform. If the item affects UniData SQL views and you resolve the item without regenerating views and schema, you will encounter problems in UniData SQL on Windows platforms.

Migrating privilege TablesUniData SQL stores information about SQL privileges for tables and views in a privilege table in each account. The privilege tables in a UNIX account contain UNIX style user names and numeric user IDs, which are invalid on Windows platforms. The following example shows a UNIX style privilege table:

:SORT privilege ALLSORT privilege ALL 11:05:29 Feb 12 2000 1privilege................. access.. field..... grant_op grantor... grantee... 0*&MAP& ALL 1 root PUBLIC0*&report& ALL 1 root PUBLIC0*CATEGORIES ALL 1 root PUBLIC...1026*RENTALS OWNER PUBLIC1026*TRIAL_VIEW1 OWNER PUBLIC1026*TRIAL_VIEW2 OWNER PUBLIC...PUBLIC*MENUFILE ALL 0 rootPUBLIC*RENTALS ALL 0 user01PUBLIC*STAFF ALL 0 root

Notice the UNIX style identifiers: 1026, user01, root.

Tip: Refer to the UniData SQL Commands Reference and Using UniData SQL for information about the privilege table.

The migration tool SQL_UNIX_2_NT creates a Windows-style privilege table from a UNIX-style table. A copy of the UNIX-style table is retained so that you can compare the two. The Windows style table observes the following rules:

The OWNER for all items in the privilege table is set to ADMINISTRATORS (the local Administrators group on the Windows machine)All privileges granted to PUBLIC on the UNIX side are retained for PUBLIC on the Windows platform.

Special Considerations for UniData SQL 2-10

Privileges granted to individual users on the UNIX side are not migrated to the Windows platform. After you run SQL_UNIX_2_NT, any member of the local Administrators group can use the UniData SQL GRANT command to make the privilege table consistent with your UNIX table.

Tip: If your system does not depend on privileges for individual users, consider replacing these with the appropriate grants to PUBLIC before you prepare your account to move from UNIX to a Windows platform. You will still need to convert the privilege table to Windows style, but there should be no impact at all to users.

The following example shows some entries in a Windows style privilege table that was generated from a UNIX style table:

:SORT privilege ALLSORT privilege ALL 12:28:14 Feb 20 2000 1privilege................. access.. field..... grant_op grantor... grantee... &MAP& OWNER PUBLIC&report& OWNER PUBLICCATEGORIES OWNER PUBLICCOURSES OWNER PUBLIC...PUBLIC*__V__VIEW ALL 0 ADMINISTRATORSPUBLIC*privilege ALL 0 ADMINISTRATORSPUBLIC*voc ALL 0 ADMINISTRATORS 52 records listed:


NT_SCOUTThe NT_SCOUT program evaluates a UniData UNIX account and identifies areas that need attention before you move the account to a Windows platform. NT_SCOUT detects and reports:

Case-sensitive file names.Case-sensitive record names in DIR type files.Reserved characters in file names (including record names in DIR type files). NT_SCOUT uses the list of reserved characters in the RESERVED.CHARS record.UniBasic commands that may behave differently on the Windows platform. NT_SCOUT uses the list of UniBasic commands in the ALT.BP.CMDS record.ECL commands that are excluded or may behave differently on Windows. NT_SCOUT uses the list of ECL commands in the ALT.ECL.CMDS record.VOC entries without corresponding files.

NT_SCOUT runs with a GLOBAL or a LOCAL option. The following table describes the options.

Parameter Description

LOCAL Processes only files that physically reside in the current account directory. This is the default if no option is specified.

GLOBAL Processes all files with entries in the VOC file of the account, regardless of physical location.

NT_SCOUT Options

NT_SCOUT 2-12

OutputNT_SCOUT creates three entries in the _HOLD_ file of the current account. The following table describes NT_SCOUT output.

NTMIGRATE.LOCNT_SCOUT also checks for a local NTMIGRATE file, called NTMIGRATE.LOC, in the current account. If there is no NTMIGRATE.LOC, NT_SCOUT creates this DIR file. The local NTMIGRATE file has two uses:

Stores the output from TAR2FTP (which you can execute from NT_SCOUT if you wish).Stores a UNIX text file called exclude.files, which lists program files in the current account that you do not want to preprocess. If you want to exclude program files, you must create both NTMIGRATE.LOC and exclude.files before you execute NT_SCOUT.

Using NT_SCOUTThe following sections describe how to use the NT_SCOUT program.


UNIX_NT_CATASTROPHIC List of findings that you should address before moving this account to the Windows platform. If you do not address these findings, they can cause data loss.

UNIX_NT_WARNING List of findings that you should review before running this application on the Windows platform. These findings may cause run-time errors or unexpected results from your application programs.

UNIX_NT_SUMMARY List of all findings from NT_SCOUT.

NT_SCOUT Output


Create exclude.files (Optional)

Before you execute NT_SCOUT in each account, decide if there are program files in the account that you do not want to preprocess. If there are, create the NTMIGRATE.LOC file and then create exclude.files, as shown in the example:

:CREATE.FILE DIR NTMIGRATE.LOCCreate DIR type file NTMIGRATE.LOC.Create file D_NTMIGRATE.LOC, modulo/1,blocksize/1024Hash type = 0Added "@ID", the default record for UniData to DICT NTMIGRATE.LOC.:AE NTMIGRATE.LOC exclude.filesTop of New "exclude.files" in "NTMIGRATE.LOC".*--: I001= TESTPROGS*--: FIFiled "exclude.files" in file "NTMIGRATE.LOC".:

Execute NT_SCOUT

Execute NT_SCOUT from the ECL prompt, as shown in the following example:

:RUN NTMIGRATE NT_SCOUT GLOBALInfo -- The following LOCAL program files won't be checked/PRODUCT_INFO/TERRIC/ACCOUNT/TESTPROGS CATASTROPHIC -- Directory/file name conflict in 'D_Student' Name conflicts with 'D_STUDENT' CATASTROPHIC -- Directory/file name conflict in 'Student' Name conflicts with 'STUDENT' and WILL affect your sql views Warning -- In the file 'BP' record 'TIMETEST1' OS commands may act different on NT Contains the command 'PCPERFORM' and may function differently on NT Line # 5 PCPERFORM "$UDTBIN/convhash CONVHASH.TEST"Warning -- In the file 'VOC' record 'denat' Contains the command 'DENAT' and may function differently on NT Line # 2 HDENAT.MENU Total Warning messages 5Total CATASTROPHIC messages 2 Do you want to build the FTP script?N

NT_SCOUT 2-14

In the example, notice that the program file “TESTPROGS” will not be evaluated because TESTPROGS is in the exclude.files record in NTMIGRATE.LOC.

Tip: NT_SCOUT prompts if you want to build the FTP script. If you answer “Y,” NT_SCOUT executes the TAR2FTP program. If you have CATASTROPHIC findings, you must fix those before moving your account. Do not build the FTP script until you have addressed all the CATASTROPHIC findings.

Correct All CATASTROPHIC Items

Print the output files from NT_SCOUT. UNIX_NT_CATASTROPHIC lists the findings you need to address before moving data files and programs to the Windows platform. The following example shows a sample UNIX_NT_CATASTROPHIC:

% more UNIX_NT_CATASTROPHIC Info -- The following LOCAL program files won't be checked/PRODUCT_INFO/TERRIC/ACCOUNT/TESTPROGS CATASTROPHIC -- Directory/file name conflict in 'D_Student' Name conflicts with 'D_STUDENT' CATASTROPHIC -- Directory/file name conflict in 'Student' Name conflicts with 'STUDENT' and WILL affect your sql views Total CATASTROPHIC messages 2

Before you move your programs and data files to the Windows platform, you must address all items in UNIX_NT_CATASTROPHIC. Simply moving files without resolving these issues can cause data loss. You may need to rename files or records, and you may need to make corresponding program changes, to resolve these issues.

Note: Users should not access the UniData account, beginning at the point where you make changes to file and/or record names. Allowing user access while addressing migration items may cause data loss or data inconsistency.

NT_SCOUT only identifies possible conflicts and problems in your UniData account. We cannot supply an automated solution to these conflicts and problems, because the correct solutions depend on your application and environment. Resolving these items may be time consuming, but is crucial to the success of your migration to the Windows platform. Refer to your UniData manuals and your UNIX and Windows platform documentation to help you determine the best ways to resolve these items.


Analyze WARNING Items

You can resolve WARNINGS (listed in UNIX_NT_WARNING) on either the UNIX or the Windows platform. These items will not cause data loss while you are moving programs and files, but they may cause runtime errors and other unexpected results when you attempt to run your application on the Windows platform. It is not necessary to resolve all these issues before you move your programs and data, but you need to identify which items must be addressed, and how they should be addressed. The Warnings report from NT_SCOUT helps you to size the conversion effort and determine if some items should be addressed before you move to the Windows platform.

Tip: The Warnings report can be very large. Some items are not problems; for instance, you will see a message for every instance of the SETPTR command, but you do not need to change them unless you used unsupported options. The more you have depended on the underlying operating system (using PCPERFORM for instance), the larger your conversion effort will be.

Back Up the Account

Consider creating and verifying a full backup of your UniData account at this time. A backup is particularly advisable if you have expended a lot of effort resolving migration items.

NT_SCOUT 2-16

NT_CATALOG_MAPNT_CATALOG_MAP is a UniBasic program that helps you recompile and recatalog your UniBasic application after you have moved an account to the Windows platform. NT_CATALOG_MAP analyzes your program files and catalog spaces on UNIX to create a paragraph that you execute after moving your account. When you execute the paragraph on the Windows platform, NT_CATALOG_MAP recompiles your application and catalogs programs globally, locally, or directly, as they were cataloged on UNIX.

OutputNT_CATALOG_MAP produces a paragraph called NT_RECATALOGGER in the VOC file of each account where it is executed. The paragraph resembles the following example:

:CT VOC NT_RECATALOGGERVOC: NT_RECATALOGGER:PA DISPLAY Compiling programs DISPLAY Now compiling file BPBASIC BP NUM_TSTBASIC BP BASIC_STATICBASIC BP TIMETEST1BASIC BP TIMETEST2 DISPLAY Now cataloging file BPCATALOG BP TIMETEST1 LOCAL FORCECATALOG BP _NUM_TST DIRECT FORCECATALOG BP _BASIC_STATIC DIRECT FORCE:


Using NT_CATALOG_MAPExecute NT_CATALOG_MAP from the ECL prompt, as shown in the following example:

:RUN NTMIGRATE NT_CATALOG_MAP No data retrieved from current (S)SELECT statement. 1 records selected to list 0. 2 records selected to list 0. BP 4 records selected to list 0. :

Note: You need to recompile and recatalog your application on the Windows platform, but you do not need to use NT_CATALOG_MAP for this purpose. You can compile and catalog manually or use a script of your choice.

NT_CATALOG_MAP 2-18

TAR2FTPTAR2FTP is a UniBasic program that analyzes a UniData account and produces an output file you can use as an FTP script. Execute TAR2FTP in each UniData account on your UNIX system, then move the output file to the Windows platform, edit the file, and use FTP to copy the programs and data files from UNIX to the Windows platform.

OutputWhen you execute TAR2FTP in a UniData account, the program creates a record called tar2ftp.out in the NTMIGRATE.LOC file in the current account. The tar2ftp.out record resembles the following example:

:!more NTMIGRATE.LOC/tar2ftp.out#unix acct name#passwordbin!mkdir ACCOUNT!mkdir ACCOUNT\SAVEDLISTS!mkdir ACCOUNT\TESTPROGS!mkdir ACCOUNT\SAVEDLISTSL!mkdir ACCOUNT\_PH_!mkdir ACCOUNT\_HOLD_!mkdir ACCOUNT\BP!mkdir ACCOUNT\CTLG!mkdir ACCOUNT\NTMIGRATE!mkdir ACCOUNT\AE_SCRATCH!mkdir ACCOUNT\__MASTER_TABLE!mkdir ACCOUNT\NTMIGRATE.LOCget /product_info/terric/ACCOUNT/VOC ACCOUNT\VOCget /product_info/terric/ACCOUNT/D_VOC ACCOUNT\D_VOCget /product_info/terric/ACCOUNT/D_SAVEDLISTS ACCOUNT\D_SAVEDLISTSget /product_info/terric/ACCOUNT/_PH_/O_TIME ACCOUNT\_PH_\O_TIMEget /product_info/terric/ACCOUNT/D__PH_ ACCOUNT\D__PH_...get /product_info/terric/ACCOUNT/STUDENT2 ACCOUNT\STUDENT2get /product_info/terric/ACCOUNT/D_NTMIGRATE.LOC ACCOUNT\D_NTMIGRATE.LOCget /product_info/terric/ACCOUNT/D_TESTPROGS ACCOUNT\D_TESTPROGSget /product_info/terric/ACCOUNT/D_STUDENT2 ACCOUNT\D_STUDENT2!convcode ACCOUNT!convdata -r ACCOUNT:


The output file contains:

Placeholders (lines beginning with #) where you will add your UNIX login ID and passwordCommands in FTP format to create necessary subdirectories in Windows and then copy files from your UNIX accountCommands to convert the machine format for data and index files after you move the account to the Windows platform

Using TAR2FTPThe following sections describe how to use the TAR2FTP program.

Execute TAR2FTP

Execute TAR2FTP from the ECL prompt, as shown in the following example:

:RUN NTMIGRATE TAR2FTP...../ACCOUNT/NTMIGRATE.LOC/tardir../ACCOUNT/NTMIGRATE.LOC/tarhash../ACCOUNT/D_TAPES../ACCOUNT/TAPES../ACCOUNT/D_TESTFILE../ACCOUNT/TESTFILE../ACCOUNT/D_DV_STUDENT_1../ACCOUNT/D_DV_TEST1../ACCOUNT/STUDENT2../ACCOUNT/D_NTMIGRATE.LOC../ACCOUNT/D_TESTPROGS../ACCOUNT/D_STUDENT2Now reprocessing tar to ftp format :

Note: Remember that you can execute TAR2FTP from NT_SCOUT. You will be prompted if you want to generate an FTP script. Be sure you run TAR2FTP after you resolve all the CATASTROPHIC items, so your FTP script reflects any changes you make to file names.

TAR2FTP 2-20

Move TAR2FTP Output to Windows Platforms

You can use FTP (ASCII mode) to move the tar2ftp.out text file (from NTMIGRATE.LOC in your current account directory) to your Windows platform. Copy the file to a directory one level higher than the account will be. (For instance, if the account directory will be \users\ACCOUNT, then copy tar2ftp.out into \users.)

Edit FTP Script

At minimum, you need to edit two lines in this file. At the top of the file, replace the lines beginning with “#” by a UNIX user ID and a UNIX password for the machine where the account currently exists. Use the DOS editor or Notepad to edit the lines in the file.

If you want to transfer files that were not included in tar2ftp.out (for instance, data files physically outside the account directory), you can add lines to include them at this time. If you want to move only a portion of the contents of the account directory, you can remove lines from tar2ftp.out.

Tip: Review tar2ftp.out carefully. If you are adding additional files, notice that you need to add commands to create necessary directories and subdirectories.


The following example shows a typical tar2ftp.out, with a UNIX login and password as the first two lines:

% more tar2ftp.outuser01x17abcqbin!mkdir ACCOUNT!mkdir ACCOUNT\SAVEDLISTS!mkdir ACCOUNT\TESTPROGS!mkdir ACCOUNT\SAVEDLISTSL!mkdir ACCOUNT\_PH_!mkdir ACCOUNT\_HOLD_!mkdir ACCOUNT\BP!mkdir ACCOUNT\CTLG!mkdir ACCOUNT\NTMIGRATE!mkdir ACCOUNT\AE_SCRATCH!mkdir ACCOUNT\__MASTER_TABLE!mkdir ACCOUNT\NTMIGRATE.LOCget /product_info/terric/ACCOUNT/VOC ACCOUNT\VOCget /product_info/terric/ACCOUNT/D_VOC ACCOUNT\D_VOCget /product_info/terric/ACCOUNT/D_SAVEDLISTS ACCOUNT\D_SAVEDLISTS...get /product_info/terric/ACCOUNT/D_TAPES ACCOUNT\D_TAPESget /product_info/terric/ACCOUNT/TAPES ACCOUNT\TAPESget /product_info/terric/ACCOUNT/D_TESTFILE ACCOUNT\D_TESTFILEget /product_info/terric/ACCOUNT/TESTFILE ACCOUNT\TESTFILEget /product_info/terric/ACCOUNT/D_DV_STUDENT_1 ACCOUNT\D_DV_STUDENT_1get /product_info/terric/ACCOUNT/D_DV_TEST1 ACCOUNT\D_DV_TEST1get /product_info/terric/ACCOUNT/STUDENT2 ACCOUNT\STUDENT2get /product_info/terric/ACCOUNT/D_NTMIGRATE.LOC ACCOUNT\D_NTMIGRATE.LOCget /product_info/terric/ACCOUNT/D_TESTPROGS ACCOUNT\D_TESTPROGSget /product_info/terric/ACCOUNT/D_STUDENT2 ACCOUNT\D_STUDENT2!convcode ACCOUNT!convdata -r ACCOUNT

Execute the FTP CommandUse the -s argument to supply the input file, as shown in the following example:

TAR2FTP 2-22

The script completes the following actions:

Creates the required directory structure.Copies the programs and data from UNIX.Executes the UniData convcode and convdata commands to convert machine format for UniBasic compiled programs and UniData hashed files, respectively. See “convcode, convdata, convidx” on page 2-24 for more information about these commands.

Note: The script always runs convcode and convdata, even if the machine format conversion is not needed. There is no harm in executing the commands in any case, but if you know you are migrating from a low byte machine, you can delete the commands from tar2ftp.out.


convcode, convdata, convidx

PurposeUniData includes three system-level commands for converting machine format between high-byte and low-byte platforms.

convcode converts UniBasic compiled programs.convdata converts UniData hashed files.convidx converts index files.

Run these commands in your UniData accounts after you move them if:

You migrated the application from a high-byte UNIX system to a Windows platform, andYou did not use TAR2FTP.

See the UniData Commands Reference for information about these three commands.

Using convcode, convdata, and convidxNote: If you copied your files and data with an FTP script created by the TAR2FTP program, you do not need to execute convcode or convdata. The FTP script executes the commands for you.

Execute these commands in each UniData account after you move the programs and files to the Windows platform.The following screens show output from the commands. For these examples, a modified demo database was migrated from an HPUX platform to a Windows platform. The first example shows output from convdata, run with the -r (recursive) option:

convcode, convdata, convidx 2-24

The next example shows the output from convcode:

The next example shows the output from convidx:


convcode, convdata, convidx 2-26

NT_UPDATE_PATHSNT_UPDATE_PATHS is a UniBasic program that searches the VOC file in a UniData account after it has been moved from UNIX to the Windows platform. The program displays UNIX directory paths from VOC entries and allows you to enter the appropriate Windows path. NT_UPDATE_PATHS then updates the VOC entries for the correct paths, converting UNIX-style slashes to Windows-style during the update. The NT_UPDATE_PATHS program calls the UniBasic subroutine BUILD.FULL.PATH to create Windows-style path identifiers.

Using NT_UPDATE_PATHSExecute NT_UPDATE_PATHS in your UniData accounts after you move the accounts and, if needed, converted machine formats.

Reset the VOC Pointer for NTMIGRATE

In your UniData account, change the VOC pointer to the NTMIGRATE directory so it points to the correct location on your Windows machine (udthome\NTMIGRATE, by default).

Reset the VOC pointer for CTLGTB

In your UniData account, change the VOC pointer to the CTLGTB file so that it points to the correct location on your Windows platform (udthome\sys, by default).

Warning: If you do not update the pointer to CTLGTB, NT_UPDATE_PATHS cannot execute.

Compile NT_UPDATE_PATHS

You need to compile this UniBasic program on your Windows platform, as shown in the following example:

:BASIC NTMIGRATE NT_UPDATE_PATHS Compiling Unibasic: \UNIDATA\NTMIGRATE\NT_UPDATE_PATHS in mode 'u'.compilation finished:


Execute NT_UPDATE_PATHS

Execute this UniBasic program from the ECL prompt, as shown in the following example:

:RUN NTMIGRATE NT_UPDATE_PATHSNT_UPDATE_PATHS 15:47:55 Feb 11 1999 The current file ID is savedlists The current path is 'SAVEDLISTSL'The path should be Press enter to accept existing path or 'D'elete pointercurrent working path is D:\users\test\demo

Note: NT_UPDATE_PATHS compiles and catalogs a called subroutine named BUILD.FULL.PATH, which UniData uses to update the VOC pointers in your account.

NT_UPDATE_PATHS 2-28

NT_RECATALOGGERNT_RECATALOGGER is a paragraph that UniData creates when you execute NT_CATALOG_MAP in a UniData account on UNIX. Run NT_RECATALOGGER after you move the account to the Windows platform to recompile and recatalog your application.

Using NT_RECATALOGGERYou cannot run NT_RECATALOGGER on Windows platforms unless you executed NT_CATALOG_MAP on UNIX. Run NT_RECATALOGGER after you move your account, convert machine type (if needed), and run NT_UPDATE_PATHS.

Execute NT_RECATALOGGER from the ECL prompt, as shown in the following example:

:NT_RECATALOGGERCompiling programsNow compiling file BP Compiling Unibasic: BP\NUM_TST in mode 'u'.Basictype is changed, BP\NUM_TST is compiling in mode 'p'compilation finished Compiling Unibasic: BP\BASIC_STATIC in mode 'u'.compilation finished Compiling Unibasic: BP\TIMETEST1 in mode 'u'.compilation finished Compiling Unibasic: BP\TIMETEST2 in mode 'u'.compilation finishedNow cataloging file BP:


SQL_UNIX_2_NTSQL_UNIX_2_NT is a UniBasic program that creates a Windows-style privilege table from a UNIX style privilege table. In the Windows-style table, the OWNER for all items is ADMINISTRATORS (the local Administrators group on the Windows platform). UniData maintains any privileges granted on the UNIX side to PUBLIC, but does not maintain privileges granted to individual users. However, the program keeps a copy of the UNIX-style privilege table for your reference.

SQL_UNIX_2_NT also checks to see if schema was migrated. If so, the program changes the value of Attribute 2, TABLE_OWNER, to ADMINISTRATORS in all records in the SQLTables file, the SQLColumns file, and the SQLStatistics file.

Note: On Windows platforms, the physical ownership of an object depends on who creates the object. If a member of the local Administrators group creates an object, the Administrators group is the owner. If a user who is not a member of that group creates an object, the individual user is the owner. This “group ownership” for administrators differs from UNIX, where objects created by the superuser, root, are owned by root. The UniData SQL privilege table reflects the group ownership for the Administrators group only. For internationalized versions of Windows platforms, UniData SQL uses the UniBasic SYSTEM(515) function to detect the localized name that corresponds to Administrators, and uses that group when creating records in the privilege table.

Using SQL_UNIX_2_NTExecute SQL_UNIX_2_NT after you complete the remainder of the migration steps.

Compile SQL_UNIX_2_NT

Compile the UniBasic program, as shown in the following example:

:BASIC NTMIGRATE SQL_UNIX_2_NT Compiling Unibasic: D:\UNIDATA\NTMIGRATE\SQL_UNIX_2_NT in mode 'u'.compilation finishedRun SQL_UNIX_2_NT

SQL_UNIX_2_NT 2-30

Run SQL_UNIX_2_NT

Execute the command at the ECL prompt, as shown in the following example:

:RUN NTMIGRATE SQL_UNIX_2_NT

The first time you run SQL_UNIX_2_NT in an account, the program makes a copy of the privilege table for your future reference. The copy is called unix_privilege. The program then clears all records from the privilege table and rebuilds the table by processing records from unix_privilege.

Tip: If you execute SQL_UNIX_2_NT more than once in an account, the unix_privilege file stays unchanged. However, UniData overwrites the privilege table each time you execute SQL_UNIX_2_NT. Any changes you made to privileges after the last run of SQL_UNIX_2_NT are lost. If you execute the program in an account where it was already run, you will see a warning message and be prompted whether to rerun the program.


Review the Results

You can display the contents of privilege and of unix_privilege, as shown in the following example:

:SORT privilege ALLSORT privilege ALL 12:51:47 Jun 15 1999 1privilege................. access.. field..... grant_op grantor... grantee... SQLColumns OWNER PUBLICSQLSpecialC OWNER PUBLIColumnsSQLStatisti OWNER PUBLICcsSQLTables OWNER PUBLICSTATES OWNERSTUDENT OWNERSTUDENT_1 OWNERTAPES OWNER...PUBLIC*sysobjects ALL 0 ADMINISTRATORSPUBLIC*sysprotects ALL 0 ADMINISTRATORSPUBLIC*sysusers ALL 0 ADMINISTRATORS 27 records listed:SORT unix_privilege ALL USING DICT privilegeSORT unix_privilege ALL USING DICT privilege 12:52:08 Jun 15 1999 1privilege................. access.. field..... grant_op grantor... grantee... 1026*SQLColumns OWNER PUBLIC1026*SQLSpecialColumns OWNER PUBLIC1026*SQLStatistics OWNER PUBLIC1026*SQLTables OWNER PUBLIC1026*STATES OWNER1026*STUDENT OWNER1026*STUDENT_1 OWNER1026*TAPES OWNER...PUBLIC*sysobjects ALL 0 terricPUBLIC*sysprotects ALL 0 terricPUBLIC*sysusers ALL 0 terric27 records listed:

Note: The examples were generated using an English-language version of Windows NT.

Remember the following points:

Privileges granted to PUBLIC on the UNIX system are unchanged on the Windows platform.

SQL_UNIX_2_NT 2-32

Ownership and privileges associated with individual users are not reflected in the new privilege table.The OWNER of all items in the privilege table is now ADMINISTRATORS (the local Administrators group). You must log in as a member of the local Administrators group on your Windows platform if you wish to grant other privileges, or create schema, for any of these items.If you wish to modify the new privilege table, use the UniData SQL GRANT and REVOKE commands to do so.


3Chapter

Managing and Using the UDTelnet Service

Introduction . . . . . . . . . . . . . . . . . . . . 3-3 Requirements for the UDTelnet Service . . . . . . . . . . 3-3Overview of Features . . . . . . . . . . . . . . . . . 3-5 Configurability . . . . . . . . . . . . . . . . . . 3-5 Direct Access to UniData . . . . . . . . . . . . . . . 3-5 Security . . . . . . . . . . . . . . . . . . . . 3-5 Secure Sockets Layer . . . . . . . . . . . . . . . . 3-6 Terminal Emulation . . . . . . . . . . . . . . . . . 3-6 Integration with UniData Serial Terminal Support . . . . . . . 3-7Configuring the UDTelnet Service . . . . . . . . . . . . . 3-8 Service Options . . . . . . . . . . . . . . . . . . 3-10 User Profiles . . . . . . . . . . . . . . . . . . . 3-13 Customizing User Profiles . . . . . . . . . . . . . . . 3-16 Generated Profiles . . . . . . . . . . . . . . . . . 3-19Starting, Stopping and Pausing UDTelnet . . . . . . . . . . . 3-21 Controlling UDTelnet from UniData Admin . . . . . . . . . 3-21 Controlling UDTelnet from the Control Panel. . . . . . . . . 3-22Configuring SSL for Telnet . . . . . . . . . . . . . . . 3-23

The UniData Telnet Service (UDTelnet) enables multiple users to log on to a single Windows platform to run UniData. With the UniData Telnet Service installed and started, your Windows platform exports a logon prompt to its network so that network users can log on and run UniData.


IntroductionThe UniData Telnet Service is a service that exports a logon prompt to a network. Users can log on through the logon prompt, and multiple users can work on the system at the same time. UDTelnet creates an alternate console window when a user runs programs other than UniData in that window, just as they would run in a console window.

When a user opens a UniData session through UDTelnet, UniData writes screen output directly to a socket. Using the socket is more efficient than writing screen output to the alternate console window.

When a user “shells out” from UniData to execute a non-UniData process (for instance, !DIR), UniData directs output to the alternate console window. This allows programs that write to “standard output” to function without modification under UDTelnet.

Requirements for the UDTelnet ServiceThis sections describes the requirements for the using the UDTelnet service.

Operating System

Your system must be running Windows NT 4.0 or greater, and have UniAdmin installed. UDTelnet runs with Windows Server and Windows Workstation.

Disk SpaceUDTelnet uses less than one megabyte of disk space. During the installation process, UniData installs the files for UDTelnet in the Telnet subdirectory in your \IBM\ud72\bin folder.

Memory

The UniData Telnet service and configuration screens take less than one megabyte of system memory to run. You need somewhat less than 1 MB of memory for every Telnet user logged into your system, over and above the memory required for the application.

Introduction 3-3

Note: For users logging in through Telnet and accessing the MS-DOS command prompt, UDTelnet is a CPU-intensive service. For such users, there is an impact on performance, which becomes more prominent as you add Telnet users. For instance, if users are logging in through Telnet to run DOS commands, the performance impact for a 100MHz Pentium processor is noticeable with 20 - 30 users logged in. In contrast however, this overhead is minimal for udt processes executing through Telnet, because UniData writes are handled through a socket.

Telnet Client

You must have a Telnet client running on your Windows system. The UDTelnet Service interacts with the existing Telnet client.


Overview of FeaturesThis section describes the features of the UDTelnet Service.

ConfigurabilityNote: You need to log on to the Administrator account or log on as a member of the local Administrators group to configure the UDTelnet Service.

Through UniAdmin, you can perform the following tasks to configure the UDTelnet Service:

Establish a default configuration for all users who access your system through UDTelnet.Create individual user profiles that establish session characteristics for each user. Create a combination of custom profiles and a default configuration.Set parameters, including the number of concurrent UDTelnet sessions and the number of logon attempts to allow each user.Make tuning changes that may affect performance for users logging in via UDTelnet to execute MS-DOS commands.

Direct Access to UniDataYou can configure the UniData Telnet Service so that users never see the Windows command prompt. Users can log directly on to UniData, or on to a custom application.

Security Users cannot log on through the Telnet Service unless:

They have a valid logon on the Windows workstation or domain.They belong to a local group that has the user privileges Access this computer from network and Log on locally assigned.

Overview of Features 3-5

These constraints mean that users logged on through Telnet have only the permissions already associated with their Windows system account, just as if they had logged on from the console.

Secure Sockets LayerWith this release, Secure Sockets Layer (SSL) technology has been implemented. SSL is a transport layer protocol that provides a secure channel between two commu-nicating programs over which arbitrary application data can be sent securely.

For UniData 6.0 and higher, the UniData telnet server, udt.exe has been changed to listen on two ports, the ordinary telnet port and an SSL port, defaulted to 23 and 992, respectively. Depending on the requested port by the client, either a nonsecure or secure connection will be established.

If a telnet session is started on a secured port (992 by default), all data transferred between the telnet window and the UniData database server is secured. For a more detailed description, see “Chapter 9, Using SSL” in Developing UniBasic Applications.

Terminal EmulationThe UniData Telnet Service provides any terminal emulation supported by UniData. UniData uses the udtermcap file to validate terminal settings. The udtermcap file, located in the udthome\include directory, contains definitions for terminals supported within UniData. By default, the UDTERMCAP file contains definitions for the following terminals:

VT100, VT200, VT300, VT400, VT420WYSE60ADDS-VPIN 9400IN 9400B

You can add terminal definitions to udtermcap, or modify the definitions, if you desire.


Integration with UniData Serial Terminal SupportConnecting the UniData Telnet Service with UniData Serial Terminal Support provides the same functionality for users logged in from “dumb” terminals and other serial devices.

Warning: Users cannot log on through the Serial Terminal service (UDSerial) unless UDTelnet is installed and running.


Configuring the UDTelnet ServiceNote: You need to log in to the Administrator account or log on as a member of the local Administrators group to configure the UDTelnet Service.

You configure the UniData Telnet Server through UniAdmin. Select one of the following methods to access the Telnet Server dialog box from UniAdmin:

From the UniAdmin menu, click Admin, then select Network Services, and then click UDTelnet Server.From the UniAdmin window, double-click Network Services, and then double-click UDTelnet Server.From the UniAdmin tool bar, click the UDTelnet Server icon, as shown in the following example:

UDTelnet ServerIcon


Regardless of the method you choose, the UDTelnet Server dialog box appears, as shown in the following example:

The following table describes the dialog tabs for Telnet Server.

Dialog Tab Use

Service Settings for maximum log on attempts, log on pause, log on timeout, termination pause, telnet port number, SSL port number, keep alive, and log on banner.

Users Allows you to specify a list of users that are allowed to connect to your Windows platform through UDTelnet.

Telnet Server Dialog Tabs

Configuring the UDTelnet Service 3-9

Service OptionsSelect the Service tab from the Telnet Server dialog box to view and edit parameters that govern the operation of the UDTelnet Service. A dialog box similar to the following example appears:

Set Telnet Port Number

Set the telnet port number that the UDTelnet service should monitor for client connections.

The default value for the Telnet Port Number is 23. IBM recommends that you not change this unless you have another service that requires socket 23.

Tip: In the TCP/IP protocol stack, certain sockets are reserved for specific services. The file %systemroot%\system32\drivers\etc\services on your Windows platform contains a partial listing of reserved sockets, excerpted from Internet RFC1060. Use the listing as an aid to identify available sockets.


Set SSL Port Number

Set the SSL port number that the UDTelnet service should monitor for client connections.

The default value for the Telnet Port Number is 992. IBM recommends that you not change this unless you have another service that requires socket 992.

Set Connection Parameters

You can set the connection parameters described below through UniAdmin.

Set Maximum Logon Attempts

In the Maximum Logon Attempt box, enter the maximum number of attempts a user is allowed to enter a logon ID and password. Use the Maximum Logon Attempt arrows to choose the number of times. The default is 5.

Set Logon Pause Value

The number of seconds UniData pauses between logon attempts if a logon attempt fails. The default value is 4.

Set Logon Timeout Value

The number of seconds UniData waits for a response to a logon prompt. As soon UniData reaches this limit, it drops the telnet connection. The default value is 30.

Set Termination Pause Value

The number of seconds UniData pauses after the final failed logon attempt before it drops the telnet connection. The default value is 4.

Set Keep Alive Parameters

You can set the keep alive parameters described below through UniAdmin.


Keep Alive Interval

The interval separating keep alive transmissions until a response is received. The default value is 1000 (1 second).

Keep Alive Time

The parameter controls how often TCP attempts to verify that an idle connection is still intact by sending a keep alive packet. The default value is 7,200,000 (2 hours).

Maximum Data Retransmissions

This parameter controls the number of times TCP retransmits an individual data segment before ending the connection. The default value is 5.

Set Backlog Queue Value

The maximum length of the queue of pending telnet connections. The default value is 14.

Select Detach Process

If you select this option, the UniData Telnet Service creates the UniData process (udt.exe) as a detached process.

Select Create Desktop

If you select this option, the UniData Telnet Service creates its own WinStation/Desktop and assigns it to the UniData process.

Specify Logon Banner

In the Logon Banner box, enter a message to display when a user successfully connects to UDTelnet.

Starting, Stopping, and Pausing the Telnet Server

Click Start to start the Telnet Server. The Start button appears dimmed unless the service is paused or stopped.


Click Stop to stop the Telnet Server. The Stop button appears dimmed unless the service is running.

Click Pause to pause the Telnet Server. The Pause button appears dimmed unless the service is running.

Click OK to save the new settings and exit the Telnet Server dialog box. Click Apply to save the new settings and keep the Telnet Server dialog box open. Changed settings do not affect Telnet sessions that are already started. New sessions started after the service parameters were changed use the new parameters. Click Cancel to exit the Telnet Server dialog box without saving changes.

User ProfilesSelect the Users tab to specify which users are allowed to connect to your system through UDTelnet, and to create custom user profiles.

A dialog box similar to the following example appears when you click the Users tab:


This dialog box enables you to specify a list of users that are allowed to connect to your Windows system through UDTelnet. At installation, UDTelnet is started with a default configuration that allows any user who can access your Windows system from the network to access the system through UDTelnet as well. This default behavior is acceptable in many instances. However, administrators may wish to grant only certain users Telnet access, or to create individual user profiles. The Users dialog box allows this flexibility.

Warning: If you remove the Default profile, no user can log on through UDTelnet unless you have created a specific profile for the user.

Default User Profile

When you first display the Users dialog box, you see an entry for DEFAULT in the User box. Highlight DEFAULT and click Edit to display the default profile. The following example illustrates a sample default profile.

Specify Default ShellIn the Default Shell box, enter the full path of an executable. In the default profile, this is set to udtbin\udt.exe, which starts a UniData session.


Specify Startup Directory

Enter the full path of the working directory to which you want to connect when you log on in the Startup Directory box. In the default profile, this is set to the UniData demo account.

Specify Arguments

In the Command Line box, enter any arguments you want to pass to the default shell. In the default configuration, this is blank.

Determine ANSI Version

Select the ANSI Version 3.x check box if you want to enable faster screen refreshes for terminals that support ANSI 3.x color. By default, this check box is not selected.

Determine How to Map Characters

Select the Use Redirection Chars check box if you want to map unprintable characters to printable characters. By default, this check box is selected.

Prompt for Working Directory

Select the Prompt Directory check box if you want the user to select a working directory when they log on. By default, this check box is not selected.

Note: If you want one or more users to see the MS-DOS prompt when they log on, edit the user profile or profiles so that the default shell is %systemroot%\system32\cmd.exe.

Click OK to return to the Telnet Server dialog box, or click Cancel to exit without saving changes.

Customizing User ProfilesComplete the following steps to create a customized profile for a user.


1. Add a ProfileClick New to add a user profile. The following dialog box appears:

Enter the logon name of the user, then click OK. Enter the logon name only (for instance, user01). Do not enter the domain name (for instance, do not enter ACCOUNTING\user01). When you click OK, a dialog box similar to the following appears:

UniData populates the dialog elements with the values from the Default Configuration. Click OK to accept those values, or edit one or more fields to customize the profile.

Note: If you deleted the Default profile, UniData displays a message when you attempt to add new user profiles. You must enter all the configuration settings manually, since UniData cannot copy them from the default profile.


2. Customize a ProfileTo edit a profile, highlight the user name in the User box, then click Edit. Consider the following points when customizing a user profile:

Specify a full path in the Default Shell box. You can use either drive letters or the Universal Naming Convention (UNC) to specify the path.By specifying the Startup Directory, you can direct different users to different startup directories, even if they are using the same default shell.You can allow users to choose their directory when they log on by selecting the Prompt Directory check box.If you do not know whether a particular terminal supports Version 3 Color, select the ANSI Version 3.x check box. Test the terminal; if screen colors are not displayed correctly, modify the user profile to clear the ANSI Version 3.x check box.

The following example shows a sample configuration that allows a user to log on through UDTelnet, select a starting directory, and access the MS-DOS command prompt. The default startup directory is C:\IBM\ud72\demo:

Changes to a user’s configuration are visible the next time the user logs in through UDTelnet.


Generated ProfilesIf you selected Prompt Directory in your Default Profile, UniData creates a profile for each user who would normally receive the default user profile. UniData creates the individual profiles the first time a user chooses a startup directory different from the default. The generated profile uses the same configuration settings as the default profile, with the exception of Startup Directory, which is set to the directory chosen by the user when they log on. The following examples show the effect of the Prompt Directory option. In the first example, the default user profile has Prompt Directory selected:

The following example shows the appearance of the screen when a user logs on:

Path (C:\IBM\ud72\demo) : \IBM\ud72\claireg


Notice that the default path is C:\IBM\ud72\demo, and the user is selecting an alternate startup directory, \IBM\ud72\claireg. Pressing ENTER starts a UniData session in \IBM\ud72\claireg. This logon session also creates a profile for the user, which you can view or edit from the Telnet Server dialog box. The generated profile is shown in the following example:

The next time the user logs on through Telnet, the default path is changed, as shown in the following example:

Path (\IBM\ud72\claireg) :


Starting, Stopping and Pausing UDTelnetYou can control the UDTelnet service from the UDTelnet Configuration dialog box or from the Control Panel.

Note: Pause and Stop have the same functionality. Once a user logs on through Telnet, their process is not affected by Pause or Stop. Pause and Stop both prevent additional users to log on through Telnet.

Controlling UDTelnet from UniData AdminYou can start, stop, or pause the UDTelnet Server Service from the Service tab in the Telnet Server dialog box.

Click Stop to stop the UDTelnet Service. Users already logged on can continue to work, but no additional users can log on through UDTelnet until you Start the service.Click Start to start the UDTelnet service (if it is stopped) or continue the service (if it is paused).Click Pause to pause the UDTelnet service. Users already logged on can continue to work, but no additional users can log on through UDTelnet until you Start the service.


Controlling UDTelnet from the Control PanelYou can start, stop, or pause the UDTelnet Service from the Control Panel. Select the Services icon from the Control Panel, and scroll through the list of services to display UniData Telnet Service. The Status column indicates whether the service is presently running, and the Startup column indicates whether the service is started automatically when you start your system. The following example shows the appearance of the Services window:

Notice the following points:

The UniData Telnet Service 7.2 is started. The UniData Telnet Service starts automatically when you start your system. This is the default configuration when you install UDTelnet.You can click Stop or Pause to stop or pause the service. Click Startup to switch between manual and automatic startup for the service.

Note: If you Pause the UniData Telnet Service from Control Panel, click Continue to resume the service. This is a difference in the interface from the Telnet Server dialog box.

Starting, Stopping and Pausing UDTelnet 3-21

Configuring SSL for Telnet

Server Side Configuration:

There are two files in the unishared directory on the server that you need to be familiar with, udtelnetd.conf and .udscrfile. Udtelnetd.conf is the UniData Telnet server configuration file, and .udscrfile is the security file containing the path to the security context file. Both of these files are located in the unishared/unirpc directory. The default location can be found by examining the registry record at HKEY_LOCAL_MACHINE\SOFTWARE\IBM\UniShared.

udtelnetd.conf - The UniData telnet server configuration file.udscrfile - The security file containing the path to the security context file.

udtelnetd.conf has the following format per line:

security_context_record_id password

Where security_context_record_id and password are the security context record ID and password used to get security context in a pregenerated security file (defined in .udscrfile). This security context record ID is system-wide, which means that the security context record identified by this ID will be used for all secure telnet connec-tions, rather than for a single user’s connection.

In addition, there are four new registry keys for SSL, found in HKEY_Local_Macyhine\Software\IBM\UniData\7.2\UDTelnetd.


The following table describes the registry keys for SSL.

Registry Key Description

BACKLOG This key controls the maximum number of concurrent clients requesting a connection. The default setting is 14 connections. This key applies to both secure and nonsecure telnet.

DEBUG_LEVEL This key controls udt.exe debug message logging for SSL processing and takes a value from 0 to 10, with a 0 setting indicating no logging. The log file is generated under /temp on the system drive with the file name tl_server_pid.log where pid is the process id for udt.exe. The default setting is 0.

SSL_LOGIN_BANNER This key defines the message text showed when a user first connects. The default message is “Welcome to IBM UniData Secure Telnet Server.”

TELNET_SSL_SOCK_NUM This key sets the telnet port number. The default setting is port 992.

SSL Registry Keys

Configuring SSL for Telnet 3-23

4Chapter

Managing and Using the UDSerial Service

Introduction . . . . . . . . . . . . . . . . . . . . 4-3 Requirements . . . . . . . . . . . . . . . . . . . 4-3Overview of Features . . . . . . . . . . . . . . . . . 4-5 Security . . . . . . . . . . . . . . . . . . . . 4-5 Terminal Emulation . . . . . . . . . . . . . . . . . 4-5 Logging . . . . . . . . . . . . . . . . . . . . 4-6 Integration with UniData Telnet Service . . . . . . . . . . 4-6Configuring the UniData Terminal Server . . . . . . . . . . . 4-7 Service Option . . . . . . . . . . . . . . . . . . 4-8 Port Configuration . . . . . . . . . . . . . . . . . 4-9 Control Keys . . . . . . . . . . . . . . . . . . . 4-12 Modem Options . . . . . . . . . . . . . . . . . . 4-13 Logon Script . . . . . . . . . . . . . . . . . . . 4-15 Auto Connection . . . . . . . . . . . . . . . . . . 4-16Starting and Stopping the UniData Terminal Server . . . . . . . . 4-18 Controlling UDSerial from UniAdmin . . . . . . . . . . . 4-18 Controlling UDSerial from the Control Panel . . . . . . . . . 4-19

The UniData Terminal Server (UDSerial) enables users to access UniData on a Windows platform through a modem or an asynchronous terminal connected through one of the Windows platform’s COM ports. A terminal or other serial device that is managed by the UniData Terminal Server also has complete Telnet access to the TCP/IP network where your Windows platform resides.

4-2

IntroductionThe UniData Terminal Server (also called UDSerial) is a software product that enables you to connect serial devices to your network. If you have UDSerial running on a Windows system, any serial device connected to the Windows system through UDSerial can have complete Telnet capabilities throughout the Windows network.

Functionally, UDSerial simply connects a device to Telnet. To run UniData through UDSerial, you must have both UDSerial and UDTelnet installed and running.

Tip: IBM recommends you install UDSerial even if your immediate plans do not include accessing UniData through an asynchronous terminal. UDSerial occupies a minimal amount of disk space. By default, the service is disabled on all ports when you install it, so it uses no system resources. By installing UDSerial, you are building in flexibility for future needs.

RequirementsYour system must meet the following criteria to use the UniData Terminal Server.

Operating System

Your system must be running Windows NT 4.0 (or greater). UDTelnet runs with Windows Server and Windows Workstation.

TCP/IP ProtocolYour system must have TCP/IP installed.

Note: Consult your Microsoft documentation for information about TCP/IP.

Serial PortsYour system must have one or more serial ports. These may be native ports built into the PC, or multiport cards (provided the cards have Windows drivers). UDSerial functions with any serial device that is supported by Windows platforms.

Consult your hardware documentation or hardware vendor if you are not sure whether a serial device or serial port is supported by your Windows platform.


Disk Space

UDSerial uses less than one megabyte of disk space.

Memory

The UniData Terminal Server and configuration screens take less than one megabyte of system memory to run. You need approximately 100Kb of additional memory for every UDSerial user logged on to your system, over and above the memory required for the application.

UDTelnet Service

To access UniData through UDSerial, you must also have the UniData Telnet Server (UDTelnet) installed and running. UDSerial connects asynchronous terminals to Telnet through the UDTelnet Service.

Introduction 4-4

Overview of Features

Security Users cannot log on through the Terminal Server unless:

They have a valid logon ID on the Windows workstation or domain.They belong to a local group that has the User Rights Access this computer from network and Log on locally assigned.

Because of these constraints, users logged on through the terminal server have only the permissions already associated with their Windows system account, just as if they had logged on from the console.

Terminal EmulationThe UniData Terminal Server can use any terminal emulation supported by UniData. UniData uses the udtermcap file to validate terminal settings. The udtermcap file, located in the udthome\include directory, contains definitions for terminals supported within UniData. By default, the UDTERMCAP file contains definitions for the following terminals:

VT100, VT200, VT300, VT400, VT420WYSE60ADDS-VPIN 9400IN 9400B

You can add terminal definitions to udtermcap, or modify the definitions, if you desire.


Logging The UniData Terminal Server writes a record to the Windows Event Log every time a user connects or disconnects, along with a record of what process the user executed, the result code from that process, and any Windows system errors that pertain to the Terminal Server.

Integration with UniData Telnet ServiceConnecting the UniData Terminal Server with the UniData Telnet Service (UDTelnet) provides the same functionality for users logged on through Telnet.


Configuring the UniData Terminal ServerNote: You need to log on as a member of your local Administrators group (or as the Administrator) to modify the configuration settings for the UniData Terminal Server.

You configure the UniData Terminal Server through UniAdmin. Select one of the following methods to access the Terminal Server dialog box from UniAdmin:

From the UniAdmin menu, click Admin, then select Network Settings, and then click UDSerial Server.From the UniAdmin window, double-click Network Services, and then double-click UDSerial Server.From the UniAdmin tool bar, click the UDTelnet Server icon, as shown in the following example:

Regardless of the method you choose, the Terminal Server dialog box appears, as shown in the following example:

UdSerial ServerIcon


The following table describes the dialog tabs for Terminal Server dialog box.

Service OptionThe Service dialog box enables you to configure your terminal service.

Set Escape Sequence

The Escape Sequence is the hexadecimal equivalent of the character string used as an escape from a remote system. The default 1d (hex equivalent of Ctrl-]). This option is not applicable for UniData.

Set Terminal Type

In the Terminal Type box, enter the terminal type used by a remote system. This option is not applicable for UniData.

Specify Logon BannerIn the Logon Banner box, enter a message to display when a user successfully connects to UDSerial.

Starting, Stopping, and Pausing the Telnet Server

Click Start to start the UDSerial Service. The Start button appears dimmed unless the service is paused or stopped.

Click Stop to stop the UDSerial Service. The Stop button appears dimmed unless the service is running.

Click Pause to pause the UDSerial Service. The Pause button appears dimmed unless the service is running.

Dialog Tab Description

Service Settings for escape sequence, terminal type, event logging level, and logon banner.

Ports Configuration settings for each serial port used by UDSerial.

Terminal Server Dialog Box Tabs

Configuring the UniData Terminal Server 4-8

Click OK to save the new settings and exit the Terminal Server dialog box. Click Apply to save the new settings and keep the Terminal Server dialog box open. Changed settings do not affect UDSerial sessions that are already started. New sessions started after you change the service parameters use the new parameters. Click Cancel to exit the Terminal Server dialog box without saving change

Warning: Do not stop the terminal server if UDSerial users are logged on. You could cause file corruption by disrupting writes in progress.

You can also control the UDSerial service from the Control Panel or from the MS-DOS command prompt.

Port ConfigurationConfiguring a port depends on the serial device to which you are attaching. You need to know about the characteristics of your terminal device to select the appropriate settings.

Click the Ports tab. A dialog box similar to the following appears:


To modify the configuration information for a port, either double-click the port name, or select the port name and click Properties. The Port Properties dialog box appears, similar to the following example:

By default this dialog box displays with the Settings tab selected. Notice that the dialog box offers additional dialog tabs for Modem Options, Logon Script, Auto Connection, and Control Keys.

Note: You can choose which ports to use with UDSerial. If you have COM ports that are reserved for other uses (for instance, serial printers or other software), you can leave those ports disabled in UDSerial configuration. Even if ports share the same serial card, they do not all have to be managed by UDSerial.

Select Baud RateThe baud rate is the Transmission speed of the port in bits per second (BPS). Refer to the vendor documentation for the hardware you are attaching to the port and select the appropriate value from the list.


Select Data Bits

Data bits are the number of data bits per character. Valid settings are 5, 6, 7, or 8. The most common setting is 8. Refer to your vendor documentation and select the appro-priate value from the list.

Select Parity

Parity determines the method of marking boundaries of characters. Parity can be none, even, odd, or mark. Consult your vendor documentation and select the appro-priate value from the list.

Select Stop Bits

Stop bits determine the method of marking the end of characters. Valid settings are 1, 1.5, or 2. The most common setting is 1. Refer to your vendor documentation and select the appropriate value from the list.

Set Flow Control

Flow Control determines the method for controlling data transmission between sending and receiving devices. Valid settings are Xon/Xoff, DTR/DSR, RTS/CTS, hardware, or none. Refer to your vendor documentation and select the appropriate value from the list.

Set Terminal Type

Set the terminal type to vt100. If the port is only used for direct access to UniData, you can set it to a valid entry in udtermcap.


Control KeysIf you select the Control Keys tab on the Port Properties dialog box, a dialog box similar to the following example appears:

Determine Escape Character

The value in the Escape Character box determines the character sequence to disconnect a session with a remote system and return your serial device to the Telnet prompt. You must enter this value as the hexadecimal equivalent of the actual sequence. The default is 1d (hex equivalent of Ctrl-]).

Set X on

X on is required if Flow Control in the Settings dialog box is Xon/Xoff. You must enter the value in hexadecimal. The default is 11 (hex equivalent of Ctrl-Q).

Set X off

X off is required if Flow Control in the Settings dialog box is Xon/Xoff. You must enter the value in hexadecimal. The default is 13 (hex equivalent of Ctrl-S).


Tip: If your terminal supports Xon/Xoff flow control, you probably do not need to modify the Control Keys.

Modem OptionsIf you have connected a modem to your COM port, and you want the modem to be managed by UDSerial, select the Modem Options tab from the Port Properties dialog box. A dialog box similar to the following example appears:

Enter Modem Initialization StringEnter the initialization commands for the modem, one command per line (for instance, auto answer and echo off) in the Modem Initialization String box.


The Modem Initialization string contains commands for the modem. Insert one command per line. For example, the following initialization string is proper if you are using a US Robotics Courier V modem and are using hardware flow control:

+++ Force modem back to Command mode ATH0 Hang up modem AT &R1 &I0 Disable flow control entirely AT &B0 & N0 Makes the serial port and connect rates equal AT &H1 &R2 Sets hardware flow control AT S0=1 Enables auto answer

The following example illustrates the Modem Options box using the initialization commands above:

Set Modem Delay

The value in the Modem Delay box determines the delay, in milliseconds, between each line in the initialization string. The default is 1000 milliseconds. Valid values are between 1000 and 5000.


Logon ScriptIf you select the Logon Script tab, a dialog box similar to the following example appears:

Enter Logon ScriptIn the Script window, enter a logon script, one input per line. The window is scrollable. The default is blank, meaning no string is sent to the remote computer.

Enter Delay

Enter the delay, in milliseconds, between each line of the logon script in the Delay box.

Determine Output Suppress

Check the Output Suppress check box to prevent the end user of the serial device from seeing the input string as it is passed to the remote computer.


Warning: Configuring a logon script (userid, password) is generally unwise for a terminal. Automatically passing an ID and password can compromise your security. If you are configuring a device such as a bar code reader, where a user cannot directly access your system, passing a preset user ID and password may be desirable. In either case, consider selecting Auto Connection.

Auto ConnectionSelect the Auto Connection tab if you want the device attached to your port to connect to a particular remote host.

Tip: Auto Connection is extremely useful for devices that do not accept direct user input, like printers or bar code readers. Auto Connection can also simplify the interface for users of terminal devices.

When you select the Auto Connection tab, a dialog box similar the following example appears:

Determine Auto Connect

Select the Auto Connect check box to enable Computer Name and Type.


Enter Computer Name

In the Computer Name box, enter the name or IP address of the computer to which you want to connect. The computer name must be resolvable by your Windows system.

Determine How to Activate Remote Connection

The Type box determines the method for activating the remote connection. The default is None. The following table describes valid Types.

Type Description

None Auto Connection is disabled.

CTS Connect/disconnect when CTS signal is raised/dropped. Will not work if Flow Control for this port is RTS/CTS.

DSR Connect/disconnect when DSR signal is raised/dropped. Will not work if Flow Control for this port is DTR/DSR.

Carrier Connect/disconnect when carrier is detected (RLSD) or dropped.

Always Connect/disconnect when UDSerial is started/stopped. Make sure there is a receiving host if you pick this Type.

Auto Connection: Valid Types


Starting and Stopping the UniData Terminal ServerYou can control the Terminal Server from the Terminal Server dialog box or from the Control Panel.

Controlling UDSerial from UniAdminYou can start, stop, or pause the UniData Terminal Server from the Service tab in the Terminal Server dialog box.

Click Stop to stop the UniData Terminal Service. Users already logged on can continue to work, but no additional users can log on through UDSerial until you Start the service.Click Start to start the UniData Terminal Service (if it is stopped) or continue the service (if it is paused).Click Pause to pause the UniData Terminal Service. Users already logged on can continue to work, but no additional users can log on through UDSerial until you Start the service.

Starting and Stopping the UniData Terminal Server 4-18

Controlling UDSerial from the Control PanelYou can start, stop, or pause the UniData Terminal Service from the Control Panel. Select the Services icon from the Control Panel, and scroll through the list of services to display UniData Terminal Service. The Status column indicates whether the service is presently running, and the Startup column indicates whether the service is started automatically when your system is restarted. The following example shows the appearance of the Services window:

Notice that, in the example, both the Telnet service and the Terminal Server are running.

Warning: Do not stop the terminal server if UDSerial users are logged on. You could cause file corruption by disrupting writes in progress.


5Chapter

UniData and Services

What Is a Service? . . . . . . . . . . . . . . . . . . 5-3Principal UniData Services . . . . . . . . . . . . . . . 5-4 Shared Basic Code Server (sbcs) . . . . . . . . . . . . . 5-4 Shared Memory Manager (smm) . . . . . . . . . . . . . 5-5 Clean Up (cleanupd) . . . . . . . . . . . . . . . . 5-6Monitoring UniData Services . . . . . . . . . . . . . . . 5-7 Log Files . . . . . . . . . . . . . . . . . . . . 5-8

UniData and ServicesThis chapter explains what services are, and describes services specific to UniData.


What Is a Service?A service is a background process that performs a specific task or set of tasks. Services wait in the background until they receive a request for their specific function. A number of standard Windows services run to control system processes, schedule commands, handle print requests, and to perform other similar functions. Consult your host operating system documentation for detailed information about the services that run on your system.

What Is a Service? 5-3

Principal UniData ServicesUniData Database services control your UniData environment. When a user starts a UniData session, the user’s process, called a udt, communicates with the services. The udt process runs with the permissions valid for the user, preventing inappropriate file access by the UniData services.

Lock tracking—smm records all UniBasic locks and semaphore locks, identifying which UniData user holds each. Process cleanup—At periodic intervals, the cleanupd service checks to see if terminated process flags have been set. If cleanupd detects a terminated process flag, it deletes the associated process from internal tables, removes any requests from the queue, and removes any messages sent to the terminated process. If cleanupd receives a message from a process, it checks to see if the message was sent from a terminated process. If so, it throws away the message.

Shared Basic Code Server (sbcs)The shared basic code server, sbcs, manages shared memory used by globally cataloged UniBasic programs. UniData starts sbcs when you execute startud and stops it when you execute stopud. The functions of sbcs include:

Loading and tracking globally cataloged programs—sbcs loads globally cataloged programs into shared memory as needed, and keeps track of the programs loaded and the number of processes executing each one. When a user executes a globally cataloged program, sbcs checks in shared memory, then takes the following actions:

If the program is already loaded, sbcs increments the counter for the number of users executing it, and tells the udt process which segment to attach to execute the program.If the program has not been loaded, sbcs loads the program into shared memory and starts a counter for it.

Periodically, sbcs checks shared memory and removes loaded programs that are no longer in use.Controlling shared memory—The sbcs daemon can attach up to 20 shared memory segments.


The maximum size of each segment for sbcs is determined by the UniData configuration parameter SBCS_SHM_SIZE. sbcs attaches segments as it needs to load globally cataloged programs, and releases memory back to the operating system when it is no longer needed.Process cleanup—At periodic intervals, the sbcs process checks the cleanupd service to see if terminated process flags have been set. If sbcs detects a terminated process flag, it removes all messages sent for the process. If the terminated process is the only process using a program in shared memory, it removes the program from shared memory. sbcs uses the process ID to determine if a message it receives is from a terminated process. If so, sbcs discards the message.

Shared Memory Manager (smm)The shared memory manager, smm, builds and manages structures and tables within shared memory. UniData starts smm when you start the UniData Database Service, and stops it when you stop the UniData Database Service.

UniData processes (udt processes) communicate with smm to request and return shared memory. The UniData processes request shared memory from smm for the following tasks:

License control—The smm process tracks the number of users for which a site is licensed, and prevents more than that number of users from logging on to UniData. smm also displays warning messages when a license is about to expire.User process tracking—When a user logs on to UniData, smm assigns an internal tracking number to the user’s process and records information about the process in tables within UniData.Buffering program variables.Storing query records and intermediate results.Storing select lists.Storing expression buffers.Managing a current modulo table for dynamic files.

Principal UniData Services 5-5

Process cleanup—At periodic intervals, the smm process checks the cleanupd service to see if terminated process flags have been set. If smm detects a terminated process flag, it checks all ipc IDs. If one of the ipc IDs is invalid, smm exits, bringing down UniData. smm also checks all process groups to see if a group leader terminated abnormally. If so, smm removes all self-created shared memory pieces and reclaims all global pages occupied by the terminated group. smm also corrects any inconsistencies the global control tables (GCT) may have. An inconsistency could exist if the process was updating a GCT when it terminated.

The startud command starts smm, which creates a control table (CTL) in shared memory. The CTL tracks all information about the shared memory segments that smm manages. The size of the CTL is related to the number of users on the system and to a series of configuration parameters.

Clean Up (cleanupd)The clean up process, cleanupd, detects terminated user processes at check time intervals. If cleanupd detects a terminated process, internal flags are set. The smm and sbcs services periodically check to see if cleanupd has set internal flags. If these services detect flags, each service performs the necessary clean up and resets its own flag to zero. The cleanupd service performs clean up that is not handled by smm or sbcs. When the smm and sbcs services have reset their flags to zero, the cleanupd service resets its flag to zero, makes the user process ID available, and frees the local control table.


Monitoring UniData ServicesTo monitor UniData services, click the Start menu, point to Settings, click Control Panel, and then double-click Services. A window similar to the following appears:

In the previous example, the UniData Database Service, NFA Server, ObjectCall Service, Telnet Service, and Terminal Server are all started. Automatic in the Startup column indicates that these services automatically start when you boot your Windows system.

Monitoring UniData Services 5-7

Log FilesThe sbcs, cleanupd, and smm services each record messages in a pair of logs in the udtbin directory. In addition, the udt process writes messages to a log file called udt.errlog if a UniData process encounters file corruption in a data file. The following table lists these log files.

Note: All messages written to the .errlog for a daemon are also written to the daemon log file. For example,if an error is written to the smm.errlog, the message also appears in the smm.log.

The udt.errlog fileIf a UniData process encounters file corruption in a data file during processing, UniData writes a message to the udt.errlog in udtbin. System administrators can monitor this log and take corrective action for the specified file.

The following example illustrates errors printed to the udt.errlog when a SELECT statement is executed against a corrupt file:

udtno=1,pid=937,uid=1172,cwd=/home/claireg,Jun 12 12:44:461:grpno error in U_blkread for file 'TEST', key '', number=3 udtno=1,pid=937,uid=1172,cwd=/home/claireg,Jun 12 12:44:461:blkread error in U_read_group for file 'TEST', key '', number=3 udtno=1,pid=937,uid=1172,cwd=/home/claireg,Jun 12 12:44:461:read_all_block_in_group error in U_gen_read_group for file ' ', key ' ', number=0

Daemon/Process Routine Messages Error Messages

smm udtbin/smm.log udtbin/smm.errlog

smm udtbin\smm.log udtbin\smm.errlog

sbcs udtbin\sbcs.log udtbin\sbsc.errlog

cleanupd udtbin\cleanupd.log udtbin\cleanupd.errlog

udt N/A udtbin\udt.errlog

startud udtbin\startud.log udtbin\startud.errlog

Log Files for UniData Daemons and Processes


6Chapter

UniData and Memory

Windows Platforms and Shared Memory . . . . . . . . . . . 6-3UniData and Shared Memory . . . . . . . . . . . . . . . 6-4 smm and Shared Memory . . . . . . . . . . . . . . . 6-4 Learning about Global Pages . . . . . . . . . . . . . . 6-11 Learning about Local Control Tables . . . . . . . . . . . 6-12 sbcs and Shared Memory . . . . . . . . . . . . . . . 6-14 Self-Created Segments . . . . . . . . . . . . . . . . 6-14

This chapter describes how to configure, attach, and release shared memory.


Windows Platforms and Shared MemoryShared memory is a region of memory that more than one process can access. Shared memory resides on a Windows system outside the address space of any process. It is partitioned into segments. As a process requires memory, the process attaches a segment to its own address space. Processes use system-level calls to create, attach, and release shared memory segments.

Windows Platforms and Shared Memory 6-3

UniData and Shared MemoryUniData interacts with shared memory by using system-level calls, UniData services, and UniData configuration parameters to build its own structures in shared memory.

UniData defines shared memory segments that can be attached by UniData processes. The sbcs (shared basic code server) service creates shared memory structures for storing active globally cataloged UniBasic programs.

The smm (shared memory manager) service creates shared memory structures for internal tables required by UniData processes. UniData processes request memory for:

Buffering UniBasic variablesStoring intermediate resultsStoring a current modulo table for dynamic files

smm and Shared MemoryThe shared memory manager (smm) creates shared memory segments as needed. The size and characteristics of segments smm or the UniData Database Service create are determined by UniData configuration parameters. Whenever UniData starts, it reads the udtconfig file located in udthome\include and stores these values in shared memory. smm subdivides each of its segments into global pages, and subdivides each global page into local pages.

smm also creates and maintains internal tables that track the use of the structures it creates. These internal tables, stored in a shared memory structure called CTL, allow smm to protect shared memory pages against accidental overwriting, and to optimize the efficiency of memory use by releasing unneeded shared memory pages back to the operating system.

Control Table List (CTL)

When you start UniData, smm creates one shared memory segment for the UniData control table list (CTL). The CTL remains in memory as long as UniData is running, and is returned to the operating system when you stop UniData.


CTL is subdivided into three regions, as shown in the following figure:

Control Table List (CTL)

Virtual Memory Poolsharedmemorypool

Control Table List

shared memory segment

LCT

local page

CTL

GI GCT GCT GCT GCT LCT LCT

generalinformation global

controltable Process Information

Counter TableMemory Information

Control Information

localcontroltable

UniData and Shared Memory 6-5

The following table describes the structures in the CTL.

smm creates the CTL by using a series of configuration parameters. The following table lists the parameters smm uses to compute the size of CTL.

CTL Structure Description

GI Segment header; also called general information table.

GCTs (global control tables)

Each GCT records the use of global pages in a shared memory segment. UniData determines the number of GCTs in the CTL by the configuration parameter SHM_GNTBLS. SHM_GNTBLS must not exceed the kernel parameter shmmni.

LCTs (local control tables)

Each LCT records the shared memory activity of a UniData process group. UniData determines the number of LCTs in the CTL by the configuration parameter NUSERS. Each LCT comprises four subtables: PI, CT, MI, and CI. A process group is related to a process group leader, or a user executing UniData system-level commands from the operating system level.

PI (process information) table

Each PI table registers all processes within a process group.

CT (counter table) Each CT records information about the behavior of the process group.

MI (memory information) table

Each MI table records all global pages or self-created shared memory segments used by the process group.

CI (control information) table

Each CI table records all blocks allocated from shared memory for temporary buffers.

Structures Within UniData’s CTL

Configuration Parameter Description

SHM_GNTBLS The number of GCTs in the CTL, which is also the maximum number of shared memory segments that UniData can attach at one time.

NUSERS The number of LCTs in the CTL, which is also the maximum number of UniData process groups that can run at the same time.

SHM_GNPAGES The number of global pages in a shared memory segment.

Configuration Parameters for CTL Structures


The size of the CTL is the sum of the size required for the GI table, the GCTs, and the LCTs. You can calculate these by following these steps:

1. The size of the GI table is fixed at 69 bytes.2. Compute the space (in bytes) needed for GCTs:3. ((2+SHM_GNPAGES)*4)*SHM_GNTBLS4. Compute the space (in bytes) needed for LCTs: 5. ((96+(4*SHM_LPINENTS)+

(12*LMINENTS)+(8*SHM_LCINENTS))*NUSERS6. Add the values from the first three steps.

You can also use the UniData command shmconf to calculate the size of CTL.

Note: The size of the shared memory segment reserved for CTL does not need to match the size of the segments smm manages. All the segments managed by smm are the same size (computed by multiplying the number of global pages per segment by the size of a global page by 512), but they are not necessarily the same size as CTL.

SHM_LPINENTS The number of entries in the PI table of each LCT, which is also the number of processes that can be included in a UniData process group.

SHM_LCINENTS The number of entries available in the CI table of each LCT; this is the maximum number of local memory segments that can be used by a process group at one time. A local segment is made up of one or more contiguous local pages.

SHM_LMINENTS The number of entries available in the MI table of each LCT; this is the maximum number of global pages or self-created memory segments a process group can use at one time.


Configuration Parameters for CTL Structures (continued)


Creating and Assigning Memory Structures

When a UniData process requests memory, smm assigns one or more global pages, as requested, and updates the GCT (or GCTs, if global pages are assigned from more than one shared memory segment). smm also updates the information in the LCT of the requesting process. When the requesting process finishes using the assigned memory, the process sends a message to smm, which releases the global page or pages and updates the GCTs and LCT.

The following figure illustrates the smm shared memory structures:

Memoryvirtual memory pool

sharedmemorypool



global page

global page

local page

CTL


UniData determines the size and number of local pages per global page, and the size and number of global pages per segment, by configuration parameters. The following table lists these parameters and some of the relationships between them.

smm reserves some memory for requests and releases unused memory to the operating system. The following table describes UniData configuration parameters that smm uses to determine how much memory to reserve and how much to release.


SHM_LPAGESZ The size (in 512-byte blocks) of a single local page of shared memory.

SHM_GPAGESZ The size (in 512-byte blocks) of a global page of shared memory. SHM_GPAGESZ must be an integral multiple of SHM_LPAGESZ. Divide SHM_GPAGESZ by SHM_LPAGESZ to obtain the number of local pages in a global page.

SHM_GNPAGES The number of global pages in a shared memory segment. Compute the size, in bytes, of a shared memory segment by multiplying the size of a single global page (512*SHM_GPAGESZ) by the number of global pages per segment (SHM_GNPAGES). This total cannot exceed the maximum segment size defined by your operating system.

Configuration Parameters for Memory Structure Sizes


SHM_FREEPCT Percentage of global pages in a shared memory segment that should be kept free. If the percentage of free pages in a segment drops below this value, smm creates a new segment to handle requests.

SHM_NFREES Number of free shared memory segments that should be kept for UniData. If the number of free segments is larger than this value, smm releases the additional segments back to the operating system. If the number drops below this value, smm creates another segment. This parameter is usually set to one.

Configuration Parameters for Creating Shared Memory Segments


Displaying Parameter Settings

Use the UniData system-level command sms -h to display the current settings for configuration parameters related to shared memory. The following screen shows the output for this command for a system with a 32-user license:

C:\UniData71\Bin>sms -hShmid of CTL: 1094717696-------------------------------- IDs ---------------------------------smm_pid smm_trace PtoM_msgqid MtoP_msgqid ct_semid (values)108 0 0 1 -2126512128(1,1,1)

-------------------- GENERAL INFO ---------------------SHM_GNTBLS = 40 (max 40 global segments / system)SHM_GNPAGES = 32 (32 global pages / global segment)SHM_GPAGESZ = 256 (128K bytes / global page)

NUSERS = 128 (max 128 process groups / system)SHM_LPINENTS = 10 (max 10 processes / group)SHM_LMINENTS = 32 (max 32 global pages / group)SHM_LCINENTS = 100 (max 100 control entries / group)SHM_LPAGESZ = 8 (4K bytes / local page)

SHM_FREEPCT = 25SHM_NFREES = 1SHM_FIL_CNT = 2048JRNL_BUFSZ = 53248N_FILESYS = 200

C:\UniData71\Bin>

Note: See “Appendix A UniData Configuration Parameters,” for further information about these parameters.

Learning about Global PagesThe gstt command displays information about smm’s use of global pages in shared memory.

Syntax:

gstt


The following example shows the output from the gstt command:

# gstt--------------------- GCTs Statistics ------------------- Total GCTs (GSMs allowed): 50Pages/GSM................: 32 (4096K bytes)Bytes/Page...............: 128K bytes GCTs used (GSMs created).: 1 (2% of 50) Active GSMs....: 1 (32 pages in total, 4096K bytes) Pages Used...........: 2 (6%, 256K bytes) Pages Freed..........: 30 (94%, 3840K bytes) Inactive GSMs..: 0 Pages Freed..........: 0 (0K bytes) Total Pages Used......: 2 (6%, 256K bytes) Total Pages Freed.....: 30 (94%, 3840K bytes) Total memory allocated: 4096K bytes ----------------- End of GCTs Statistics ----------------

Tip: Use the output from gstt, along with the visual display from sms, to monitor use of shared memory segments. We recommend increasing the number of GCTs (SHM_GNTBLS) if the value of GCTs used is consistently higher than 80%.

Learning about Local Control TablesThe lstt command displays information about local control tables in shared memory. Each local control table tracks resource use for a udt process.

Syntax:

lstt [-l n | -L pid]


The following screen shows the output from lstt entered with no options:

# lstt----------------------- LCTs Statistics ----------------------- Total LCTs (Process Groups allowed): 50 LCTs Used (Active Process Groups): 1 (2% of 50) Total Ps: 2 Total Global Pages Used: 2 (256K bytes) Total Self-created.....: 0 (0K bytes) Total memory used......: 256K bytes -------------------- End of LCTs Statistics -------------------

Tip: Use the output from lstt, along with the visual display from sms, to monitor use of local control tables. IBM recommends increasing the number of LCTs (NUSERS) if the value of “LCTs used” is consistently higher than 80%. Also, if “Total Self-created” is consistently greater than zero, consider increasing SHM_GPAGESZ or optimizing your application to minimize use of self-created segments.

Use the -l or -L option to display additional information about a specific local control table. The following screen shows an example:

# lstt -l 1----------------------- LCTs Statistics ----------------------- Total LCTs (Process Groups allowed): 50 LCTs Used (Active Process Groups): 1 (2% of 50) Total Ps: 2 Total Global Pages Used: 2 (256K bytes) Total Self-created.....: 0 (0K bytes) Total memory used......: 256K bytes Statistics for LCT-1 (Leader’s pid: 24230) PI Entries Used (Processes): 2 (20% of 10) MI Entries Used (LSMs).....: 2 (6% of 32) Global Pages...........: 2 (256K bytes) Self-created...........: 0 (0K bytes) Total memory used......: 256K bytes CI Entries Used (BLKs).....: 6 (6% of 100) Local Blocks Used......: 5 Local Blocks Freed.....: 1 -------------------- End of LCTs Statistics -------------------

See the UniData Commands Reference for additional information about the parameters of the lstt syntax.


sbcs and Shared Memorysbcs creates structures in shared memory as needed for storing active globally cataloged UniBasic programs. The limits for structures created by sbcs are different from those for smm. The following table describes two udtconfig parameters that control the size of sbcs segments.

Self-Created SegmentsA UniData process can attach a segment of shared memory larger than a standard global page. UniData requires that a UniBasic variable read into memory be contained in a single global page. If a variable is larger than the size of a global page, udt creates a special segment in shared memory. These “self-created” segments, also called “indirect” segments, are attached to the requesting udt process and managed by smm. Some circumstances resulting in self-created segments are:

Editing a large report with AE. AE is a UniBasic program, and it reads a report in as a single variable.Reading a large array as a single variable.

smm creates a segment large enough to hold the variable. The self-created segment is counted as a global page used by the UniData process that created the segment.


SBCS_SHM_SIZE Size, in bytes, of shared memory segments created by sbcs. sbcs uses the segments to store globally cataloged programs. sbcs can attach a maximum of 20 segments.

MAX_OBJ_SIZE Maximum size, in bytes, of object code files that sbcs can be load into shared memory. sbcs loads object code files larger than this size into the user’s address space instead of shared memory.

Configuration Parameters for sbcs


Warning: Creating these segments of memory is not an efficient resource use, and may result in poor performance or in thrashing. Use the system-level lstt command or the ipcstat command to determine if your application is using self-created segments on a regular basis. If so, analyze the sizes of variables the application uses. Consider increasing the value of SHM_GPAGESZ (the size of a global page) to handle the variables. Also, consider modifying the application to read arrays by element rather than as a single variable.


7Chapter

Configuring Your UniData System

Configuration Procedure . . . . . . . . . . . . . . . . 7-3 Identify Disk Requirements . . . . . . . . . . . . . . 7-3 Identify Memory Requirements . . . . . . . . . . . . . 7-3 Verify Version Compatibilities . . . . . . . . . . . . . 7-4 Check/Reset System-Level Parameters . . . . . . . . . . . 7-4 Check/Reset UniData Configuration Parameters . . . . . . . . 7-4 Define Peripherals within UniData . . . . . . . . . . . . 7-5 Create UniData Accounts . . . . . . . . . . . . . . . 7-5 Add Windows Users. . . . . . . . . . . . . . . . . 7-6 Set Environment Variables . . . . . . . . . . . . . . . 7-6 Review UniData Security . . . . . . . . . . . . . . . 7-8 Convert Data Files . . . . . . . . . . . . . . . . . 7-9 Review Backup Procedures . . . . . . . . . . . . . . 7-9

Configuring Your UniData SystemThis chapter outlines configuration considerations that may be appropriate when you first implement UniData or when you make major changes to your system. Major changes include adding or reconfiguring hardware, installing a new software application, or upgrading or relicensing UniData.

This chapter does not present detailed information, but outlines the considerations and refers you to sources of additional information.


Configuration ProcedureIf you are installing or upgrading UniData, see Installing and Licensing UniData Products for estimates for initial disk and memory needs for your system. These estimates should be sufficient to allow you to install and start UniData with a minimal configuration.

1. Identify Disk RequirementsDisk space and disk configuration are key factors that determine system performance. The initial estimates in Installing and Licensing UniData Products should allow you to install and run UniData. However, we recommend that you evaluate your system, including your operating system, your hardware configuration, and your application, to develop accurate disk space requirements. IBM offers the following suggestions.

Disk Requirements—Use the largest expected size for your data files to estimate how much disk space you need. In certain applications, such as financial applications, the number of records varies in a predictable way over time. Your system must have enough disk space to handle the maximum number of records without difficulty.Disk I/O—For best results, configure your disk system so that access is balanced across all devices. IBM suggests the following:

\TEMP directory—Locate your \TEMP directory on a different physical drive from your data for improved performance.UniData accounts—If your application uses more than one UniData account, locate the account directories on separate drives to distribute load.

2. Identify Memory RequirementsThe initial estimates in Installing and Licensing UniData Products should allow you to install and run UniData with a minimal configuration. However, memory requirements can be platform dependent as well as application dependent. Estimate the memory required for the following components of your application:

The control table list (CTL)

Configuration Procedure 7-3

The memory segments controlled by smm The memory segments for sbcs

See Chapter 6, “UniData and Memory,” for information about estimating memory needs.

3. Verify Version CompatibilitiesIf you are considering major upgrades to your hardware or to your operating system, consult your IBM account representative early in your planning process to determine if your current UniData version is supported by the hardware or software you are considering.

4. Check/Reset System-Level ParametersDepending on your version of Windows, you may or may not be able to modify system-level parameters directly. You may need to adjust the following categories of parameters when you first implement UniData:

Memory—Review parameters that limit the number of shared memory segments system-wide, the maximum and minimum size of a segment, and the maximum number of segments per process. See Chapter 6, “UniData and Memory,” for additional information.Files and Users—Review parameters that define the maximum number of open files and file locks supported system-wide, the maximum number of files per user process, and the maximum number of user processes the system can support at one time. ipc Facilities—Review parameters that define the number and size of message queues, the number of semaphore sets and semaphores, and the number of semaphore undo structures your system supports.

5. Check/Reset UniData Configuration ParametersThe UniData udtconfig file, located in udthome\include, contains a set of parameters that are given default values when you install UniData. When you start a UniData session, UniData sets environment variables for each value in the udtconfig file.


Note: The udtconfig file is always located in udthome\include. Do not move the directory to another location, or UniData will not run.

The udtconfig file enables you to define values for each parameter that applies to your UniData environment. You can adjust most udtconfig parameters for your environment, but some should not be changed. Refer to “Appendix A UniData Configuration Parameters,” for detailed information about each udtconfig parameter.

You must log in as Administrator to modify udtconfig parameters.

6. Define Peripherals within UniDataYou must define tape devices, printers, and line devices within UniData before you can access them from UniData. Before defining a device within UniData, make sure that it is properly installed and functioning in your Windows environment. Refer to your operating system documentation for information about setting up peripherals on your system.

Use the ECL SETTAPE, SETLINE, and SETPTR commands to define your peripherals to UniData. See Chapter 14, “Managing Printers in UniData,” and Chapter 16, “Managing and Using Tape Devices,” for additional information.

7. Create UniData AccountsWhen you implement UniData, you may need to create one or more UniData accounts for your application. A UniData account is a directory that contains a UniData VOC file and its dictionary. The VOC file identifies commands, paragraphs, and all data files that are used in the UniData account. The data files may be in the same directory as the VOC file, or the VOC file may contain pointers to data files in other file systems. Your system may have a single UniData account or several, depending on your application.

Note: A Windows account (logon ID, password) is not the same as a UniData account. Every UniData user should have a separate Windows account (logon ID and password), but many users can access the same UniData account.

Use the Windows platform mkdir command and the UniData system-level newacct command to create UniData accounts. See your host operating system documentation for information about the mkdir command, and see Chapter 9, “Managing UniData Accounts,” for information about the newacct command.


8. Add Windows UsersAccessing UniData requires each user to have a logon ID and password on your Windows system. We recommend you create a separate Windows account for each UniData user. See your host operating system documentation for detailed information on creating Windows accounts. See Chapter 10, “Managing UniData Security,” for UniData-specific information.

9. Set Environment VariablesYou do not have to set the UDTHOME and UDTBIN environment variables on Windows platforms, unless your udthome and udtbin directories differ from those defined in the Registry. A user wishing to access UniData using a different udthome and udtbin than those defined in the Registry must have two environment variables set: UDTHOME and UDTBIN. The settings you assign for these variables depend on whether you performed a basic or an advanced UniData installation.

See Installing and Licensing UniData Products for information about installation types.

UDTHOME—This variable identifies the path of the UniData “home” directory. The home directory contains subdirectories UniData needs for processing.UDTBIN—This variable identifies the path for the directory that contains UniData executables. By default, udtbin is a subdirectory under udthome.

Setting UDTHOME and UDTBIN

You can add commands to set these environment variables to each user’s profile, if the user is accessing UniData with a different udthome or udtbin than defined in the Registry. Use the following commands to set these variables:

set UDTHOME \directory-nameset UDTBIN \directory-nameset PATH \directory-name


You can also set environment variables from the System window. From the Start menu, click Control Panel, and then double-click System. Click the Advanced tab, then click Environment Variables. A dialog box similar to the following example appears:

Enter the name of the environment variable you want to establish or change in the Variable box. Enter the setting for the environment variable in the Value box. Click Set to set the variable, or Delete to delete the variable.

Setting Additional Environment Variables

“Appendix B Environment Variables for UniData,” lists an additional set of variables that are significant for UniData users. These can be set in the same manner as the environment variables in the previous example before entering UniData.

Note: While you are in a UniData session, you cannot change environment variables for that session.


10. Review UniData SecurityDepending on your application, you may need to implement additional measures to ensure data security and separation of duties. Review your application and implement any or all of the following:

Default Permissions—Modify the default permissions for udthome and its contents that were set when you installed UniData.Users and domains—Assign UniData users to separate domains, and set permissions on your database so that each group of users has access to the data they need.VOC file—Customize your VOC file to limit access to powerful commands.Remote entries—Use remote pointers to files and commands to allow more fine-grained protection.SQL Privileges—For SQL access, use the UniData SQL GRANT and UniData SQL REVOKE commands to customize access to tables.Query Privileges—For UniQuery access, use the QUERY.PRIVILEGE file.

See Chapter 10, “Managing UniData Security,” for additional information.

11. Convert Data FilesDepending upon the nature of your system change, you may need to perform some conversion of UniData hashed files. Consider the following:

Schema—If you are implementing UniData ODBC or UniOLEDB, you may need to make UniData files accessible to UniData SQL, and you may also need to utilize the Schema API to incorporate ODBC compliance for field and attribute names. See Using VSG and the Schema API for detailed information.File characteristics—UniData also offers you the capability to convert files from static to dynamic, change file characteristics such as block size and modulo, change hashing algorithm for a static file, and change file format between high-byte and low-byte formats. See Chapter 11, “Managing UniData Files,” and the UniData Commands Reference for additional information.


12. Review Backup ProceduresSpecial considerations are needed to back up UniData accounts. Make sure your backup procedures have the following capabilities:

Subdirectories—Your backup procedure should be able to back up at least three levels of subdirectories. This is required to support UniData MULTIDIR and MULTIFILE files. Backing up selected files — Your backup procedure should allow you to input a list of files to back up. This is required to support full backups of UniData accounts. Simply backing up the directory that contains the VOC file may be insufficient, since data files are not necessarily located in the same directory as the VOC file. The ECL SETFILE command creates VOC entries with pointers to files in other locations. However, backup utilities may not follow these SETFILE pointers. To create a complete backup of an account, you need to make sure you back up and verify each physical file associated with the account.


8Chapter

Starting, Stopping, and Pausing UniData

Normal Operation . . . . . . . . . . . . . . . . . . 8-3 UniData Log Files . . . . . . . . . . . . . . . . . 8-3 Start UniData with startud . . . . . . . . . . . . . . . 8-4 Stop UniData with stopud . . . . . . . . . . . . . . . 8-5Pausing UniData . . . . . . . . . . . . . . . . . . . 8-6 The dbpause Command. . . . . . . . . . . . . . . . 8-6 The dbpause_status Command . . . . . . . . . . . . . 8-7 Resuming Processing . . . . . . . . . . . . . . . . 8-8Additional Commands . . . . . . . . . . . . . . . . . 8-9 Stopping a User Process with stopudt . . . . . . . . . . . 8-9 Stopping a User Process with deleteuser . . . . . . . . . . 8-10 Displaying ipc Facilities with ipcstat . . . . . . . . . . . 8-11 Stopping UniData with stopud -f . . . . . . . . . . . . . 8-12

This chapter describes procedures for normal startup and shutdown of UniData, and also describes commands used to log out users, stop processes, and remove ipc facilities, if needed. These commands are also documented in the UniData Commands Reference.

8-2

Normal OperationUse the UniData startud and stopud commands, respectively, for normal startup and shutdown. These commands start and stop the sbcs, cleanupd, and smm processes, in the correct order.

Note: You must log on as Administrator to execute startud or stopud. Make sure you define the environment variables UDTHOME and UDTBIN, and make sure your PATH includes udtbin. If you are running more than one version of UniData, make sure that these environment variables are set for the version of UniData you want to start and stop.

UniData Log Filesstartud makes entries in the log files (smm.log, sbcs.log, and cleanupd.log) that identify the system resources used by the daemons.

The following example is a sample sbcs.log:

%# type sbcs.log

SBCS version: 7.2

BEGSMALL = 1 BEGMED = 5 BEGLARGE = 20 BEGHUGE = 45Begsmall = 0 Begmed = 163 Beglarge = 490 Beghuge = 981Beginning of emergency area = 1638, size = 410Recover = 1 Debugmode = 0

Shm Attach Address: 0Shm Max. Size.....: 1048576SBCS process id...: 2474

IPC facilities:

q - 205 (request queue)q - 206 (reply queue)q - 207 (new version queue)m - 408


The next example shows a sample smm.log:

% type smm.logSMM version: 7.2

Number of users......: 16SMM checking interval: 60 secondsSMM process id.......: 108

IPC facilities:q - 0 (request queue)q - 1 (reply queue)m - 1094717696 (ctl)m - -1795163136 (glm)m - -1795163134 (shmbuf)s - -2126512128 (ctl)s - -2126512127 (journal)s - -2126512103 (SUPERRELEASE/SUPERCLEAR.LOCKS)s - -2126512128 (latch)s - -2126512127 (latch)s - -2126512126 (latch)s - -2126512125 (latch)s - -2126512124 (latch)s - -2126512123 (latch)s - -2126512122 (latch)s - -2126512121 (latch)s - -2126512120 (latch)s - -2126512119 (latch)s - -2126512118 (latch)s - -2126512117 (latch)s - -2126512116 (latch)s - -2126512115 (latch)s - -2126512114 (latch)s - -2126512113 (latch)

The next example is a sample cleanupd.log:

% pg cleanupd.log CLEANUPD daemon:CLEANUPD checking interval: 20 secondsCLEANUPD minimum interval: 10 secondsCLEANUPD process id.....: 880

Start UniData with startud The following screen shows the normal output from the startud command:

C:\UniData71\Bin>startudWait for Unidata Service to be started ...The Unidata Service has been started successfully.

Normal Operation 8-4

Note: When you install UniData for Windows Platforms, UniData installs the UniData Database 7.2 Service with a setting to automatically start when you boot your computer. You can change this setting to manually start the UniData Database Service 7.2. See your host operating system documentation for detailed information about starting and stopping services.

Stop UniData with stopudFor normal operation, use the stopud command with no options. You need to make sure users are logged out of UniData before you execute this command.

The following screen shows the expected response to the stopud command:

C:\UniData71\Bin>stopudDBpause is OFF.Stop Unidata Service now ...CLEANUPD stopped successfully.

The Unidata Service has been stopped successfully.#


Pausing UniDataThis section describes the commands you can use to temporarily suspend updates to your system.

The dbpause CommandUniData includes a system-level command that enables you to temporarily block updates to the database. You can use this feature to perform some tasks that require UniData to be stopped, such as backing up your data.

Syntax:

dbpause

You must log on as Administrator to issue the dbpause command.

dbpause blocks most updates to the database that are made within UniData. Writes or transactions in process when you issue the dbpause command are completed before dbpause takes effect. UniData blocks updates until the system administrator executes the dbresume command.

UniData does not block system-level commands, such as COPY or MOVE. In addition, UniData does not block updates to the _HOLD_ file and the _PH_ file, and does not interrupt report printing.

Note: Some UniData system-level commands require that UniData not be running. These commands do not execute successfully with dbpause in effect. You cannot stop UniData with dbpause in effect.

UniData does not block the following ECL commands when dbpause is in effect:

ACCT.SAVE, T.ATT, T.DUMPBLOCK.PRINT, BLOCK.TERMCHECKOVER, dumpgroup, fixfile, fixgroup, guideCLEAR.ACCOUNT, CLEARDATA, CLRCOMOCONFIGURE.FILE, HASH.TEST LIST.TRIGGER

Pausing UniData 8-6

DATE.FORMATCLEAR.LOCKS, DELETE.LOCKED.ACTION, LOCK, SUPER-CLEAR.LOCKS, SUPERRELEASEBLIST, VCATALOGdeleteuser, ipcstat, makeudt, stopudt, updatevocECLTYPE, UDT.OPTIONSFLOAT.PRECISIONHELPLINE.ATTLIST.INDEXLOGTO (unless a login paragraph exists in the account to which you are logging, and an action is defined in the login paragraph that is paused)MIN.MEMORYSET.DEC, SET.MONEY, SET.THOUS, SET.WIDEZEROSETOSPRINTER, SETPTR, SP.ASSIGN, SP.EDITTERMWHAT

The following example illustrates the output from the dbpause command:

C:\UniData71\bin>dbpauseDBpause successful.#

The dbpause_status CommandThe UniData system-level dbpause_status command returns information about the status of dbpause.

Syntax:

dbpause_status

The following example illustrates the output from the dbpause_status command when dbpause is in effect:

C:\UniData71\bin>dbpause_statusDBpause is ON.%


Resuming ProcessingTo resume processing after issuing the dbpause command, issue the dbresume command. User processes resume, and writes that were blocked when the dbpause command was issued complete.

Syntax:

dbresume

Note: You must log on as Administrator to issue the dbresume command.

The following screen illustrates the output from the dbresume command:

C:\UniData71\bin>dbresumeDBresume successful.#

Pausing UniData 8-8

Additional CommandsUniData provides a number of system-level commands to assist you in clearing users, processes, and system resources from UniData if needed. These commands are intended for removing hung processes, clearing ipc facilities for a clean start of UniData, or logging users and resources off for an emergency shutdown. These commands are listed in the following table.

Warning: Notice that stopudt, deleteuser, and stopud -f all carry the risk of disturbing the integrity of your data. You should never use them as a routine substitute for normal user logoff.

Stopping a User Process with stopudtThe stopudt command logs out a user, as opposed to stopud, which stops UniData.

Syntax:

stopudt pid

The argument pid is a system-level process ID, found in the USRNBR column of listuser command.


listuser Lists all current UniData users.

stopudt Logs a user out of UniData; a current write completes, but subsequent operations for that udt do not take place.

deleteuser Forces a user out of UniData and removes the user’s entry from the internal tables.

ipcstat Lists all ipc structures in use on the system; identifies those used by UniData processes.

stopud -f Forces all UniData processes to stop regardless of system activity.

UniData System-Level Commands


Use this command if you need to log out a user you cannot reach, or to clear a hung user process. The following screen shows the action of stopudt.

C:\UniData71\Bin>listuserLicensed(reg+pooled)/Effective Udt Sql iPhtm Pooled Total

( 32+10 )/42 2 0 0 0 2

UDTNO USRNBR UID USRNAME USRTYPE TTY IP-ADDRESS TIME DATE 1 3904 0 cgustafs udt pts/1 Console 11:21:04 Jan 31 2005

2 2052 0 cgustafs udt pts/2 Console 11:18:55 Jan 31 2005

C:\UniData71\Bin>stopudt 2052

C:\UniData71\Bin>listuserLicensed(reg+pooled)/Effective Udt Sql iPhtm Pooled Total

( 32+10 )/42 1 0 0 0 1


You must log on as Administrator to execute stopudt. If you run listuser immediately after stopudt, the user may still be included in the display. This is because the cleanupd process performs its checking and cleanup routines at a predefined interval.

Note: The argument for stopudt is the process ID (pid) associated with the udt process you are removing. Use the UniData listuser command, as shown in the preceding example. The pid is under the USRNBR column.

Stopping a User Process with deleteuserThe deleteuser command first tries to kill the udt process by sending UniData an internal signal equivalent to the UNIX kill -15 command. If this signal is unsuccessful after five seconds, it uses the Win32 API Terminate Process to kill that process.

Syntax:

deleteuser pid

The argument pid is the process ID.

Warning: Because deleteuser may execute the Terminate Process, it is particularly important that you verify the pid carefully.

Additional Commands 8-10

The following screen shows an example of the deleteuser command:

% listuserLicensed(reg+pooled)/Effective Udt Sql iPhtm Pooled Total

( 32+10 )/42 2 0 0 0 2


2 3820 0 cgustafs udt pts/2 Console 11:25:09 Jan 31 2005

# deleteuser 3904# listuserLicensed(reg+pooled)/Effective Udt Sql iPhtm Pooled Total

( 32+10 )/42 1 0 0 0 1


Note: You must log on as Administrator to execute deleteuser.

Displaying ipc Facilities with ipcstatThe ipcstat command displays a list of all ipc facilities (message queues, semaphores, and shared memory segments) in use on a system, and identifies those facilities used by UniData processes. You do not need to log on as administrator to execute ipcstat.

Syntax:

ipcstat [-q] [-m] [-s]

The following screen shows an example of ipcstat output:

C:\UniData71\Bin>ipcstat -mT ID SIZE CPIDm1115689280 4688384 1420 -> smm R7.2 (ctl)m-1459618815 358664 1420 -> smm R7.2 (msg)m-1459618816 4194304 1420 -> smm R7.2 (glm)m-1459618814 4194304 1420 -> smm R7.2 (buf)#

Notice that, because the -m option was specified, the output lists shared memory segments only. Use ipcstat -q to display message queues, ipcstat -s to list semaphores, and ipcstat with no options to list all ipc facilities.

Note: UniData does not use all the ipc facilities on the system. The output from ipcstat indicates which ones are used by UniData processes. The ones that correspond to “unknown” are not associated with UniData processes.


Stopping UniData with stopud -fThe stopud -f command stops all processes and UniData services regardless of activity on the system. Use this only if your system is hung and stopud fails.

Syntax:

stopud -f

The following example shows the expected output from stopud -f:

C:\UniData71\Bin>stopud -fDBpause is OFF.WARNING: 'stopud -f' will stop the Unidata system with force.This may not gurantee the consistency of the database files.

Would you like to continue?(y/n) [n]yStop Unidata Service now ...CLEANUPD stopped successfully.The Unidata Service has been stopped successfully.

You must log on as Administrator to execute stopud -f.

Warning: stopud -f may leave your database in an inconsistent state; use it as a last resort.

Additional Commands 8-12

9Chapter

Managing UniData Accounts

What Is a UniData Account? . . . . . . . . . . . . . . . 9-3Creating a UniData Account . . . . . . . . . . . . . . . 9-4Deleting an Account. . . . . . . . . . . . . . . . . . 9-8Clearing Space in UniData Accounts . . . . . . . . . . . . 9-9 CLEAR.ACCOUNT . . . . . . . . . . . . . . . . 9-9

This chapter describes UniData accounts and describes procedures used to create, save, and clear the accounts.

9-2

What Is a UniData Account?A UniData account is a directory that contains a default set of UniData files, including a VOC file and its dictionary.

Note: The system-level newacct command creates the default files UniData requires for an account.

The VOC file identifies commands, paragraphs, and all data files that are used in the UniData account. The data files may be in the same directory as the VOC file, or the VOC file may contain pointers to data files in other directories. Your system may have a single UniData account, or several, depending on your application.

Note: A Windows account typically means a logon ID, its associated password, and its default directory. There is no direct relationship between UniData accounts and Windows accounts (logon IDs). Many Windows users may access any UniData account. A Windows user’s default directory does not have to be (and usually is not) a UniData account.


Creating a UniData AccountThere are three steps required to create a UniData account:

1. Use the MS-DOS mkdir command to create the directory that will house the account. The name of the UniData account directory can be in uppercase, lowercase, or mixed uppercase and lowercase.

2. Make the new directory your working directory. You can change to the directory with the MS-DOS cd command.

3. Use the UniData newacct command to create the VOC and other UniData-specific files in the directory.

Note: You do not need to log on as Administrator to create a UniData account. However, you must have Change access in the account directory.

The following three screens illustrate how to create a UniData account. In the examples, the new account is names ACCOUNT, and is located in the UniData directory:

The first window shows creating the account directory:

The example illustrates executing the newacct command:

C:\IBM\ud72\ACCOUNT>newacctThe UDTHOME for this account is C:\IBM\ud72\.Do you want to continue(y/n)? y

Notice that the screen displays the current setting of UDTHOME and prompts you if you wish to continue.

Creating a UniData Account 9-4

The final window shows the contents of your new UniData account:

When you execute newacct, UniData creates the VOC file for the new account using a standard VOC file located in the sys subdirectory of your UniData home directory.

Tip: If you want to tailor your standard VOC file before creating new accounts, you may do so. There are a number of reasons you may wish to tailor your VOC file. You may want to add custom paragraphs, for instance, that all users should execute. IBM recommends that you save a copy of the standard VOC before making changes.

The following table describes the default subdirectories UniData creates with a new account.

Subdirectory Description

BP Used to store UniBasic source and object code.

CTLG Used to store locally cataloged UniBasic programs.

SAVEDLISTS Used to store SELECT lists.

SAVEDLISTSL Used to store temporary information for BY.EXP sorts. UniData automatically creates and deletes the contents of this subdirectory.

_HOLD_ Used to store print files.

Subdirectories in a UniData Account


UniData creates the subdirectories empty and populates them as the account is used.

The next table describes the UniData hashed files that UniData creates are created in a new account.

_PH_ Used to store output from background processes (created by the UniData ECL PHANTOM command) and captured terminal I/O (created by the UniData ECL COMO command).

_EDAXMAP_

_XML_

File Description

MENUFILE Stores user-generated menu definitions.

VOC VOC (vocabulary) file, containing references for ECL commands, sentences, paragraphs, and file names.

__V__VIEW Used to store UniData SQL view specifications.

privilege Used to store UniData SQL access privileges.

D_BP Dictionary for the BP file, which holds UniBasic programs.

D_CTLG Dictionary for CTLG.

D_MENUFILE Dictionary for MENUFILE.

D_SAVEDLISTS Dictionary for SAVEDLISTS.

D_VOC Dictionary for VOC.

D__HOLD_ Dictionary for _HOLD_.

D__PH_ Dictionary for _PH_.

D__REPORT_ Dictionary for _REPORT_.

Hashed Files in a UniData Account

Subdirectory Description

Subdirectories in a UniData Account (continued)

Creating a UniData Account 9-6

Note: See Developing UniBasic Applications and Using UniData SQL for information about UniBasic and UniData SQL

D__SCREEN_ Dictionary for _SCREEN_.

D___V__VIEW Dictionary for __V__VIEWS.

D_SAVEDLISTSL Dictionary for savedlists.

File Description

Hashed Files in a UniData Account (continued)


Deleting an AccountThere is no UniData command or utility that allows you to delete an entire account. If you need to delete an account, complete the following steps:

1. Analyze the database and identify which files you want to delete. Take care not to delete shared files that other UniData accounts still need.

2. Create and verify a full backup of at least the account you are going to delete.

3. Consider strategy. If the account is self-contained (that is, within one file system), you can use the MS-DOS rmdir /s command to delete the account directory. If the account has file pointers to other file systems, you may wish to use the ECL DELETE.FILE command to delete the files before removing the account directory. Use the ECL MAX.USER command to prevent inadvertent access to the UniData account.

Warning: Be careful with rmdir /s. This command removes all files and subdirectories below the directory you specify. If you have nested accounts (that is, a UniData account within a UniData account) and you remove an account directory with rmdir /s, you could remove more than one account.

Deleting an Account 9-8

Clearing Space in UniData AccountsUniData uses the _PH_ and _HOLD_ subdirectories of each account to store output from background processes and temporary print files, respectively. These subdirec-tories can become large, causing disk space problems. The UniData ECL CLEAR.ACCOUNT command removes all files from either or both of these subdirectories.

CLEAR.ACCOUNTSyntax:

CLEAR.ACCOUNT

You must log on to the UniData account you are clearing. You do not need to log on as Administrator, however, you must have write permission for the _PH_ and _HOLD_ directories and delete permissions for the files in the directories. When you issue the command, UniData prompts you for confirmation to clear each directory, as shown in the following example:

:WHEREC:\UniData71\ACCOUNT:CLEAR.ACCOUNTClear _PH_ directory(Y/N)? YClear _HOLD_ directory(Y/N)? Y

Notice that the ECL WHERE command displays the current account.

Warning: CLEAR.ACCOUNT removes ALL files from the subdirectories. Use this command only if you are certain none of the information is needed. Use the UniData DELETE command or the MS-DOS DEL command, if necessary, to remove only selected files.


10Chapter

Managing UniData Security

Customizing Permissions . . . . . . . . . . . . . . . . 10-3Customizing a VOC File . . . . . . . . . . . . . . . . 10-6 Removing Entries . . . . . . . . . . . . . . . . . 10-6Customizing UniData . . . . . . . . . . . . . . . . . 10-8Remote Items . . . . . . . . . . . . . . . . . . . . 10-10The SETFILE Command . . . . . . . . . . . . . . . . 10-12LOGIN and LOGOUT Paragraphs . . . . . . . . . . . . . 10-13UniData SQL Privileges . . . . . . . . . . . . . . . . 10-16Field-Level Security for UniQuery . . . . . . . . . . . . . 10-17 Points to Remember about Field-Level Security . . . . . . . . 10-17 The QUERY.PRIVILEGE File . . . . . . . . . . . . . 10-18 UniQuery Processing . . . . . . . . . . . . . . . . 10-20 Turning on Field-Level Security . . . . . . . . . . . . . 10-21

When you install UniData, UniData sets default permissions on system files and directories. After installing UniData, you may want to customize some permissions.


Customizing PermissionsTo customize permissions, from Windows Explorer, select the directories or files for which you want to customize permissions. Using the right mouse button, click the directory or file, click Properties, and then click the Security tab. The following dialog box appears:

Select the permissions you desire in the Permissions area, then click OK.

Customizing Permissions 10-3

IBM make a series of recommendations for customizing these permissions, as shown in the next table.

Directory or File Guidance

udthome\sys\CTLGTB Users responsible for cataloging or deleting cataloged programs need write permission. Other users need only read permission.

udthome\sys\DICT.DICT Users need only read permission. Administrators need write permission as well.

udthome\sys\VOC Users need only read permission. Administrators need write permission as well.

udthome\sys\CTLG Users, including programmers, need execute permission to this global catalog directory. In general, do not allow users to add or delete subdirectories to CTLG.

udthome\sys\CTLG\n and directories and files within these subdirectories

CTLG contains a subdirectory for each letter of the alphabet and one for symbols. Users need execute permission to these directories and read access to the files in them. Programmers may need Change permissions to the subdirectories and files so they can catalog or delete cataloged programs.

udthome\demo Use this directory for training and experimentation. Use any permissions settings that suit your situation.

udthome\sys\AE_BP All users with access to AE (the line editor) need read and write permissions.

Guidelines for Permissions for UniData System Files


When you create a UniData account, IBM suggests the following guidelines for setting permissions for the directory, subdirectories, and files in the account:

Direct Description

The account directory Only users who need to create files in the directory should have write permission.

BP Users need read and execute permissions so they can run UniBasic programs that are not globally cataloged. Programmers need write permission.

CTLG Users need read and execute permissions so they can run locally cataloged programs. Programmers and administrators need write permission so they can locally catalog and delete locally cataloged programs.

SAVEDLISTS Users need read and write permissions.

_HOLD_ Users need read and write permissions.

_PH_ Users need read and write permissions.

VOC (This refers to the account VOC file, not the master VOC file in udthome\sys.) Users must have read and write access to enter their accounts unless you have set the VOC_READONLY environment variable. See Using UniData for more information about the VOC file.

Suggested Permissions for a UniData Account

Customizing Permissions 10-5

Customizing a VOC FileThis section describes ways to customize your VOC file.

Removing EntriesDepending on your application, you may wish to prevent users from executing certain ECL commands. If you remove the entries corresponding to these commands from a VOC file in an account, users logged on to that account will not be able to execute them. When a user enters an ECL command, UniData searches the VOC file in the current account. If there is no corresponding entry, UniData displays an error message instead of executing the command.

The following example shows the results of deleting a VOC entry:

LIST VOC WITH @ID = COPY 19:03:11 May 23 2004 1VOC....... COPY1 record listed:DELETE VOC COPY'COPY' deleted.:COPY FROM DICT INVENTORY TO DICT ORDERS ALLNot a verb COPY

The following table lists ECL commands that create or modify UniData files, or allow users to execute system-level commands. You may want to consider removing some or all of these from the VOC files for your accounts. These commands allow users to perform the following tasks.

Command Description

! Escape to an MS-DOS shell prompt.

CLEAR.FILE Clears the data or dictionary of a file.

CNAME Changes a filename.

COPY Copies records.

CREATE.FILE Creates files.

VOC Commands Security


Note: You can remove entries from the UniData master VOC file (located in udthome\sys) or from the VOC files in one or more UniData accounts. The master VOC is installed as part of the UniData installation, and is used to build VOC files for your accounts when you execute the newacct command. If you remove commands from the master VOC file, and then create new UniData accounts, users in the new accounts will not be able to execute the commands you remove.

Tip: If you choose to modify the master VOC file, make sure you save a copy of it and its dictionary before you begin your modifications.

Warning: When you remove a VOC command entry, UniData no longer recognizes that command. UniData displays an error message if a user tries to execute the command, whether at the ECL prompt, or within a UniBasic program.

CREATE.INDEX Creates an alternate key index.

DELETE Deletes records from VOC or other files.

DELETE.CATALOG Deletes catalog entries.

DELETE.FILE Deletes a file.

DELETE.INDEX Deletes an alternate key index.

DISABLE.INDEX Disables an alternate key index.

ED Invokes the ED editor.

ENABLE.INDEX Enables an alternate key index.

MODIFY Modifies records in a data or dictionary file.

PTRDISABLE Disables a printer or queue.

PTRENABLE Enables a printer or queue.

RESIZE Resizes a file.

UPDATE.INDEX Updates an alternate key index.

Command Description

VOC Commands Security (continued)

Customizing a VOC File 10-7

Customizing UniDataThe UDT.OPTIONS command enables you to customize your UniData environment. UDT.OPTIONS 19 allows you to choose whether Administrators can bypass security restrictions created by removing entries from the VOC file. If UDT.OPTIONS 19 is on, UniData prevents even Administrators from executing commands after the entries are removed from the VOC.

If UDT.OPTIONS 19 is off (the default), UniData allows Administrators to execute ECL commands even if the command entries were removed from the VOC file. When a user logged on as Administrator executes a command, UniData first reads the VOC file in the current account, just as it does for any other user. If there is a matching entry, UniData executes the command. If there is no matching VOC entry, and if UDT.OPTIONS 19 is OFF, Administrators can still execute the command. The following table shows the behavior of UDT.OPTIONS 19.

UDT.OPTIONS 19 is turned off by default. Leave it off to allow a user with Admin-istrator privileges to execute commands that users cannot; turn it on to make Administrators consistent with other users.

UDT.OPTIONS 19 Command Status Behavior

ON VOC entry exists Administrators can execute commandOthers can execute command

OFF VOC entry exists Administrators can execute commandOthers can execute command

ON No VOC entry Administrators cannot execute commandOthers cannot execute command

OFF No VOC entry Administrators can execute commandOthers cannot execute command

UDT.OPTIONS 19


Note: See the UDT.OPTIONS Commands Reference for detailed information about the UDT.OPTIONS command.

Customizing UniData 10-9

Remote ItemsYou can further customize security by replacing some command entries in your VOC file with remote items. A remote item (R-type VOC record) allows a record definition to be stored in a location other than the VOC file. You can substitute remote items for sentences, paragraphs, commands, locally cataloged programs, or menus. See Using UniData for more information about R-type items.

R-type items enable you to customize security in two ways:

You can use a remote item as a pointer to a location with different Windows file permissions from the current account, limiting access to the item.You can supply a “security routine” for the remote item. R-type items name a cataloged subroutine that is executed when a user invokes the remote item. The subroutine must have one argument, and return a value of 1 (true) or 0 (false). When a user invokes a remote item with a security subroutine, the remote item does not execute unless the subroutine returns 1 (true).

The following screen shows an example of a remote item created for the ECL LIST command:

:LIST VOC F1 F2 F3 F4 WITH @ID = LIST 11:05:23 May 24 2004 1VOC....... F1........ F2............. F3............. F4............. LIST R OTHER_LIST LIST SECTEST21 record listed

With this VOC record in place, when a user executes the LIST command, UniData executes a security subroutine called SECTEST2. If that subroutine returns a value of 1, UniData executes the item called LIST in a file called OTHER_VOC.

The next screen shows the security subroutine:

:AE BP SECTEST2Top of "SECTEST2" in "BP", 4 lines, 66 characters.*--: P001: SUBROUTINE SECTEST2(OKAY)002: COMMON /SECUR/ VALID003: OKAY = VALID004: RETURNBottom.


In this example, the subroutine obtains the value of VALID from named COMMON. The value can be set by another subroutine or program. The following example shows what happens if VALID is zero (false) and a user executes the ECL LIST command:

:LIST VOC WITH F1 = PANot a verb LIST

The next example shows what happens if VALID is 1 (true):

:LIST VOC WITH F1 = PALIST VOC WITH F1 = PA 11:13:27 May 24 2004 1VOC....... ECLTYPECPCTSP.OPENlistdictLISTDICT6 records listed

Remote Items 10-11

The SETFILE CommandYou can also customize security by placing data files in a location with different NTFS permissions than your UniData account, and then modifying the corre-sponding VOC entries to point to the location. Use the SETFILE ECL command to establish the file pointers, as shown in the following example:

:SETFILE \USERS\SECURE\INVENTORY INVENTORYEstablish the file pointerTree name \USERS\SECURE\INVENTORYVoc name INVENTORYDictionary name \USERS\SECURE\D_INVENTORYOk to establish pointer(Y/N) = YSETFILE completed.

You can set the NTFS permissions at the location of the file to limit access. If a user with insufficient permissions tries to access the file, UniData displays an error message similar to the one shown in the following example:

:LIST INVENTORY ALLOpen \usr\SECURE\INVENTORY error.Open file error.:

See the UniData Commands Reference for information about the SETFILE command.


LOGIN and LOGOUT ParagraphsYou can define LOGIN and LOGOUT paragraphs in the VOC files of your accounts to provide further control of users’ environments. A typical LOGIN paragraph sets UDT.OPTIONS and then invokes an application menu. A typical LOGOUT paragraph executes a routine that cleans up application files and exits the application in an orderly manner. If you define the environment so that a user logs directly on to a UniData account and executes the udt command, and the LOGIN paragraph defines the UDT.OPTIONS and displays a menu, the user does not see either the MS-DOS command prompt or the ECL prompt.

The behavior of LOGIN and LOGOUT paragraphs are summarized as follows:

When you enter UniData, UniData checks the VOC file in the account you are entering for a LOGIN paragraph. If there is one, UniData automatically executes it.If you change accounts with the ECL LOGTO command, UniData does NOT execute the LOGOUT paragraph in the account you are leaving. UniData looks in the VOC file of the account you are entering, and executes the LOGIN paragraph there, if there is one. When you exit UniData, UniData checks the VOC file in your current account and executes the LOGOUT paragraph, if one is there.

Note: You can also use the ECL ON.ABORT command to prevent users from accessing the ECL or MS-DOS prompt. ON.ABORT defines a paragraph that executes whenever a UniBasic program aborts. See the UniData Commands Reference for information about ON.ABORT.

LOGIN and LOGOUT Paragraphs 10-13

The following sample session shows simple examples of LOGIN and LOGOUT paragraphs in a UniData account, and a different LOGOUT paragraph in a second account:

:WHEREC:\USERS\TEST:CT VOC LOGINVOC: LOGIN:PAUDT.OPTIONS 19 ONUDT.OPTIONS 20 ONDISPLAY ENTERING UNIDATA APPLICATION:CT VOC LOGOUTVOC: LOGOUT:PADISPLAY EXITING UNIDATA APPLICATION::LOGTO \UniData71\demo:CT VOC LOGOUTVOC: LOGOUT:PARUN BP EXIT_PROGDISPLAY LOGGING OUT OF UNIDATA:

In the preceding example, the second LOGOUT paragraph executes a program called EXIT_PROG, which simply prints a message. A user-written exit program can perform a variety of tracking and reporting functions.


The next example shows the response when two of these paragraphs are executed:

C:\USERS\TEST% udtUniData Release 6.1 Build: (3082)(c) Copyright IBM Corporation 2005All rights reserved.

Current UniData home is \UniData71.Current working directory is \USERS\TEST.ENTERING UNIDATA APPLICATION:LOGTO \UniData71\demo:WHEREC:\UniData71\demo:QUITEXITING THE INVENTORY APPLICATIONLOGGING OUT OF UNIDATA%

Notice that the LOGIN paragraph defines UDT.OPTIONS and then prints a message. A LOGIN paragraph can also execute a program, or display a menu. If a user’s .login or .profile file sets their working directory to a UniData account and executes the udt command, and the LOGIN paragraph defines the UDT.OPTIONS and displays a menu, the user does not see either the MS-DOS command prompt or the ECL prompt.

Notice also that logging out of UniData after the LOGTO command executes the LOGOUT paragraph of the current account only.

Note: If UDT.OPTIONS 20, U_IGNLGN_LGTO, is on, users logged on as an Admin-istrator can access an account through the LOGTO command without executing the LOGIN paragraph. If a user logged on as an Administrator accesses the account directly, UniData executes the LOGIN paragraph regardless of the setting of UDT.OPTIONS 20.

LOGIN and LOGOUT Paragraphs 10-15

UniData SQL PrivilegesWhen you create a UniData SQL table or view, you have exclusive UniData SQL access to it. Regardless of file permissions set at the system level, no other user can execute UniData SQL operations against the table or view until you grant privileges through the UniData SQL GRANT command. The UniData SQL REVOKE command allows you (or any other user with ALL privileges) to revoke privileges that were granted. UniData SQL privileges can be granted or revoked for an entire table or for specified commands.

Note: UniData and UniData SQL share data and dictionary files. Therefore, depending on the system-level file permissions, tables created in UniData SQL can be accessed by other UniData tools such as ECL or UniQuery. The GRANT and REVOKE commands affect UniData SQL operations only.

See the UniData SQL Commands Reference and Using UniData SQL for more information about UniData SQL privileges.


Field-Level Security for UniQueryUniData includes functionality to determine UniQuery access on a attribute-by-attribute basis.

System administrators can set privileges for UniQuery access at the file or attribute level for a single user or for all users in a domain by creating a QUERY.PRIVILEGE table in a specified format and adding records to that table.

You can also set a default for your system, defining all files as OPEN or SECURE. In an OPEN system, the ability to access a file or a field with UniQuery is a function of system-level file permissions, other UniData security implementations, and privi-leges granted using the QUERY.PRIVILEGE table. In a SECURE system, unless privileges are granted in the QUERY.PRIVILEGE table, users cannot access files through UniQuery, regardless of system-level permissions or other implementations.

Points to Remember about Field-Level SecurityRemember the following points about field-level security:

Implementing and maintaining field-level security is a completely manual process. You must create and populate the QUERY.PRIVILEGE file manually.ECL commands, such as CREATE.FILE, DELETE.FILE, and CNAME, do not update the QUERY.PRIVILEGE table.ECL commands are not affected by UniQuery security.The UniQuery MODIFY command is not affected by the UniQuery security feature. The security is imposed when a user attempts to SELECT.A default of OPEN or SECURE affects all UniData accounts that share the same udthome. You cannot define some accounts as OPEN and some as SECURE.Privileges granted on a file are not automatically applied to its dictionary. Therefore, if a user has ALL access to the INVENTORY file and its dictionary, you must consider D_INVENTORY as well. If the system default is OPEN, the user can access D_INVENTORY. Otherwise, if you want the user to access D_INVENTORY, you need a QUERY.PRIVILEGE record for D_INVENTORY as well.

Field-Level Security for UniQuery 10-17

The QUERY.PRIVILEGE FileUniQuery security depends on the existence of the QUERY.PRIVILEGE file, which must be located in udthome\sys. If this file does not exist, UniQuery functions as it has previously, with no field-level security.

Warning: If you create the QUERY.PRIVILEGE file, but do not populate the file with any records, UniData does not allow any user to access any files on the system through UniQuery.

When you install UniData, the UniQuery security is not implemented, and there is no QUERY.PRIVILEGE file. If you wish to turn this feature on, you must create QUERY.PRIVILEGE and D_QUERY.PRIVILEGE manually.

Records in the QUERY.PRIVILEGE file grant the SELECT privilege to users or groups of users, at the file level or the attribute level. Each QUERY.PRIVILEGE record has one attribute. The dictionary of the QUERY.PRIVILEGE file contains four records.

Following is a sample of the dictionary of the QUERY.PRIVILEGE file:

:LIST DICT QUERY.PRIVILEGELIST DICT QUERY.PRIVILEGE BY TYP BY @ID TYP LOC CONV NAME FORMAT SM ASSOC 15:20:26 Jun 02 2004 1@ID............ TYP LOC.......... CONV NAME........... FORMAT SM ASSOC..... @ID D 0 QUERY.PRIVILEGE 50L SPRIV D 1 PRIVILEGES 5R MFULLPATH V FIELD(@ID'*' File Path 25T S ,2)USERNAME V FIELD(@ID,'*' User Name 25T S ,1)4 records listed


The following table describes each QUERY.PRIVILEGE attribute.

Note: You can customize the length of the dictionary attributes in the QUERY.PRIVILEGE file. The length of @ID should be sufficient to contain the longest UNIX user name and the longest absolute path for a UniData file on your system. FULLPATH and USERNAME should be long enough to handle the longest absolute path and longest user name, respectively.

The following example shows a very simple example of a QUERY.PRIVILEGE file:

LIST QUERY.PRIVILEGE PRIV 15:28:31 Jun 02 2004 1QUERY.PRIVILEGE................................... PRIVILEGES user01*C:\UniData\demo\INVENTORY 1 2 3 4 5 11user01*C:\UniData\demo\CLIENTS ALLDEFAULT OPEN3 records listed

This QUERY.PRIVILEGE file means:

Except for INVENTORY and CLIENTS, which are in the demo database, all users have privileges to query all files in all accounts that share the same udthome.

Attributes Description

@ID Data attribute that defines the user or domain and the file for which you are setting privileges. If you are setting up a system default, @ID is DEFAULT. Otherwise, @ID must be of the format username*path, domain\ uername*path, or PUBLIC*path.

PRIV Data attribute that indicates the attributes to which you are granting privileges, by location. PRIV is a multivalued attribute. To grant privileges to all attributes in a file, set PRIV to ALL. If you are setting a system default, set PRIV to OPEN to grant privileges. To restrict privileges to every attribute in a file, set PRIV to SECURE.

FULLPATH Virtual attribute formula that designates the full path of the file affected by PRIV. This formula has the format FIELD(@ID,”*”,2).

USERNAME Virtual attribute formula that designates the user affected by PRIV. This formula has the format FIELD(@ID,”*”,1).

QUERY.PRIVILEGE Record Attributes


user01 can query the fields in positions 1, 2, 3, 4, 5, and 11 only in the INVENTORY file. No other user can query this file.user01 can query any field in the CLIENTS file. No other user can query the CLIENTS file.

UniQuery ProcessingIf you turn on the security feature by creating and populating the QUERY.PRIVILEGE file, every time a user logs on to UniData, their udt process reads the contents of QUERY.PRIVILEGE and stores the information for reference. Then, when a user attempts a UniQuery access, UniData checks the stored infor-mation, following these steps:

1. Check for privileges granted to the user’s domain.If the user’s domain has sufficient privileges for the requested access, allow the access. Otherwise, proceed to step 2.

2. Check for privileges granted specifically to the user.If the user has sufficient privileges for the requested access, allow the access. Otherwise, proceed to step 3.

3. Check for privileges granted to PUBLIC.Privileges granted to PUBLIC apply to all system users. If PUBLIC has suf-ficient privileges for the requested access, grant the access. Otherwise, proceed to step 4.

4. Check for a DEFAULT entry.If there is a DEFAULT record in QUERY.PRIVILEGE, and if the default is set to OPEN, allow the requested access. If there is no DEFAULT, or if the DEFAULT is SECURE, disallow the access, displaying the following message:No privilege on filename.

Turning on Field-Level SecurityComplete the following steps to implement the UniQuery field-level security feature:

1. Log on to your system as Administrator.UniData must be running. Users do not need to log off.


2. Create QUERY.PRIVILEGEChange your working directory to udthome\sys, and enter udt to start a Uni-Data session. Use the ECL CREATE.FILE command as follows:

:WHERE\UniData71\sys:CREATE.FILE QUERY.PRIVILEGE 101Create file D_QUERY.PRIVILEGE, modulo/1,blocksize/1024Hash type = 0Create file QUERY.PRIVILEGE, modulo/101,blocksize/1024Hash type = 0Added "@ID", the default record for UniData to DICT QUERY.PRIVILEGE.

Make the QUERY.PRIVILEGE file a static hashed file.3. Set Permissions on QUERY.PRIVILEGE

The QUERY.PRIVILEGE file and its dictionary should be read-only to all users except Administrator. Check the permissions and change them, if necessary.

4. Edit the DictionaryUse UniEntry, AE, or ED to edit D_QUERY.PRIVILEGE. The dictionary must look like the following example:

@ID............ TYP LOC.......... CONV NAME........... FORMAT SM ASSOC..... @ID D 0 QUERY.PRIVILEGE 50L SPRIV D 1 PRIVILEGES 5R MFULLPATH V FIELD(@ID,'*' File Path 25T S ,2)USERNAME V FIELD(@ID,'*' User Name 25T S ,1)

You can customize the format for the dictionary items to specify lengths for the attributes that match your system.

5. Add Records to QUERY.PRIVILEGEFor this step, you may prefer to have users logged out of UniData. As you add records to the QUERY.PRIVILEGE file, users logging on to UniData access whatever records are present at the time they log on, which may cause unexpected results.Use AE, UniEntry, or ED to populate the QUERY.PRIVILEGE file.


11Chapter

Managing UniData Files

UniData Hashed Files . . . . . . . . . . . . . . . . . 11-4Static Hashed Files . . . . . . . . . . . . . . . . . . 11-5Dynamic Hashed Files . . . . . . . . . . . . . . . . . 11-6 Dynamic Files and Overflow . . . . . . . . . . . . . 11-6 When Dynamic Files Are Created . . . . . . . . . . . . 11-9 Tips and Constraints for Creating a Dynamic File . . . . . . . 11-10 Dynamic Files and Disk Space . . . . . . . . . . . . . 11-12Sequentially Hashed Files . . . . . . . . . . . . . . . . 11-18 The over001 File . . . . . . . . . . . . . . . . . 11-18 The gmekey File . . . . . . . . . . . . . . . . . 11-19DIR-Type Files . . . . . . . . . . . . . . . . . . . 11-21Multilevel Directory Files . . . . . . . . . . . . . . . . 11-24Index Files and Index Log Files . . . . . . . . . . . . . . 11-26 Index-Related Files for a Static Hashed File . . . . . . . . . 11-27 Index-Related Files for a Dynamic Hashed File . . . . . . . . 11-28File-Handling Commands . . . . . . . . . . . . . . . . 11-29File Corruption . . . . . . . . . . . . . . . . . . . 11-32 What Causes File Corruption? . . . . . . . . . . . . . 11-32 Preventing File Corruption . . . . . . . . . . . . . . 11-33UniData Detection Tools . . . . . . . . . . . . . . . . 11-34 guide . . . . . . . . . . . . . . . . . . . . . 11-34 guide_ndx . . . . . . . . . . . . . . . . . . . 11-39 verify2 . . . . . . . . . . . . . . . . . . . . 11-42UniData Recovery Tools . . . . . . . . . . . . . . . . 11-45 dumpgroup . . . . . . . . . . . . . . . . . . . 11-45 fixgroup . . . . . . . . . . . . . . . . . . . . 11-47 fixfile . . . . . . . . . . . . . . . . . . . . . 11-48

11 -2 A

Detection and Repair Examples . . . . . . . . . . . . . . 11-53How to Use guide . . . . . . . . . . . . . . . . . . 11-57Error Messages . . . . . . . . . . . . . . . . . . . 11-60 File Access Messages . . . . . . . . . . . . . . . . 11-60 Block Usage Messages . . . . . . . . . . . . . . . 11-60 Group Header Messages . . . . . . . . . . . . . . . 11-61 Header Key Messages . . . . . . . . . . . . . . . . 11-61 Other Header Messages . . . . . . . . . . . . . . . 11-61 Free Block Messages . . . . . . . . . . . . . . . . 11-62 Long Record Messages . . . . . . . . . . . . . . . 11-63 Dynamic File Messages . . . . . . . . . . . . . . . 11-64

dministering UniData on Windows Platforms

UniData stores your data in hashed files of several different types. UniData also supplies other types of files to support your database, including index files, program files, and directory files.

This chapter describes the types of UniData hashed files and explains the commands you can use to manage them.


UniData Hashed FilesHashed files are binary files that cannot be viewed at the operating system level or read by text editors external to UniData. Each UniData hashed file consists of a file header and one or more groups of data. Each data group contains the following structure:

A fixed-length group headerA pointer arrayRecord IDsData

A record key is assigned to a group in the file according to a hashing algorithm. Then the precise location of the data is stored in the header of that group. The goal of hashing is to make searching for data more efficient by eliminating the need to search an entire file for a record. In a hashed file, UniData searches only the group where the primary key of the record was assigned. UniData supports two proprietary hashing algorithms (hash type 0 and hash type 1). The hash type determines the data group that contains each record.

The most efficient hashing algorithm for a file is the one that provides the best distri-bution of keys across the groups in the file. If the distribution is uneven, heavily loaded groups are accessed more frequently, which results in inefficient disk space use and increased contention for those groups. The default hash type for both static and dynamic files is 0. You can specify hash type 1 when you create a file, and you can switch between hash types with the memresize command.

UniData Hashed Files 11-4

Static Hashed FilesUniData creates static hashed files with a specified block size multiplier and a specified modulo (number of data groups). UniData stores the block size and modulo in the header of the file.

Groups in static hashed files can overflow in two ways, as shown in the following table.

Note: When a group in a static file overflows, UniData links the overflow blocks to that specific group. If overflow blocks are freed (by deleting records, for example) they remain linked to the original group and are not available to handle overflow from any other group in the data file. The space used by the blocks is not returned to the operating system. Level 1 overflow eventually impacts the performance of a static hashed file. Level 2 overflow impacts performance earlier and more severely, so correct sizing to prevent level 2 overflow is critical.

Overflow Type Description

Level 1 overflow The amount of space required for the data in the group is larger than the amount of space available. This happens if the length of a data record is too long for the block size, or if the number of records in the group grows so large that not all of the data fits. UniData appends overflow blocks to the original file, and stores the data portions of records in overflow. The pointers and keys remain in the primary data file; accessing a record can require two reads, one to determine the address and the second to read the data in overflow.

Level 2 overflow The amount of space required for pointers and keys is larger than the total size of the group. This happens if too many records are hashed to the group. UniData creates overflow blocks which contain both data and keys. Record access can require multiple reads to determine the location and find the data.

Level 1 and Level 2 Overflow


Dynamic Hashed FilesDynamic hashed files automatically increase modulo (number of groups) to minimize level 2 overflow. When you view the structure of dynamic files at the operating system level, the structure is different from that of static files. A dynamic file is actually an NTFS directory containing at least two binary files:

One or more data files named dat00x. These are hashed files. dat001 is the primary data file. Each group in a dat file contains a group header, keys, pointers, and data.One or more overflow files named over00x. Blocks in these files hold data when a group in a data file is in level 1 overflow.

The following example shows the structure of the ORDERS file in the UniData demo database:

C:\Unidata71\demo>DIR ORDERSVolume in drive C has no label.Volume Serial Number is E476-B561

Directory of C:\UniData71\demo\ORDERS

10/27/98 11:14a <DIR> .10/27/98 11:14a <DIR> ..10/08/98 03:02p 24,576 dat00110/08/98 03:02p 9,216 over0014 File(s) 33,792 bytes 2,842,187,776 bytes free

Notice that the dictionary file (D_ORDERS) is not a directory.

Dynamic Files and OverflowDynamic files automatically change size (both physical size and modulo) as data is added to them. You create a dynamic file with a specified initial modulo, which is the minimum modulo of the file. As records are added, UniData adds groups to the data file (dat001) to prevent level 2 overflow and adds blocks to the overflow file (over001) to contain level 1 overflow.

Dynamic Hashed Files 11-6

If you specify the OVERFLOW option with the CREATE.FILE command, UniData creates a dynamic file with an overflow file for each dat file. For example, over001 corresponds to dat001, over002 corresponds to dat002, and so forth. When the file is cleared, UniData maintains this overflow structure. For more information about the CREATE.FILE command, see the UniData Commands Reference.

Splitting and Merging

When a group in the primary data file reaches level 1 overflow, UniData stores the overflowed data in blocks in the overflow file. Blocks in over001 are linked (internal to UniData) to groups in the primary data file dat001. When the overflow file runs out of blocks, UniData adds blocks to it. To prevent level 2 overflow, UniData splits groups (increasing the modulo of the primary file) whenever the load factor of an existing group reaches a level called the splitting threshold (or SPLIT.LOAD). The splitting process is transparent to the user. When a group splits, UniData adds the additional group to the primary data file, increasing its modulo and physical size.

As records are removed from a dynamic file, groups that had been split can merge back together if all the following conditions are true:

The current modulo of the file is greater than the minimum modulo of the file.The combined load factor of the two groups is less than a value called merging threshold (or MERGE.LOAD).One of the two groups is the last group in the file.

UniData provides two different split/merge types for dynamic files, KEYONLY and KEYDATA. You can set the split/merge type when you create a dynamic file, and you can change an existing split/merge type for a file with the CONFIGURE.FILE command or the memresize command. Use FILE.STAT, ANALYZE.FILE, or GROUP.STAT to display the split/merge type for a file.


KEYONLY Type

The KEYONLY split/merge type is the default for UniData dynamic files. For KEYONLY dynamic files, the load factor of a group is the percentage of the group space that is filled with keys and pointers. By default, the splitting threshold for a group in a KEYONLY dynamic file is 60%, meaning that the group can split into two when the space occupied by keys and pointers reaches 60% of the size of the group. By default, the merging threshold for a KEYONLY dynamic file is 40%, meaning that if the total load in a pair of groups that resulted from a split is under 40% of the size of a single group, the pair are eligible to merge. You can change the splitting threshold for a single KEYONLY file with the CONFIGURE.FILE or memresize commands, and you can change the defaults for all files by changing the SPLIT_LOAD and MERGE_LOAD parameters in the UniData configuration file (\udthome\include\udtconfig).

KEYDATA Type

The KEYDATA split/merge type is also available for UniData dynamic files. For KEYDATA dynamic files, the load factor of a group is the percentage of the group space that is filled with keys, pointers, and data. By default, the splitting threshold for a group in a KEYDATA dynamic file is 95 percent, meaning that the group can split into two when the space occupied by keys, pointers, and data reaches 95 percent of the size of the group. By default the merging threshold for a KEYDATA dynamic file is 40 percent, meaning that if the total load in a pair of groups that resulted from a split is under 40 percent of the size of a single group, the pair are eligible to merge.You can change the splitting threshold for a single KEYDATA file with the CONFIGURE.FILE or memresize commands, and you can change the defaults for all files by changing the KEYDATA_SPLIT_LOAD and KEYDATA_MERGE_LOAD parameters in the UniData configuration file (\udthome\include\udtconfig).

Selecting a Split/Merge TypeUse the KEYONLY split/merge type for files whose records differ widely in length (standard deviation from average is large). When record lengths vary widely, the KEYONLY split/merge type makes more efficient use of disk space. Use the guide or FILE.STAT command to determine the record length and standard deviation from average for an existing file.


Use KEYDATA for files whose record length is consistent and in which the length of the data portion of each record is large with respect to the record ID. For files with these characteristics, the KEYDATA split/merge type provides a better distribution of records and less overflow than KEYONLY.

Dynamic Files and Hash Type

For both static and dynamic files, the default hash type was is 0. This hash type provides a more even distribution of keys in groups in dynamic files. If key distri-bution in a file is uneven, you should consider tuning the modulo, block size, and split/merge type of the file. If none of these methods is effective, you should consider switching the hash type to 1.

When Dynamic Files Are CreatedThe following considerations determine where the parts of a newly created dynamic file are located.

Estimating the Size of the File

The estimated space required for a new dynamic file is the smaller of the following:

MAX_FLENGTHminimum modulo * block size

If (minimum modulo * block size) is larger than MAX_FLENGTH, the new file needs more than one data part file.

Locating the Dynamic File DirectoryThe dynamic file directory is located in the UniData account where CREATE.FILE was executed.


The following example illustrates creating a dynamic file in the current account directory:

:CREATE.FILE DYN_TEST 3,1 DYNAMICCreate file D_TEST.DYN, modulo/1,blocksize/1024Hash type = 0Create dynamic file TEST.DYN, modulo/3,blocksize/1024Hash type = 0Split/Merge type = KEYONLYAdded "@ID", the default record for UniData to DICT TEST.DYN.:!DIR DYN_TEST Volume in drive C has no label. Volume Serial Number is E476-B561

Directory of C:\UniData71\claireg\DYN_TEST

11/09/98 01:47p <DIR> .11/09/98 01:47p <DIR> ..11/09/98 01:47p 4,096 dat00111/09/98 01:47p 1,024 over001 4 File(s) 5,120 bytes 2,842,173,440 bytes free:

In the preceding example, the primary data file (dat001) includes a file header and the three data groups for a total of four 1K blocks. The overflow file (over001) includes a 1K file header. Since MAX_FLENGTH is larger than minimum modulo * block size, the primary data file and overflow file each have only one “part.”

Tips and Constraints for Creating a Dynamic FileThis sections provides information about choosing the optimal modulo and block size for a dynamic file.

Choosing the Initial ModuloIf you are creating a dynamic hashed file, selecting an appropriate starting (minimum) modulo is critical to the future efficiency of the file. You should select a starting modulo based on the expected future size of the file, because subsequent splitting and merging operations are affected by the initial modulo. Starting with a modulo that is very small (for instance, 3) produces inefficient hashing and splitting as the file grows. Starting with a modulo that is very large produces a file that may initially take up more disk space than needed, but that impact is more desirable than the slow performance and inefficiency that results if the starting modulo is too small.


When you create a dynamic file, estimate the initial modulo by using the same procedure for estimating the modulo for a static file.

Choosing the Block Size

If you are creating a KEYDATA dynamic file, make sure the block size is large with respect to the record length. IBM recommends you choose a block size that is at least 10 times the average record length. UniData bases the load factor in a KEYDATA file on the percentage of the space in each block that is occupied by both keys and data. If the block size is not large with respect to record size, the file will occupy a large amount of space, and much of that space will be unused.

If you are creating a KEYONLY dynamic file, make sure the block size is large with respect to the average key length. IBM recommends you choose a block size that is at least ten times the average key length. Load factor in a KEYONLY file is based on the percentage of the space in each block that is occupied by keys and pointers. If the block size is not large with respect to the average key length, and the hashing is not even, certain groups will be split over and over, resulting in an inefficient distribution.

Dynamic Files and Disk SpaceWhen data is removed from blocks in the overflow file, UniData keeps those blocks for the dynamic file. A certain number are reserved for the groups they were part of, and the remainder of the blocks are available for overflow from any group in the file. The UniData configuration parameter GRP_FREE_BLK defines the maximum number of free blocks that should be kept in the free block list for a particular group. If more blocks are freed, they are kept in the free block list at the file level.

Note: See “Appendix A UniData Configuration Parameters,” for a list of the configuration parameters.

If you remove all records from a dynamic file with either the ECL CLEAR.FILE command or the ECL DELETE command with the ALL option, the file returns to its minimum modulo, and the disk space is returned to the operating system. However, if you remove all records from a dynamic file using a select list, the file may not return to its minimum modulo. Depending on the order in which records are removed, some groups resulting from earlier splits may not become eligible for merging, even though they do not contain any records.


The following examples show splitting and merging in a dynamic file. The first example shows creating a dynamic file with a minimum modulo of 3:

:CREATE.FILE SIZE.TEST 3,2 DYNAMICCreate file D_SIZE.TEST, modulo/1,blocksize/1024Hash type = 0Create dynamic file SIZE.TEST, modulo/3,blocksize/2048Hash type = 0Split/Merge type = KEYONLYAdded "@ID", the default record for UniData to DICT SIZE.TEST.:FILE.STAT SIZE.TESTFile name(Dynamic File) = SIZE.TESTNumber of groups in file (modulo) = 3Dynamic hashing, hash type = 0Split/Merge type = KEYONLYBlock size = 2048Number of records = 0Total number of bytes = 0...File has 1 over files, 1 prime files:!DIR SIZE.TEST Volume in drive C has no label. Volume Serial Number is E476-B561

Directory of C:\IBM\ud72\claireg\SIZE.TEST

11/09/98 02:01p <DIR> .11/09/98 02:01p <DIR> ..11/09/98 02:01p 8,192 dat00111/09/98 02:01p 2,048 over001 4 File(s) 10,240 bytes 2,841,095,680 bytes free


Because the file was created with a block size multiplier of two, the size of each block is 2048 bytes. The primary file (dat001) has one block for the file header, and three for the data. The overflow file (over001) is initially allocated one block for its header.Because the split/merge type was not specified, the file was created as a KEYONLY file.


The next example shows what happens when the dynamic file is populated with records:

:COPY FROM DICT VOC TO DICT SIZE.TEST ALL@ID exists in SIZE.TEST, cannot overwrite58 records copied:COPY FROM VOC TO SIZE.TEST ALL489 records copied:!DIR SIZE.TEST\* Volume in drive C has no label. Volume Serial Number is E476-B561


11/09/98 02:01p <DIR> .11/09/98 02:01p <DIR> ..11/09/98 02:05p 24,576 dat00111/09/98 02:05p 12,288 over001 4 File(s) 36,864 bytes

2,841,068,032 bytes free


The FILE.STAT command shows the following output:

:FILE.STAT SIZE.TESTFile name(Dynamic File) = SIZE.TESTNumber of groups in file (modulo) = 12Dynamic hashing, hash type = 0Split/Merge type = KEYONLYBlock size = 2048File has 3 groups in level one overflow.Number of records = 489Total number of bytes = 12590

Average number of records per group = 44.5Standard deviation from average = 13.2Average number of bytes per group = 1144.5Standard deviation from average = 459.4

Average number of bytes in a record = 25.7Average number of bytes in record ID = 7.9Standard deviation from average = 35.5Minimum number of bytes in a record = 6Maximum number of bytes in a record = 379

Minimum number of fields in a record = 1Maximum number of fields in a record = 10Average number of fields per record = 2.2File has 1 over files, 1 prime filesStandard deviation from average = 0.7

File has 1 over files, 1 prime files

:!DIR SIZE.TEST Volume in drive C has no label. Volume Serial Number is E476-B561

Directory of C:\IBM\ud72\claireg\SIZE.TEST11/09/98 02:01p <DIR> .11/09/98 02:01p <DIR> ..11/09/98 02:05p 26,624 dat00111/09/98 02:05p 20,480 over001 4 File(s) 47,104 bytes 2,841,068,032 bytes free


The original three groups have split. Now there are 12 groups in the primary data file, and 10 groups (plus the header group) in the overflow file.


The following example shows the results of deleting all records with a select list:

:SELECT SIZE.TEST

>DELETE SIZE.TESTDo you want to delete records in select list?(Y/N)Y...:FILE.STAT SIZE.TESTFile name(Dynamic File) = SIZE.TESTNumber of groups in file (modulo) = 10Dynamic hashing, hash type = 0Split/Merge type = KEYONLYBlock size = 2048Number of records = 0Total number of bytes = 0... File has 1 over files, 1 prime files...::!DIR SIZE.TEST Volume in drive C has no label. Volume Serial Number is E476-B561

Directory of C:\IBM\ud72\claireg\SIZE.TEST11/09/98 02:01p <DIR> .11/09/98 02:01p <DIR> ..11/09/98 02:05p 26,624 dat00111/09/98 02:05p 20,480 over001 4 File(s) 47,104 bytes 2,841,068,032 bytes free


Merging has reduced the modulo to 10. The file size as measured at the operating system level has not changed from the previous example. Some groups did not merge, and the groups that were added remain allocated to the file.


The final example shows the results of CLEAR.FILE:

:CLEAR.FILE SIZE.TESTSIZE.TEST is cleared.:FILE.STAT SIZE.TESTFile name(Dynamic File) = SIZE.TESTNumber of groups in file (modulo) = 3Dynamic hashing, hash type = 0Split/Merge type = KEYONLYBlock size = 2048Number of records = 0Total number of bytes = 0 Average number of records per group = 0.0Standard deviation from average = 0.0Average number of bytes per group = 0.0Standard deviation from average = 0.0 Average number of bytes in a record = 0.0Minimum number of bytes in a record = 0Maximum number of bytes in a record = 0 Minimum number of fields in a record = 0Maximum number of fields in a record = 0Average number of fields per record = 0.0File has 1 over files, 1 prime files

:!DIR SIZE.TEST Volume in drive C has no label. Volume Serial Number is E476-B561


11/09/98 02:01p <DIR> .11/09/98 02:01p <DIR> ..11/09/98 02:01p 8,192 dat00111/09/98 02:01p 2,048 over001 4 File(s) 10,240 bytes 2,841,095,680 bytes free

The ECL CLEAR.FILE command returns the file to its original modulo and size.


Sequentially Hashed FilesA sequentially hashed file has the same structure as a dynamic file, but UniData stores all records sequentially, based on the primary key. The modulo (number of groups) for a sequentially hashed file is fixed, it does not grow and shrink as records are added or deleted.

You create sequentially hashed files by converting from existing UniData static or dynamic files. You specify a percentage of the file that you want to remain empty to allow for growth. Although the structure for a sequentially hashed file is the same as a dynamic file, the modulo is fixed.

Use sequentially hashed files for files where the majority of access is based on the primary key.

The dat001 FileThe dat001 file is also called the primary data file. As you add records to a sequen-tially hashed file, UniData hashes the keys, based on information in the gmekey file, to groups in dat001. If your data overflows the group (level 1 overflow), UniData writes the overflow data to the over001 file.

The over001 FileAs you add records to a sequentially hashed file, whenever the space reserved for data in a group in the primary file gets too full, UniData writes the excess data into blocks in over001. Registers within UniData track how blocks in over001 are linked to groups in dat001. If over001 gets too large, UniData adds additional blocks to it. If the current file system becomes full, or over001 grows larger than a UniData limit, UniData creates an over002 file.

If the sequentially hashed file has level 2 overflow, the file should be rebuilt using the shfbuild command.


The gmekey FileEach sequentially hashed file contains a static, read-only file called the gmekey file. UniData reads this file into memory when you open a sequentially hashed file. The gmekey file contains information about the type of keys in the file (alpha or numeric), and controls which group a record is hashed to when it is written.

You create a sequentially hashed file by converting an existing dynamic or static file with the shfbuild command:

Syntax:

shfbuild [-a |-k] [-n | -t] [-f] [-e empty percent] [-m modulo] [-b block size multiplier] [-i infile] outfile

The following table describes the shfbuild options.


-a Only rebuild the last group of the sequentially hashed file. UniData splits the last group into groups according to the records in the group. If you use this option, the outfile should be the name of the sequentially hashed file. Do not specify infile.

-k Build the gmekey file only. If you use this option, outfile should be the name of the sequentially hashed file. Do not specify infile. UniData rebuilds the gmekey file according to the keys in each group of outfile.

-n/-t Force the outfile to be in numeric or alphabetic order. By default, the order of outfile is determined by the infile primary key type. If infile is a sequen-tially hashed file, UniData uses the same order in outfile. If infile is not a sequentially hashed file, the order of outfile is determined by the justifi-cation of the @ID of the infile dictionary record. If it is right justified, it is numeric. Otherwise, it is alphabetic. If you use the -a or the -k option, these options have no effect.

-f Force outfile to truncate before being built.

-m Specifies the new modulo of outfile.

-e Empty percent. This is a number between 0 and 99 which indicates how much space in the rebuilt groups to reserve. UniData calculates the new modulo of the file from empty_percent and the number of records in the rebuilt groups. If you do not specify -e or -m, UniData rebuilds the sequen-tially hashed file according to the default empty percent of 20.

shfbuild Parameters

Sequentially Hashed Files 11-18

To convert an existing file, execute the shfbuild command from the system level prompt, as shown in the following example:

% shfbuild -m 59 SEQUENTIAL175 keys found from SEQUENTIAL.175 records appended to SEQUENTIAL; current modulo is 59.

After converting a file to a sequentially hashed file, you must manually enter a file pointer in the VOC file in order to access the sequentially hashed file, as shown in the following example:

:AE VOC SEQUENTIALTop of New "SEQUENTIAL" in "VOC".*--: I001= F002= SEQUENTIAL003= D_SEQUENTIAL*--: FIFiled "SEQUENTIAL" in file "VOC".

-b Specifies the block size of the sequentially hashed file in kilobytes.

-i infile Load the contents from infile instead of outfile. infile can be any type of UniData file.

outfile The name of the output file.


shfbuild Parameters (continued)


DIR-Type FilesA UniData DIR-type file is an NTFS directory that contains NTFS text or data files. Each NTFS text or data file is a UniData record. The BP file, a UniData file that stores UniBasic source files and compiled programs, is a DIR-type file. The following example shows the structure of a sample BP file:

:!DIR BP\* Volume in drive D has no label. Volume Serial Number is 4CD1-467F Directory of D:\UniData\ACCOUNT\BP 11/11/98 10:58a <DIR> .11/11/98 10:58a <DIR> ..11/11/98 10:58a 34 MAINPROG11/11/98 10:58a 58 SUBPROG11/11/98 10:58a 86 _MAINPROG11/11/98 10:58a 168 _SUBPROG 6 File(s) 346 bytes 796,589,568 bytes free:

In the example, MAINPROG and SUBR are UniBasic source files. _MAINPROG and _SUBR are compiled programs.

DIR-Type Files 11-20

Multilevel Files (MULTIFILES)A UniData multilevel (LF type) file is a NTFS directory that contains one or more UniData hashed files. All of the UniData hashed files share a common dictionary. To access a record, you must specify both the directory and the hashed file where the record is located. The following screen shows an example of a multilevel file:

:CT VOC MULTI1VOC: MULTI1:LFMULTI1D_MULTI1:!DIR MULTI1\* Volume in drive D has no label. Volume Serial Number is 4CD1-467F Directory of D:\UniData\ACCOUNT\MULTI1 11/11/98 11:00a <DIR> .11/11/98 11:00a <DIR> ..11/11/98 11:00a 4,096 MULTI111/11/98 11:00a 4,096 MULTI211/11/98 11:00a 4,096 MULTI3 5 File(s) 12,288 bytes:

Note: If the subfile of a multilevel file has the same name as the directory, you can use the directory name only to access the subfile. For instance, LIST MULTI1 is correct syntax if the directory MULTI1 contains subfile MULTI1.

Points to Remember About Multilevel FilesA UniData multilevel file is a NTFS directory that contains UniData hashed files.Each multilevel file may contain a mixture of static and dynamic hashed files.All of the hashed files in a multilevel file share the same dictionary.


UniData supports multilevel files to simplify conversion for legacy applica-tions. The multilevel structure allows a number of data files to share a single dictionary. However, multilevel files are less efficient than ordinary static or dynamic files. The leveled structure means more system resources are needed to read and update these files. For this reason, IBM recommends using ordinary static or dynamic hashed files rather than multilevel files whenever possible. You can share a single dictionary between UniData files by modifying the VOC entries for each file to reference the same dictionary.

DIR-Type Files 11-22

Multilevel Directory FilesA UniData multilevel directory (LD) file is a NTFS directory. The NTFS directory contains one or more NTFS subdirectories (UniData DIR type files). All of the DIR files share the same dictionary. To access a record, you must specify both the multi-level directory file and the DIR file where the record resides. The following example shows some characteristics of a multilevel directory file:

:CT VOC MULTIDVOC: MULTID:LDMULTIDD_MULTID:!DIR MULTID\* Volume in drive D has no label. Volume Serial Number is 4CD1-467F Directory of D:\UniData\ACCOUNT\MULTID 11/11/98 11:01a <DIR> .11/11/98 11:01a <DIR> ..11/11/98 11:01a <DIR> TEST111/11/98 11:01a <DIR> TEST211/11/98 11:01a <DIR> TEST3 5 File(s) 0 bytes 796,556,800 bytes free:

Note: If a subdirectory of a multilevel directory file has the same name as the main directory, you can use the main directory name to access the subdirectory. For instance, LIST MULTID is correct syntax if the directory MULTID contains subdirectory MULTID.

Points to Remember About Multilevel Directory Files

A UniData multilevel directory file is a NTFS directory that contains UniData DIR files (NTFS subdirectories).All of the DIR files in a multilevel file share the same dictionary.Each record in a multilevel directory is a NTFS file.


UniData supports multilevel directory files to simplify conversion for legacy applications. However, multilevel directory files are less efficient than ordinary DIR files. The leveled structure means that more system resources are needed to read and update these files. For this reason, IBM recommends using ordinary DIR files rather than multilevel directory files whenever possible. You can share a single dictionary between UniData DIR files by modifying the VOC entries for each file to reference the same dictionary.

Multilevel Directory Files 11-24

Index Files and Index Log FilesUniData creates an index file whenever you create the first alternate key index on a UniData hashed file. Index information is stored in B+ tree format. UniData index files are NTFS data files.

Note: Regardless how many alternate key indexes users create for a data file, UniData creates a single index file.

The ECL CREATE.INDEX command creates the index file. The ECL BUILD.INDEX command populates the index. DELETE.INDEX (with the ALL option) removes the index file.

By default, each time you update a UniData data file, its associated indexes are updated at the same time. You can turn off automatic indexing on one or more data files (using the ECL DISABLE.INDEX command) to speed performance during periods of heavy activity on your system. If you turn off automatic indexing, UniData stores all index updates in an index log file. The ECL UPDATE.INDEX command applies updates from index logs to indexes in batch mode, and the ECL ENABLE.INDEX command turns automatic updating back on. The ENABLE.INDEX command also creates an index log file if one is not already there. DELETE.INDEX (with the ALL option) removes the index log file.

See the UniData Commands Reference for additional information about index handling commands.


Index-Related Files for a Static Hashed FileFor a static hashed file, UniData creates both the index file and the index log file in the account directory with the data file. The following example shows a sample account where a static file named STATIC.TST has been indexed:

:!DIR/D Volume in drive D has no label. Volume Serial Number is 4CD1-467F Directory of D:\UniData\ACCOUNT [.] D_MENUFILE D__SCREEN_ VOC[..] D_MULTI1 D___V__VIEW X_STATIC_TSTAE_COMS D_MULTID L_STATIC_TST [_HOLD_][AE_SCRATCH] D_SAVEDLISTS MENUFILE [_PH_][CTLG] D_STATIC_TST [MULTID] _SCREEN_D_AE_COMS D_VOC [SAVEDLISTS] __V__VIEWD_AE_SCRATCH D__HOLD_ [SAVEDLISTSL]D_BP D__PH_ STATIC_TSTD_CTLG D__REPORT_ udt_shell4B.tmp 37 File(s) 259,060 bytes 796,475,904 bytes free:

X_STATIC.TST is the index file for the data file STATIC.TST, and L_STATIC.TST is the index log file.

Index-Related Files for a Dynamic Hashed FileFor a dynamic hashed file, UniData creates both the index file and the index log file in the dynamic file directory itself. The following example shows the structure of the ORDERS file in the demo database after an index is created on the file:

:!DIR ORDERS\* Volume in drive D has no label. Volume Serial Number is 4CD1-467F Directory of D:\UniData\demo\ORDERS 11/11/98 11:16a <DIR> .11/11/98 11:16a <DIR> ..11/11/98 11:16a 24,576 dat00111/11/98 11:16a 20,480 idx00111/05/98 10:58a 9,216 over00111/11/98 11:16a 20 xlog001 6 File(s) 54,292 bytes 796,470,784 bytes free:

Index Files and Index Log Files 11-26

Notice that the index and index log files are located in the dynamic file directory rather than in the account. The file idx001 is the index file, and xlog001 is the index log file.

Note: A dynamic hashed file can have more than one idx file. The same configuration parameter (MAX_FLENGTH) that limits the size of a dat or over part file limits the size of index files. When the size of an index file (for instance, idx001) reaches MAX_FLENGTH, UniData creates the next index file (for instance, idx002).


File-Handling CommandsUniData includes a variety of commands for users to create and delete UniData files as well as to obtain status information, change file parameters, and diagnose and repair damaged hashed files.

The following table describes ECL file-handling commands and indicates the UniData file types they affect.

Command Description

CREATE.FILE Creates a UniData file; works for static and dynamic hashed files, dictionary files, DIR files, multilevel files and multilevel directories.

DELETE.FILE Deletes a UniData file; works for static, dynamic, and sequen-tially hashed files, dictionary files, DIR files, multilevel files, and multilevel directories.

CLEAR.FILE Removes all records from a UniData file; works for static, dynamic, and sequentially hashed files, dictionary files, DIR files, multilevel subfiles, and multilevel subdirectories.

CNAME Changes the name of a UniData file; works for static, dynamic, and sequentially hashed files and DIR files. Does not work for multilevel subfiles and multilevel subdirectories or dictionary files.

SETFILE Sets a pointer to a UniData file; works for static, dynamic, and sequentially hashed files, DIR files, multilevel files, and multi-level directories. Does not work for dictionary files or for multilevel subfiles or subdirectories.

RECORD Identifies group where a primary key is hashed, and displays a list of keys hashed to that group. Works for static, dynamic, and sequentially hashed files and for multilevel subfiles. Does not work for dictionaries, directory files, multilevel directories, or multilevel subdirectories.

FILE.STAT Displays statistics about a hashed file, including modulo, block size, hash type, and record statistics. Works for static, dynamic, and sequentially hashed files or static or dynamic multilevel subfiles. Does not work for dictionaries, directory or multilevel directory files, or multilevel subdirectories.

ECL File Commands

File-Handling Commands 11-28

See the UniData Commands Reference for detailed information about the syntax of the file-handling commands.

GROUP.STAT Displays record distribution in a UniData hashed file. Works for static, dynamic, or sequentially hashed files or static or dynamic multilevel subfiles. Does not work for dictionaries, directory or multilevel directory files, or multilevel subdirectories.

RESIZE Changes the modulo, block size, or hash type of a UniData hashed file. Works on static hashed files, static hashed multilevel subfiles, and dynamic files. Does not work on directories, multi-level directories or subdirectories, or dictionaries..

ANALYZE.FILE Displays statistics, including current and minimum modulo, hash type, block size, split/merge type, split load, merge load, and record distribution for a dynamic file. Works on dynamic and sequentially hashed files and dynamic hashed multilevel subfiles only.

CONFIGURE.FILE Changes split/merge type, split load, merge load, part table, or minimum modulo for a dynamic file. Works on dynamic hashed files and dynamic hashed multilevel subfiles only.

REBUILD.FILE Reconstructs a dynamic file using current settings for split load, merge load, and minimum modulo. Used after CONFIGURE.FILE. Works on dynamic hashed files and dynamic hashed multilevel subfiles only.

CHECKOVER Checks UniData hashed files for level 2 overflow. Works on all UniData hashed files and subfiles. Used to check all files in a UniData account directory.

Command Description

ECL File Commands


The next table describes UniData system-level file-handling commands.

Command Description

checkover Checks UniData hashed files for level 2 overflow. Works on all UniData hashed files and subfiles. Checks all files in a UniData account directory. The system-level version can be executed with UniData shut down or with UniData running.

dumpgroup Unloads the contents of a damaged group in a hashed file; can be executed with UniData shut down or with UniData running. Does not work with EDA files.

fixfile Repairs damaged groups in a file; can be executed with UniData shut down or with UniData running. Does not work with EDA files.

fixgroup Repairs a damaged group; can be executed with UniData shut down or with UniData running. Does not work with EDA files.

guide Identifies damaged hashed files or dictionary files. Cannot be executed if UniData is shut down. Does not work with EDA files.

memresize Changes the modulo, block size, or hash type of a UniData hashed file. Works on static or dynamic hashed files and multilevel subfiles. Does not work on sequentially hashed files, directories, multilevel directories or subdirectories, EDA files, or dictionaries. This command uses shared memory and disk storage rather than disk storage alone as working storage. Although it is executed from the system-level prompt, you cannot run it if UniData is shut down. memresize also converts static files to dynamic files, dynamic files to static files, and changes the split/merge type and part table for dynamic files.

shfbuild Converts a static or dynamic file to a sequentially hashed file.

UniData System-Level File Commands

File-Handling Commands 11-30

File CorruptionFile corruption is damage to the structure of a file. UniData file management tools diagnose and repair problems that occur if invalid, unreadable, or inconsistent infor-mation is written to file or group headers. Such invalid information can result in UniData being unable to access part or all of the data in the file. UniData provides a series of utilities that enable you to detect and repair damaged files.

Note: UniData file tools do not detect or repair invalid or inconsistent data in files. Detecting data inconsistencies should take place at the application level.

What Causes File Corruption?File corruption can result from a variety of causes:

Hardware failures, including CPU crashes, media or memory failure, controller failures, bad spots on a disk.Interrupting a write in progress; for example, terminating a UDTelnet Service while users are still logged on to the system.Incomplete writes; for example, a disk runs out of space before a write is complete.

Note: Overflowed files are more likely to become corrupted, since multiple I/O operations can be required to accomplish a single read or write to an overflowed file. An interrupted write can result in a condition where a primary data block and corresponding overflow blocks are out of synch. The increased chance of corruption is particularly significant for files in level 2 overflow.

Preventing File CorruptionYou can reduce the possibility of file corruption by sizing your files to minimize overflow. Level 1 overflow can leave incomplete records in a file, although all the IDs are available. Level 2 overflow can cause more severe data problems because IDs and data can be lost. IBM strongly recommends you monitor and minimize level 2 overflow. Using dynamic files versus static files minimizes level 2 overflow, which provides some protection. However, using dynamic files greatly increases level 1 overflow, making the risk of file corruption greater than that for static files.


Certain UniData commands carry a direct risk of file corruption, as shown in the following table.

There are other operations that can corrupt UniData files; the following list contains some examples:

Stopping the UniData Telnet Service (UDTelnet) or the UniData Terminal Server (UDSerial) while users are logged on to the system.Attempting to view/edit a UniData file with an MS-DOS text, octal, or binary editor can damage the file whether or not UniData is running. In many cases, the file damage is irreversible.Backing up and restoring a UniData file while users are accessing the file during backup may damage the restored file. Any UniData file can be damaged in this way, but the risk is particularly great for dynamic files.

Note: The file being backed up is not damaged. Danger is only to the file being restored.

Command Risk Factor

deleteuser This UniData command first tries to gracefully terminate a process. If unsuccessful, deleteuser forces the process to terminate.

stopud -f This syntax of the stopud command does not allow writes to complete before logging users off.

UniData Commands That Can Corrupt a File

File Corruption 11-32

UniData Detection ToolsUniData supplies the following tool for detecting damaged files:

guide — Use the guide command to detect file damage when UniData is running.

guideSyntax:

guide [file1, file2,...][-options]

Note: You may supply guide with the name of a single UniData file or a series of file names separated by commas or spaces. If you do not specify any files, guide processes all files in the current UniData account directory. However, guide does not work with EDA files.

Description

guide is a Unidata-supplied, system-level utility that provides detailed statistics and suggestions for optimizing file size and ensuring data integrity.

Note: If you do not want the guide utility to report orphan blocks, set the value of the SUPPRESS_ORPHAN_BLOCK_ERROR to a positive integer.


Options

The following table lists the options available for the guide command.

Option Description

-a |-A [filename]-na | -NA (no advice)

Controls whether management advice is included in the output. The default file name for the advice information is GUIDE_ADVICE.LIS. You cannot combine the -a and -o options, because UniData assumes the -a option when the -o (output) option is present. You may use the -na option in combination with the -o option.

-b | -B [filename]-nb | -NB (no brief statistics — this is the default)

Controls whether UniData produces a file containing a brief summary of statistical information. The default file name is GUIDE_BRIEF.LIS.

-d1 | -D1 Includes minimum statistics about the file. Does not work with the -ns option.

-d2 | -D2 Includes statistical information helpful in estimating correct file sizing. This is the default. Does not work with the -ns option.

-d3 | -D3 Includes all information reported with -d2, plus additional information about distribution of data sizes. Does not work with the -ns option.

-e | -E [filename]-ne | -NE (no errors)

Controls whether guide produces a report of structural errors in the selected files. The default error list file name is GUIDE_ERRORS.LIS. UniData assumes the -e option when the -o (output) option is present, and may not be specified at that time. You may, however, use the -ne option in combination with the -o option.

-f | -F [filename] Specifies the file that should receive a list of damaged groups. The default filename, if none is specified, is GUIDE_FIXUP.DAT. UniData creates this file only if it detects errors.

-ha | -HA Evaluates all hash algorithms (default). Note: the -h option has no effect if specified for a dynamic file.

guide Command Options

UniData Detection Tools 11-34

-h0 | -H0 Evaluates algorithm 0. Note: the -h option has no effect if specified for a dynamic file.

-h1 | -H1 Evaluates algorithm 1. Note: the -h option has no effect if specified for a dynamic file.

-i | -I [filename] Directs the guide utility to evaluate all of the files in the file named filename. GUIDE_INPUT.DAT is the default. The file should be composed of one file name per line. UniData treats blank lines and lines that begin with an exclamation point as comments.

-l | -L [count] If you specify the -d3 option, the guide utility displays the keys for the largest records. The key appears in quotes and, if truncated, is followed by an asterisk (*). The -l option controls the number of records that display. The default value is three. Specifying a large number of records results in a significantly slower analysis.

-m | -Mnew_modulo

Directs the utility to evaluate the effects of a different modulo upon the specified file. You must use this option in conjunction with the -h (hash test) option. This option has no effect when specified for a dynamic file.

-o | -O [filename] Controls whether output is combined or directed to separate files. If you specify -o, UniData directs all output to the file specified by filename. If you do not specify a file name, UniData directs the output from guide to “standard out” (usually, your terminal).

-p | -P page_length-np | -NP(no pagination)

Controls the display of guide output when you specify the -o option and direct output to the terminal. Specify -np to scroll the output past with no pause. Specify -p page-length to pause after displaying each page and prompt with the following message: “Press RETURN to continue...” The following responses are accepted at the prompt:• <RETURN> to display the next page.• “N” to continue with no pauses.• “Q” to quit the application.page_length is the number of lines per page in the screen display. The default value is 24.

Option Description

guide Command Options (continued)


guide Output

The guide utility can create five output files. The following table lists these files. You may change the default names.

-r | -R [filename] Specifies whether to produce a reporting file. The filename must be the UNIX file specification of a UniData database file, previously created by the CREATE.FILE command. Use this option to generate file statistics reports using UniQuery. Copy a dictionary for the report file from udthome\sys\D_UDT_GUIDE.

-s | -S count If you specify the -d3 option, the guide utility displays the keys for the smallest records. UniData displays the key in quotes. If the key is truncated, it is followed by an asterisk (*). The “-s count” option controls the number of records to appear in sorted order. The default value is three. Large values result in a significantly slower analysis.

-s | -S [filename] -ns | -NS (no statistics)

Controls whether UniData includes statistical information about the file in the output file. If you do not specify a filename, UniData uses GUIDE_STATS.LIS. (The -s (statistics) option is assumed when the -o (output) option is present, and may not be specified at that time.) You may use the -ne (no errors) option in combination with the -o option.

File Description

GUIDE_ADVICE.LIS Displays management advice about files that are poorly sized or corrupted.

GUIDE_ERRORS.LIS Lists structural errors detected in the files specified.

GUIDE_STATS.LIS Lists statistical information about the files specified.

GUIDE_BRIEF.LIS Displays summary information about selected files, including record counts, total size, used size and modulo.

GUIDE_FIXUP.DAT Contains a list of damaged groups that can be used as input for fixfile. This list can also be used to input file names/group numbers for dumpgroup/fixgroup.

guide Output Files

Option Description

guide Command Options (continued)


If you do not specify options, UniData selects the default options: -a, -e, -f, and -s, and places the results in the default files.

The guide utility checks for existing output files. If there are existing output files, guide appends a timestamp to the end of the existing file before it creates the current output file. The most current output files will not have this time stamp. UniData does not overwrite output files generated in a previous analysis. As a result, you may accumulate a large number of files that you should purge periodically.

guide Report File

You can use the -r option of guide to create a UniData file containing statistical infor-mation about your database. To use the option, complete the following steps:

1. Create a UniData file in the account where you are running guide.2. Copy the records from udthome\sys\D_UDT_GUIDE to the dictionary of

the file you created in step 1. 3. Execute guide -r filename, where filename is the UniData file you created in

step 1.

The guide utility creates statistical information in filename about the evaluated files. The records contain 62 attributes and are keyed by VOC entry name. You can use UniQuery or ECL commands, or write UniBasic code, to analyze the data and produce reports.


guide Example

The following example shows output from guide executed against a directory that contains a damaged file:

# guide -na -ns# pg GUIDE_ERRORS.LIS TEST.FILE File Integrity: Group 1, block 2, record number 0 = "10053" invalid offset 2047 or length 110 Primary group 1, block 2 has 1 offset(s) less than the offset of the group header Group 1, block 2 bytes left 790 is wrong. Group 1, block 1 is pointed to by multiple links Group 1, block 1 has incorrect group number 0 Files processed: 183Errors encountered: 5# pg GUIDE_FIXUP.DATTEST.FILE 1

Notice that group 1 of TEST.FILE is damaged.

Note: guide works only if UniData is running.

guide_ndxSyntax:

guide_ndx{-x | -X} {1 | 2 | 3}, {index_names, ... | ALL} [-t template | -T template] filename

Description

As with other UniData file types, an index file could become corrupt due to hardware failures, the interruption of a write to the index file, or an incomplete write. The guide_ndx utility checks for physical and logical corruption of an index file.

If an index file is corrupt, UniData displays a runtime error when a UniData process tries to access the index. If the index file is associated with a recoverable file, a message is written to the sm.log.


The guide_ndx command creates two files, the GUIDE_XERROR.LIS and the GUIDE_STATS.LIS. GUIDE_ERROR.LIS lists any corruption found in the index file, and GUIDE_STATS.LIS list statistics about the index. If you have a corrupt index, you must rebuild it using the CREATE.INDEX and BUILD.INDEX commands. For more information and creating and building indexes, see Using UniData.

Note: IBM recommends deleting the index with the DELETE.INDEX ALL command. Using the ALL option deletes all alternate key indexes and the index file itself.

Parameters

The following table describes each parameter of the syntax.


-x{1 | 2 | 3} Determines the type of checking guide_ndx performs:1 – Perform physical checking 2 – Perform logical checking 3 – Perform physical and logical checking

index_names The index names you want guide_ndx to check. Separate each index name with a comma, or enter ALL to check all indexes for the file.

-t template The template to use for output files. The default is GUIDE.

filename The name of the data file containing the index.

guide_ndx Parameters


Example

The following example illustrates the contents of the GUIDE_XERROR.LIS file when guide_ndx detects corruption:

% pg GUIDE_XERROR.LIS

INVENTORY Checking index 'INV_DATE' physically... Invalid key length (30569, key item 65) in node 24576. Bytes left not matched (recorded 3157, calulated 4933) in node 24576. Checking index 'FEATURES' physically... Checking index 'COLOR' physically...The next example illustrates the GUIDE_XSTATS.LIS file:% pg GUIDE_XSTATS.LIS

INVENTORY Large index.......... INVENTORY/idx001 Alternate key length. 60 Node/Block size...... 6K OV blocks............ 1 # of indices......... 3 Index auto update.... Enabled, No updates pending

Index Name F-type V-type K-type Nulls Dups F-No/VF-pos (Root) INV_DATE D S N Yes Yes 1 (24576 [1-4]) FEATURES D S T Yes Yes 4 (30720 [1-5]) COLOR D M T Yes Yes 5 (36864 [1-6])

The following table describes the column heading that display in output for the X_STATS.LIS file.

Column Heading Description

Index name Name of the index.

F-type Type of attribute indexed: D for data attribute, V for a virtual attribute.

V-type Value code for the attribute. S for singlevalues, M for multi-valued or multi-subvalued.

K-type Type of index: Txt for text, Num for numeric.

X_STATS.LIS Display


Nulls “Yes” indicates that empty strings are indexed. “No” indicates that empty strings are not indexed.

Dups “Yes” indicates that duplicate keys are allowed in the alternate key index. “No” indicates that duplicate keys are not allowed.

F-No/VF-expr The attribute location for alternate key indexes built on data attributes (D-type) or the virtual attribute definition for alternate key indexes built on virtual attributes (V-type).


X_STATS.LIS Display (continued)


UniData Recovery ToolsUniData includes the following commands to recover corrupted hashed files:

dumpgroup—Use this command to unload complete and valid records from a damaged group, separating valid records from damaged records.fixgroup—Use this command to clear records from a damaged group and to reload and rebuild the group with the valid records unloaded by dumpgroup.fixfile—Use fixfile in conjunction with guide. guide provides a FIXUP.DAT file that lists corrupt files and groups. fixfile uses FIXUP.DAT to unload, clear, and rebuild the damaged groups.

dumpgroupSyntax:

dumpgroup filename group.no [-doutputfile] [-p]

Description

The system-level dumpgroup command unloads readable records from a group you specify in a UniData file. If the file was corrupted, dumpgroup unloads complete, valid records, leaving behind any information it cannot read.

UniData Recovery Tools 11-42

Parameters


If you execute dumpgroup without specifying an output file, the output simply displays on the screen. You will not be able to use that output to verify records or repair the damaged group. If you do specify an output file, UniData places the records in uneditable form, suitable for reloading, into the output file. UniData also creates a directory within your current account for each dumped group. The directory is named FILE_GROUP, where FILE and GROUP are the file name and group number you specify on the command line. This directory contains an ASCII file for each record, so that you can check them for consistency before reloading the damaged file.

Warning: When you use the -d option, make sure you name your output file with a name that does not already exist in your account name. If you specify a duplicate name, the preexisting file may be overwritten.


filename Specifies the name of the file containing groups to be dumped.

group.no Specifies the number of the group to dump. The output from either guide identifies groups that are damaged. Use this information to select groups to process.

[-doutputfile] Specifies the name of a file that contains the readable records from the dumped group, in an uneditable form. If you do not specify the -d parameter with an outputfile, the output prints to screen. To load outputfile back into the file, use fixgroup. Note: No space is allowed between -d and outputfile.

[-p] Converts nonprinting field markers to printable characters in editable output file. This option is only valid if -d is used.

Parameters of dumpgroup Command


fixgroupSyntax:

fixgroup filename group.no [-iinputfile] [-k]

The system level fixgroup command reloads a hashed file group based on a file created by the dumpgroup command.


Warning: If you execute fixgroup without an input file argument, UniData clears the damaged group. Be sure that you have saved the readable records with dumpgroup before clearing the group. If you clear the damaged group and you have not saved the readable records, the data in that group is lost. The syntax for clearing a group without reloading it is:

fixgroup filename group.no

UniData displays a warning message before clearing the group, as shown in the following example

fixgroup INVENTORY 5 will make group 5 empty, do you wish to do it ? [y/n]


filename Specifies the name of the file to repair.

group.no Indicates the identifying number of the damaged group.

[-iinputfile] Specifies the name of the file created by dumpgroup. If you do not specify an input file argument, fixgroup simply clears the specified group, without reloading it. Note: No space is allowed between -i and inputfile.

[-k] Allows fixgroup to reload the damaged records from inputfile without zeroing the group first. This option may be useful if the group was updated since dumpgroup was executed. However, for best results, do not allow access to a file while it is being repaired, and clear the damaged groups rather than using the -k option.

fixgroup Parameters


fixfileSyntax:

fixfile {-t | {-dfilename | -k | -p | -f}} [-mfilename] [-wdirectory] [-ifilename | filename group.no]

The system-level fixfile command repairs damaged groups in UniData files by clearing the group and optionally restoring readable records to the group. Use fixfile in conjunction with the guide utility. Do not let users access files while fixfile is running because you could lose records.


The following table describes each parameter of the fixfile syntax.


{-t} Direct all output to the terminal only. Each readable record is described in a new line that includes the record key and the record length. All attributes in the record appear on separate lines, each line indented by two spaces. Special and nonprintable characters are translated as follows:Attribute Mark — New lineValue Mark — “ } ”Subvalue Mark — “ | ”Text Mark — “ { ”Non-printables — “ . ”The -t and -d parameters are mutually exclusive and cannot be used together.

{-dfilename} A file specification is required. For static files, dumps the readable records to this file in uneditable format. For dynamic files, UniData creates this file, but dumps the actual records to a file in \temp.With the -d option, UniData also writes the records, in readable format, to a directory in your current UniData account. This directory contains an ASCII file for each readable record in the group. The records are in a format suitable for editing. To repair any file, you need both the -d and -f options.

{-k} If you specify the -k option with the -d option, UniData does not clear the damaged groups. This has the effect of dumping the readable records for examination, but leaving the file corrupt. If you specify the -d and -f option along with the -k option, UniData repairs the file and returns the readable records to the group. Any unreadable records that UniData did not dump remain in the file as well.

{-p} If you specify the -p option with the -d option, UniData trans-lates all non-printing characters and characters with special meaning to UniData. This translation applies to the editable ASCII files created by the -d option. If you do not specify the -p option, only attribute marks are translated.

fixfile Command Parameters


How fixfile Works with Static Files

When you run fixfile with the -t option on a static file, UniData displays the readable records from the file and group to the terminal. UniData does not clear or repair the group. You can supply the names of damaged files and groups from the command line or from an input file. The default input file is GUIDE_FIXUP.DAT.

When you run fixfile with -dfilename on a static file, UniData creates:

{-f} If you specify the -f option with the -d option, UniData clears the damaged group and restores the records that were dumped back into the group, creating a fixed file with all readable data restored. You must specify the -d option with the -f option.

[-mfilename] UniData writes all error messages and statistics to the file you specify, instead of the terminal.

[-wdirectory] UniData creates the work files that are generated in the directory you specify.

{-ifilename} UniData uses this file as the source of the names of damaged files and groups to be repaired. If you do not use this option or the {filename group.no} option, UniData uses the GUIDE_FIXUP.DAT file under the current directory. This option is mutually exclusive with {filename group.no}.

{filename group.no} The file name and group number that contains the corruption. If you do not use this option or the {-ifilename} option, UniData uses the GUIDE_FIXUP.DAT file under the current directory. This option is mutually exclusive with the {-ifilename} option.


fixfile Command Parameters (continued)


An NTFS directory or directories for the files and groups being repaired. If only one group in a file is damaged, the directory is named FILE_GROUP, where FILE is the damaged file (from GUIDE_FIXUP.DAT) and GROUP is the damaged group. If several groups in a file are damaged, UniData creates a directory named FILE_dir.

Each FILE_GROUP directory contains an ASCII file for every readable record in the damaged group. Each file name is the key for the corresponding UniData record. These records are in a format suitable for editing. Each FILE_dir contains a subdirectory for each damaged group in FILE. The name of each subdirectory is the group number of the damaged group. Each subdirectory contains an ASCII file for every readable record in the damaged group. Each file name is the key for the corresponding UniData record. These records are in a format suitable for editing.

A file, with the name you specify on the command line, that contains the records fixfile could read, in uneditable format. This file is used to reload the records into the damaged groups after the groups are cleared.

Note: If you specify the -p option, fixfile translates nonprinting characters in the records when it creates the “editable” files. Otherwise, UniData translates only attribute marks to new lines.

When you run fixfile with the -d and -f options on a static file, UniData reloads the records into the damaged groups, taking them from the file you specify on the command line. Unless you specify the -k option, fixfile clears the groups, removing all contents, before reloading the data. If you specify the -k option, UniData adds the records back, but does not clear any data from the group.

Note: It is possible to run fixfile in two steps, one to dump the records for review and the second to repair the file. To dump the records only, run fixfile with the -d option, but without the -f option. Unless you specify the -k option, running fixfile with the -dfilename deletes the readable data from the specified groups when it creates output. To repair the file, run fixfile with both -d and -f options.

How fixfile Works with Dynamic Files

When you execute fixfile with the -d option on a dynamic file, UniData creates the following:


An NTFS directory located in \temp for each file-group combination being repaired. The directories are named FILE_GROUP where FILE is a damaged file (from GUIDE_FIXUP.DAT) and GROUP is a damaged group. If several groups in a file are damaged, UniData creates a directory for each damaged group. Each FILE_GROUP directory contains an ASCII file for every readable record in the damaged group. Each record’s name is the key for the corre-sponding UniData record. These records are in a format suitable for editing. A file containing the records fixfile could read, in uneditable format suitable for reloading into the group after it has been cleared. This file is located in \temp (or in the directory identified by the TMP environment variable) and is named ud_dp_pid, where pid is the process ID of the process that executed fixfile.

Note: If you specify the -p option, fixfile translates nonprinting characters in the records when it creates the editable files. Otherwise, UniData translates only attribute marks to new lines.

When you run fixfile with the -d and -f options on a dynamic file, UniData reads the file you specify with the -d option on the command line and also reads the uneditable file of dumped records. UniData then reloads the records from that file into the damaged groups. Unless you specify the -k option, fixfile clears the groups, removing all contents, before reloading the data. Otherwise, UniData adds the records back, but does not clear any data from the group.

Note: You can run fixfile in two steps, one to dump the records for review and the second to repair the file. To dump the records for review, run fixfile with the -d option, but without the -f option. (You do not need to use -k for dynamic files. For dynamic files, running fixfile with -dfilename and not -f does not delete the readable data from the specified groups when it creates output.) To repair the file, run fixfile with both the -d and -f options. If you specify the same file name with -d in both the review and repair steps, UniData will prompt whether or not to clear the damaged groups.


Detection and Repair ExamplesThe following example shows typical output from running guide against a damaged file:

The output displays statistics and then reports which groups are damaged. In this case, group 1 is damaged.

The next example shows the output from dumping the records from the damaged group with dumpgroup:

Detection and Repair Examples 11-50

At this point you can review the directory CLIENTS_1, containing a file for each record that was dumped from group 1.You should verify that the data in each record is valid. The following example shows the output from rebuilding the damaged group with fixgroup:


The following examples show a damaged CLIENTS file and a damaged TESTFILE being repaired using guide and fixfile. The first screen shows output from guide:

:!TYPE GUIDE_ERRORS.LIS CALLBASIC_DEMO/EXAMPLE1/callbasic_example1.mdp Unable to open file or file is not Unidata data file. CALLBASIC_DEMO/EXAMPLE1/callbasic_example1.ncb Unable to open file or file is not Unidata data file. CLIENTS File Integrity: Group 3, block 23 has invalid offset 24929 TESTFILE File Integrity: Group 1, block 6231 has invalid offset 6381921 Files processed: 49Errors encountered: 4:The next example shows output from fixfile::!FIXFILE -DOUTFILE -F**** Record Key='10037', Record length=126**** Record Key='9983', Record length=98**** Record Key='10018', Record length=94**** Record Key='10094', Record length=105**** Record Key='10075', Record length=103**** Record Key='10056', Record length=111...**** Record Key='SELECT.ONLY', Record length=14 Record key : 10037Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10037a Record key : 9983Corresponding file : D:\UniData\demo\CLIENTS_dir\3\9983a Record key : 10018Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10018a Record key : 10094Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10094a Record key : 10075Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10075a Record key : 10056Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10056a6 records dumped for group 3 of D:\UniData\demo\CLIENTS.

Detection and Repair Examples 11-52

1 block6 records written to group 3 of file D:\UniData\demo\CLIENTS.27 records dumped for group 1 of D:\UniData\demo\TESTFILE.1 block27 records written to group 1 of file D:\UniData\demo\TESTFILE.:


How to Use guide The steps listed below provide guidelines for effectively using the guide utility.

1. Monitor File Integrity with guideYou should execute guide against your database at regular intervals, as well as when you have had a system crash. You can set up shell scripts to run guide at specified intervals on specified lists of files, or you can simply execute the guide command in each UniData account. You can execute guide against static hashed files at any time, and schedule guide to run on dynamic files at a time when the system is idle or only lightly loaded.

Note: The guide utility requires exclusive access to process any dynamic file. There are two considerations: first, if you run guide against such files while the system is under heavy load, guide may be unable to process the majority of your files. Second, if guide is able to gain exclusive access to a file, UniData blocks other access to that file until guide completes.

2. Check Error Output (GUIDE_ERRORS.LIS)Use the following information to determine what action to take, depending on the error output.

No Errors

If there are no errors, proceed to step 5.

Partially Allocated Block Messages

Partially allocated block messages are not false error reports; they indicate an out-of-synch condition in a dynamic file, but they do not mean that the file must be fixed immediately. Users can continue to access the file; this will not cause damage. Complete the repair at a convenient time using the procedure in step 3.

Partially allocated block messages look like:

free block xx partially allocated, xxx bytes remainingBlock xx of primary file not a member of any group

How to Use guide 11-54

Other guide Error Messages

guide produces many messages besides the one discussed above. If you see error messages pertaining only to static files, or if you see other error messages pertaining to dynamic files, proceed to step 3.

3. Repair Damaged FilesComplete the following steps:

1. Back up the damaged file(s)—If time and space permit, IBM strongly recommends you back up (or simply make a copy of) the damaged files before proceeding. In the event of a system failure during the repair process, you will be able to restore from the backup copies and repeat the procedures rather than attempting to recover a partially-completed repair. DO NOT ALLOW USERS TO ACCESS YOUR FILES WHILE YOU ARE BACKING THEM UP!

2. Repair the damaged groups—After guide completes, you can execute either fixfile or dumpgroup/fixgroup to repair the damaged groups. In either case, the process overview is: dump the readable records from a damaged group, clear the group, and then reload all readable records back into the group.Tip: IBM recommends that you not use the -k option with fixfile or with fixgroup. The -k option lets you reload the readable records without clearing the group. However, you may encounter additional errors if you do not clear the group. Use fixfile or fixgroup without -k; this procedure automatically clears the group before reloading the readable records.Be sure no users are accessing your files before repairing damaged groups. The dumpgroup command does not obtain exclusive access, and fixfile/fix-group only lock the file when the records are being written back to a group. Concurrent access to the file could make corruption worse.

3. Verify the repair—Rerun guide after the repair is complete to verify that the errors are fixed. If they are not, or if additional groups are damaged, repeat the previous step.

4. Back Up the Repaired FilesBack up any files you have just completed repairing.


5. Continue ProcessingIf you shut UniData down to repair files, start it again before allowing users to log in.

How to Use guide 11-56

Error MessagesThis section lists error messages users may see and provides information about the meaning of them. These messages are generated by the guide command.

File Access MessagesFile access messages are similar to the following example:

can not obtain an exclusive lock on recoverable file 'filename'error opening 'filename' part filesUnable to lock dynamic file 'filename'

All of these messages indicate that guide did not process the file because it was unable to obtain an exclusive lock on the file.

Note: These messages display only at the terminal. They are not logged in any file.

Block Usage MessagesBlock usage messages are similar to the following example:

Group xx, block xx is pointed at by multiple linksThe xxth block, grpoff=xx is pointed at by multiple linksIn file, 'filename', the xxth group, grpoff=xx, have hit by other links.

These indicate that a block is found to be referenced by more than one link, which should not occur. These messages indicate damage.

The xxth block of file (filename) has no link.the xxth block has no link

A block has been found that is not in the global free chain and is not used by any group. This error can be reported when guide encounters a corrupt block, and is therefore unable to check blocks linked through the corrupted one.


Group Header MessagesGroup header messages are similar to the following example:

Group xx, block xx, invalid flags xx, should be an overflowheader block

Group xx, block xx, invalid flags xx, should be a normal headerblock

These messages indicate damage.

Header Key MessagesHeader key messages are similar to the following example:

Group xx, block xx key area is corrupted, key size xx, number ofkeys xx

Group xx, block xx key area is corrupted, incorrect key size xxGroup xx, block xx key area is corrupted, data position xx, key

size xx number of keys xxGroup xx, block xx key area is corrupted, total key length xx,

key size xx, number of keys xxkeys xx in group header yy errorkeysize=xx,keys=xxBad keyarea: keysize=xx keys=xx datapos =xx

These errors indicate that key area size or number of keys have been corrupted in a group header.

Other Header MessagesThere are a number of other header messages, as shown in the following examples:

Group xx, block xx has incorrect group number

The group number recorded in the block header does not match the group being checked.

Group xx, block xx has invalid offsetnext over (xx) error in group head

Error Messages 11-58

The offset (link to next disk block) is not a multiple of the block size, or, for a dynamic file, the offset does not indicate an overflow file offset.

Group xx, block xx data area is corrupted, incorrect data position xx

wrong datapos=xx

A data position in a group header is damaged.

Group xx, block xx, y number xx = y invalid offset xx or length Group xx, block xx, y number xx = y offset occurs in wrong orderGroup xx, block xx, y number xx = y offset errorPrimary group xx, block xx has xx offset(s) less than the offset

of the group headerthe bad length of the xxth key = xxThe xxth key='yy', keylen=yy, hashed to xx this group =xx,

modulo=xxtotalkeylen=xx,keysize=xx,keys=xx key area corruptedthe xxth key[] offset(yy) has wrong orderThe xxth[] off_lens error,offset=yy,len=xxThis isn’t an overflow group, but there is xx offset:are xx

offsets less than the offset of group header

Each group header has an area that stores offset-record length pairs, which are sorted by offset. Each offset of a record equals the offset of the previous record plus its length. If these conditions are not met, corruption results, and some or all of the previous messages display.

Group xx, block xx bytes used xx and bytes left xx are inconsistent

Group xx, block xx has wrong number of bytes remaininggroup header byteleft (xx) wrong*key[xx] (key) record length xx wrongfile no in xxth key[] offset() not rightbyteleft (xx) in blk(yy) wrongbyteused (xx) + byteleft (xx) in block (yy) error

The counter that records the number of bytes available in a block does not agree with the actual number of bytes in the block.

Group xx, block xx, yy number xx=yy record length error xx&key[xx] (key) record length (xx) wrong

The actual record length does not match the offset-length pair of the record.

Free Block MessagesGroup xx, free block count in group header (y) error, should

be xx


The actual count of free blocks for a group does not match the counter in the group header.

Group xx, free block xx partially allocated, xx bytes remainingGroup xx, free block xx has invalid flags xx

A block is linked to the free block list but not correctly initialized. Blocks linked to the free list should have no bytes used and should be “normal” blocks (not header blocks).

Long Record Messages“Long” records are records which span more than one block. Messages about problems with these are similar to the following example:

Group xx, block xx, y number xx =y invalid flags xxGroup xx, block xx, y number xx =y longrecord, nextoff(zz) errorGroup xx, block xx, y number xx =y longrec: file no in nextoff

(zz) errorGroup xx, block xx, y number xx =y invalid next offset xxGroup xx, block xx, y number xx =y record length errorblockflag for normal block(yy) error (xx)&key[xx] () blockflag (xx) for longrec errorlongrecord, byteleft(xx) errorlong record, last block (yy) flag (xx) error.

In UniData hashed files, a long record always starts from the beginning of a level one overflow block, which is flagged as “STARTLONG.” Each intermediate block is flagged as “MIDLONG,” and the last block is flagged as “ENDLONG.” If the length of a long record does not match header information, or if any flag in its data blocks is incorrect or the pointer in the chain gets broken, guide reports messages like the preceding ones.

Error Messages 11-60

Dynamic File MessagesDynamic file message are similar to the following examples:Overflow file number too largePrimary file number too largeThe part file number stored in a data block is invalid.The next_block(xx) in overflow file header errorThe next_block(xx) in free block (xx) is over filesize.The offset to the next global free block list is wrong.The free block offset xx too large in header blockThe free block offset xx error in header blockBlock(xx) is not a index free blockFree blocks count in header of file error (should be xx)Global free block information has been damaged.level 2 overflow: file no in nextover (xx) erroropfile (xx) in group header(yy) error.

Header information for overflow part files has been damaged.


12Chapter

Managing UniData Locks

The Global Lock Manager . . . . . . . . . . . . . . . . 12-3 How GLM Works . . . . . . . . . . . . . . . . . 12-3Locking in UniBasic . . . . . . . . . . . . . . . . . 12-5 How Locks Work . . . . . . . . . . . . . . . . . 12-5 Locking Commands . . . . . . . . . . . . . . . . 12-6Resource Locks . . . . . . . . . . . . . . . . . . . 12-8Listing Locks . . . . . . . . . . . . . . . . . . . . 12-9 LIST.READU . . . . . . . . . . . . . . . . . . 12-9 LIST.LOCKS . . . . . . . . . . . . . . . . . . 12-11 LIST.QUEUE . . . . . . . . . . . . . . . . . . 12-11 Parameters . . . . . . . . . . . . . . . . . . . 12-12 LIST.QUEUE Display. . . . . . . . . . . . . . . . 12-13Commands for Clearing Locks . . . . . . . . . . . . . . 12-17 SUPERCLEAR.LOCKS Command . . . . . . . . . . . 12-17 SUPERRELEASE Command . . . . . . . . . . . . . 12-18Procedure for Clearing Locks . . . . . . . . . . . . . . . 12-20

This chapter outlines file, record, and system resource locking within UniData, describes tools for listing locks and listing the contents of the wait queue, and describes procedures for releasing locks that remain set when a process exits UniData.


The Global Lock ManagerThe Global Lock Manager (GLM) is an internal software module that is linked into each udt process to manage logical record locks. Prior to UniData 5.0, logical records locks were managed by the lock control process (lcp) daemon.

How GLM WorksGLM manages local lock tables for each udt process and a shared global lock table in shared memory, which can be accessed by multiple udt processes. The lock tables are hashed tables containing linked lists, which contain lock nodes. When a udt process locks a record, UniData writes the file name, record ID, and lock mode to both the local lock table and the global lock table. When a udt process requests a lock, UniData first searches that local lock table for the udt to see if that process is holding the lock, then the global lock table to see if another udt process is holding the lock.

GLM udtconfig Parameters

There are four udtconfig parameters which control the size of the shared lock table and the memory UniData allocates for each memory request.

N_GLM_GLOBAL_BUCKET

This parameter defines the number of hash buckets system-wide, used to hold the lock names in shared memory. This setting directly affects performance. Normally, the default value of this parameter should not be changed. However, if you notice significant degradation in performance, or your application intensively accesses specific files, you should increase this parameter. The value should be the closest prime number to NUSERS * 3.

N_GLM_SELF_BUCKET

This parameter determines the number of hash buckets for the local lock table, and is highly application dependent. If the application requires a large number of locks in one transaction (more than 20), this setting should be increased from the default of 23. The setting should be the closest prime number to the maximum number of locks per transaction.

The Global Lock Manager 12-3

GLM_MEM_ALLOC

This parameter defines the number of lock nodes allocated for each memory request, and is highly application dependent. If your application requires a large number of locks in one transaction, this setting should be increased to the maximum number of locks per transaction * 2.

GLM_MEM_SEGSZ

This parameter specifies the segment size for each shared memory segment required for GLM. The maximum number of segments is 16. Large application environments require a larger size. The default value is 10.

GLM_MEM_SEGSZ must be greater than 4096 and less than SHM_MAX_SIZE. The formula for determining SHM_MAX_SIZE is NUSERS * maximum number of locks per transaction * 512. SHM_MAX_SIZE should be a multiple of 4096.


Locking in UniBasicA series of UniBasic commands enable users to set read-only locks and exclusive locks on UniData files and their contents.

How Locks WorkUniBasic locks are advisory rather than physical, meaning that they inform other users of a file or record that the file or record is in use, rather than explicitly preventing access. You can set exclusive locks or shared (read-only) locks.

Exclusive Locks (U Type)

Exclusive (U) locks are respected by all lock-checking commands except those that write and delete. Exclusive locks are set by “U” commands, for instance READU, MATREADU, and RECORDLOCKU.

Shared Locks (L Type)

Shared, or read-only, locks can be shared by more than one user. These locks are set by “L” commands, for instance READL, MATREADL, RECORDLOCKL. A record locked with an L lock can be accessed for reading by another “L” command, but cannot be accessed by “U” commands.

Writing and DeletingWRITE and DELETE commands execute regardless of lock status. WRITEU, WRITEVU, MATWRITEU, and DELETEU retain locks set by previous commands. To prevent multiple updates to records, all WRITE and DELETE commands should be preceded by a lock-setting command like READU.

Locking in UniBasic 12-5

Locking CommandsThe following table lists UniBasic commands for setting and releasing locks.

Command Description

FILELOCK Locks the data or dictionary portion of a UniData file against access by commands that check locks.

FILEUNLOCK Unlocks a file previously locked with the FILELOCK command.

MATREADL Assigns the values found in successive attributes of a record to corresponding elements of a matrix and sets a read-only lock on the record.

MATREADU Assigns the values found in successive attributes of a record to corresponding elements of a matrix and sets an exclusive lock on the record.

MATWRITE Writes successive elements of a matrix to the corresponding attri-butes of a record and releases locks previously set on the record.

MATWRITEU Writes successive elements of a matrix to the corresponding attri-butes of a record without releasing locks previously set on the record.

READBCKL Retrieves one record from a B+ tree based alternate key index and places a read-only lock on the record. Each subsequent READBCKU retrieves the previous record in the index.

READBCKU Retrieves one record from a B+ tree based alternate key index and places an exclusive lock on the record. Each subsequent READBCKU retrieves the previous record in the index.

READFWDL Retrieves one record from a B+ tree based alternate key index and places a read-only lock on the record. Each subsequent READBCKU retrieves the next record in the index.

READFWDU Retrieves one record from a B+ tree based alternate key index and places an exclusive lock on the record. Each subsequent READBCKU retrieves the next record in the index.

READL Reads a specified record from a file, assigning the record contents to a dynamic array and setting a read-only lock on the record.

READU Reads a specified record from a file, assigning the record contents to a dynamic array and setting an exclusive lock on the record.

UniBasic Commands for Locking Files and Records


READVL Reads a specified attribute of a specified record, assigning the attribute value to a variable and setting a read-only lock on the record.

READVU Reads a specified attribute of a specified record, assigning the attribute value to a variable and setting an exclusive lock on the record.

RECORDLOCKL Sets a read-only lock on a specified record in a specified file.

RECORDLOCKU Sets a read-only lock on a specified record in a specified file.

RELEASE Releases record locks without updating records.

WRITE Writes an expression to a record, releasing locks previously set by READU, READL, READVU, and MATREADU.

WRITEU Writes an expression to a record without releasing any previous locks on the record.

WRITEV Writes an expression to an attribute of a record, releasing previous update locks.

WRITEVU Writes an expression to an attribute of a record without releasing previous locks on the record.

Command Description

UniBasic Commands for Locking Files and Records (continued)

Locking in UniBasic 12-7

Resource LocksIn both UniData and UniBasic, you can reserve a system resource by setting a semaphore lock on it.

Note: Certain device handling commands (T.ATT, T.DET, LINE.ATT, and LINE.DET) set semaphore locks.

The following table lists commands for explicitly reserving system resources from the ECL prompt.

Note: Although the LOCK and UNLOCK commands enable users to set and release semaphore locks, UniData does not necessarily use system-level semaphores to control access to system resources. The output from LIST.LOCKS and ipcstat may not appear to be consistent, but UniData is functioning correctly.

Command Description

UNLOCK Releases system resources reserved by the LOCK command. (UniData does not automatically release these resources when a program terminates.) This command is not needed to release file and record locks.

LOCK (ECL and UniBasic)

Reserves a system resource for exclusive use.

Locking System Resources


Listing LocksUniData offers three commands for listing record and file locks, semaphore locks on system resources, and processes waiting to get locks.

LIST.READUThe ECL LIST.READU command enables any user with access to the ECL prompt to display a list of file and record locks set on the system.

Syntax:

LIST.READU [user_number | ALL | FILENAME filename | USERNAME user_name] [DETAIL]

Parameters



user_number Displays all locks held by the user number you specify.

ALL Displays all currently active locks.

FILENAME filename Displays all active locks associated with the file name you specify. If the file name does not reside in the current account, nothing is displayed.

USERNAME user_name

Displays all active locks associated with the user name you specify.

DETAIL Displays detailed information.

LIST.READU Parameters

Listing Locks 12-9

Examples

The following example illustrates the output from the LIST.READU command when you do not specify any options.

:LIST.READU UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE 3 234 1049668 claireg Console INVENTORY 10060 X 15:40:20 Jun 12

The next example illustrates the output from the LIST.READU command when you specify a user number. The user number can be found in the output from the LIST.QUEUE and LIST.READU commands under the UNBR column.

:LIST.READU 196 UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE 3 196 1049668 claireg Console INVENTORY 10060 X 08:34:39 Jun 13:

The next example illustrates output from the LIST.READU command when you specify a user name.

:LIST.READU USERNAME claireg UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE 2 220 1049668 claireg Console VOC LIST X 08:10:47 Jun 13 3 196 1049668 claireg Console INVENTORY 10060 X 08:39:40 Jun 13

The final example illustrates output from the LIST.READU command when you specify a file name.

:LIST.READU FILENAME INVENTORY UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE 3 196 1049668 claireg Console INVENTORY 10060 X 08:39:40 Jun 13

LIST.READU DisplayThe following table describes the output from the LIST.READU command.


UNO A sequential number UniData assigns to the udt process that set the lock.

UNBR The process ID of the user who set the lock.

UID The user ID of the user who set the lock.

UNAME The login name of the user who set the lock.

TTY The terminal device of the user who set the lock.

LIST.READU Display


LIST.LOCKSUse the ECL LIST.LOCKS command to display semaphore-type locks that reserve system resources for exclusive use. These locks can be set individually with the LOCK command. They are also set by other ECL commands, including T.ATT.

Syntax:

LIST.LOCKS

The following examples shows the LIST.LOCKS command and its output:

:LIST.LOCKS UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE 1 386 1049668 claireg Console semaphore 1 X 09:11:42 Jun 10:

Note: If you need to clear a semaphore lock that has been left set, you need to note the UNBR and the lock number for the lock. In the example, the lock number is 1 for the lock displayed.

LIST.QUEUEThe ECL LIST.QUEUE command displays a list of all processes waiting to get locks. If a process is waiting for a lock, LIST.QUEUE displays information about the holder of the lock and processes waiting for the lock. Locks are set by each udt process through the general lock manager (GLM) module.

FILENAME The file name in which the record is locked.

RECORD_ID The record ID of the locked record.

M The type of lock. X indicates an exclusive lock. S indicates a shared lock.

TIME Time the lock was set.

DATE Date the lock was set.


LIST.READU Display (continued)

Listing Locks 12-11

Syntax:

LIST.QUEUE [USERNAME user_name | FILENAME filename | user_number][DETAIL]

ParametersThe following table describes each parameter of the syntax.

The following example illustrates the output from the LIST.QUEUE command when you do not specify any parameters.

:LIST.QUEUEFILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6031 2 pts/2 11:05:44 Jun 04--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6130 4 ttyp1 11:05:54 Jun 04INVENTORY 11060 X clair 6188 1 ttyp3 11:06:04 Jun 04

The next example illustrates the LIST.QUEUE output when you specify a user name:

:LIST.QUEUE USERNAME rootFILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6031 2 pts/2 11:35:46 Jun 04

--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X root 6259 5 ttyp2 11:35:56 Jun 04:


USERNAME user_name

Lists all locks the user is waiting for. user_name is the operating system logon name.

FILENAME filename Lists all users waiting for locks for the file name you specify.

user_number Lists all locks for which the user_number is waiting. The user number can be found in the UNBR column of the LIST.READU and LIST.QUEUE output.

DETAIL Displays a detailed listing.

LIST.QUEUE Parameters


The next example illustrates the LIST.QUEUE command output when you specify a file name:

:LIST.QUEUE FILENAME INVENTORYFILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATEINVENTORY 11060 X root 6259 5 ttyp2 11:38:16 Jun 04--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6188 1 ttyp3 11:38:36 Jun 04INVENTORY 11060 X clair 6031 2 pts/2 11:38:46 Jun 04:

The final example shows the output from the LIST.QUEUE command when you specify a user number:

:LIST.QUEUE 6763FILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6758 5 pts/3 14:16:26 Jun 04--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6763 6 ttyp1 14:16:46 Jun 04:

LIST.QUEUE DisplayThe LIST.QUEUE display in the previous examples use the default display. Infor-mation about the owner of the lock is listed above the line. Information about processes waiting for the lock is listed below the line, sorted by the date and time the process requested the lock.

The following table describes the LIST.QUEUE default display for the owner of the lock.


FILENAME The name of the file holding the lock.

RECORD_ID The record ID holding the lock.

M Type of lock held. X is an exclusive lock, S is a shared lock.

OWNER The user name of the owner of the lock.

UNBR The process group ID (pid) of the user who set the lock.

UNO The sequential number UniData assigns to the udt process for the owner of the lock.

LIST.QUEUE Owner Display

Listing Locks 12-13

The next table describes the LIST.QUEUE display for the processes waiting for locks.

The following example illustrates the LIST.QUEUE display when you specify the DETAIL option:

:LIST.QUEUE DETAILFILENAME RECORD_ID M INBRH INBR DNBR OWNER UNBR UNO TTY TIME DATEINVENTORY 10060 X 1638400 9878 3832984929 claireg 325 1 Console 09:55:52 Jun 19--------------------------------------------------------------------------------FILENAME RECORD_ID M INBRH INBR DNBR WAITING UNBR UNO TTY TIME DATEINVENTORY 10060 X 1638400 9878 3832984929 claireg 296 2 Console 09:56:02 Jun 19

TTY The Terminal device of the user owning the lock.

TIME The time the lock was set.

DATE The date the lock was set.


FILENAME The name of the file for which a lock is requested.

RECORD_ID The record ID of the record for which a lock is requested.

M The type of lock requested. X is an exclusive lock, S is a shared lock.

WAITING The user name of the process waiting for a lock.

UNBR The process ID (pid) of the user waiting for a lock.

UNO The sequential number UniData assigns to the udt process waiting for a lock.

TTY The terminal device of the user waiting for a lock.

TIME The time the lock was requested.

DATE The date the lock was requested.

LIST.QUEUE Waiting Display


LIST.QUEUE Owner Display (continued)


The following table describes the owner information the LIST.QUEUE command displays when you specify the DETAIL option.

The following table describes the waiting information the LIST.QUEUE command displays then you specify the DETAIL option.


FILENAME The name of the file for which a lock is held.

RECORD_ID The record ID of the record for which a lock is held.

M The type of lock held. X is an exclusive lock, S is a shared lock.

INBRH The high integer of the inode of the file holding the lock.

INBR The low integer of the inode of the file holding the lock.

DNBR Used in conjunction with the INBR to define the file holding the lock at the operating system level.

OWNER The user name of the process holding the lock.

UNBR The process ID (pid) of the user holding a lock.

UNO The sequential number UniData assigns to the udt process holding a lock.

TTY The terminal device of the user holding a lock.

TIME The time the lock was set.

DATE The date the lock was set.

LIST.QUEUE Detail Display


FILENAME The name of the file for which a lock is requested.

RECORD_ID The record ID of the record for which a lock is requested.

M The type of lock held. X is an exclusive lock, S is a shared lock.

INBRH The high integer of the inode of the file holding the lock.

INBR The inode of the file for which a lock is requested.

LIST.QUEUE Detail Display

Listing Locks 12-15

DNBR Used in conjunction with the INBR to define the file for which a lock is requested at the operating system level.

WAITING The user name of the process requesting a lock.

UNBR The process ID (pid) of the user requesting a lock.

UNO The sequential number UniData assigns to the udt process requesting a lock.

TTY The terminal device of the user requesting a lock.

TIME The time the lock was requested.

DATE The date the lock was requested.


LIST.QUEUE Detail Display (continued)


Commands for Clearing LocksIf you break out of a process that is running, if a process is killed, or if a system resource is not unlocked by a UniBasic program, locks can remain after they should have been released. If a lock remains set, other users experience difficulty accessing a record, file, or resource. As other processes attempt to access the locked item, message queue congestion can result if the process that set the lock is no longer logged on. The typical manifestations of unneeded locks are:

Users cannot perform expected operations on a file or record. Over a lengthy period of time, users receive messages indicating that the file or record is locked.Performance suffers, either because the item that is locked is heavily used or because a message queue has become clogged due to the lock.Batch jobs attempting to access a locked item fail.

Specific symptoms depend on the type of lock and the frequency of usage of the locked item.

UniData includes two commands that enable an administrator with root access to release locks held by other users.

SUPERCLEAR.LOCKS CommandSUPERCLEAR.LOCKS enables you to release semaphore locks on system resources (such as tape drives).

Syntax:

SUPERCLEAR.LOCKS usrnbr [locknum]



usrnbr The process ID (pid) that holds the lock. This number is UNBR in the LIST.LOCKS display.

[locknum] The number of the locked system resource. If you do not specify locknum, the command clears all locks set by usrnbr.

SUPERCLEAR.LOCKS Parameters

Commands for Clearing Locks 12-17

The following example shows the effects of SUPERCLEAR.LOCKS:

:LIST.LOCKS UNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE 1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01 Jun 03 3 15692 1172ump01 tyv4 semaphor -1 0 66 X 16:27:01 Jun 03::SUPERCLEAR.LOCKS 15692 -1:LIST.LOCKS UNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE 1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01 Jun 03:

SUPERRELEASE CommandThe SUPERRELEASE command enables you to release locks you have set on records.

Syntax:

SUPERRELEASE usrnbr [inbr devnum] [record.id]


Note: If you execute SUPERRELEASE and specify only usrnbr, you release all record locks held by the process ID corresponding to usrnbr.

The following example shows the effect of SUPERRELEASE:

:LIST.READU UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE 1 376 1049668 claireg Console INVENTORY 10060 X 09:56:06 Jun 10 2 394 1049668 claireg Console INVENTORY 1006 X 09:56:56 Jun 10:SUPERRELEASE 376:LIST.READULIST.READU UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE 2 394 1049668 claireg Console INVENTORY 1006 X 09:56:56 Jun 10


usrnbr The process ID that holds the lock. This number is UNBR in the LIST.READU display.

[inbr devnum] The inode number and device number for the file that has the lock set. These numbers are INBRH, INBR and DNBR in the LIST.READU display.

[record.id] The identifier for the record to clear. This number is RECORD ID in the LIST.READU display.

SUPERRELEASE Parameters


Procedure for Clearing LocksComplete the following steps to identify and clear unneeded locks.

1. Check for Unneeded LocksUse the UniData LIST.READU and LIST.LOCKS commands to display the locks currently set on the system. Use LIST.QUEUE to identify locks for which processes are waiting. Note locks that meet the following criteria:

They are set on files or records that users cannot currently access.They have been set for a long period of time (shown by the time and date on the list).They were set by users who are not currently on the system.

2. Note Information for ClearingFor record locks, note UNBR, INBRH, INBR, DNBR, RECORD NO. For semaphore locks, note UNBR and lock number. To clear record locks, proceed to step 3. To clear semaphore locks, proceed to step 4.

3. Release Record LocksLog on as an Administrator and use the UniData SUPERRELEASE command to clear record locks. If possible, specify only a UNBR to clear all the locks belonging to a process ID. If you have semaphore locks to clear, proceed to step 4. Otherwise, proceed to step 5.

Warning: Some situations that retain locks can also cause file corruption (for example, a udt process is inadvertently killed). Consider checking the file with guide to make certain it has not been corrupted.

4. Clear Semaphore LocksLog on as an Administrator and clear semaphore locks with the SUPERCLEAR.LOCKS command.

Procedure for Clearing Locks 12-19

13Chapter

Managing UniData Users

Adding Users . . . . . . . . . . . . . . . . . . . . 13-3 User Groups . . . . . . . . . . . . . . . . . . . 13-3 Home Directories . . . . . . . . . . . . . . . . . 13-4 Logon Scripts . . . . . . . . . . . . . . . . . . 13-5Monitoring User Processes . . . . . . . . . . . . . . . 13-7 UniData Commands . . . . . . . . . . . . . . . . 13-7Stopping User Processes . . . . . . . . . . . . . . . . 13-9 Using TIMEOUT . . . . . . . . . . . . . . . . . 13-9

This chapter outlines considerations for adding UniData users to your Windows system, and describes how to use UniData commands to view user processes for troubleshooting, to remove user processes when needed, and to start and stop UniData.

13-2

Adding UsersTo access UniData on your system, each user needs a valid Windows account, including an MS-DOS logon ID and password. In Pick® systems, where each logon account must be a Pick® account, shared logon IDs and passwords are common. In contrast, UniData allows multiple relationships between user logon IDs and UniData accounts. A user may have access to more than one UniData account, and many users can access a single UniData account using separate logon IDs. Therefore, IBM strongly recommends you set up a separate Windows account for each user. IBM recommends separate logon IDs for the following reasons:

It is easier to identify processes and locks belonging to an individual user, which facilitates troubleshooting.Using separate logon IDs allows you to define your users’ responsibilities for protecting their passwords and your data.

User GroupsWhen you add a user account to your Windows system, you can assign the user to one or more user groups. In contrast to UNIX, Windows platforms allows a user to belong to many groups simultaneously, and allows access to objects based on all groups to which the user is assigned.

When you install UniData on your Windows system, the installation procedure sets permissions on the UniData directory structure. UniData grants permissions to three categories of users, Administrators, members of the UniData group, and all other users. After you install UniData, you must assign your UniData users to the UniData group.

Note: Use User Accounts to create user accounts. Use Computer Management add users to groups, and assign User Rights. From the Start menu, click Control Panel then double-click User Accounts. Refer to your Windows documentation for further information.


Home DirectoriesOn Windows platforms, you can define a home directory for each logon ID. This directory is the user’s working directory when they log on. You are not required to define a home directory. If you wish, you can define the same home directory for a group of users, or create a separate one for each user. The home directory does not need to be a UniData account.

To define a home directory for a user, from the Start menu, double-click Adminis-trative Tools, and then double-click Computer Management. Double-click Users, double-click the user for which you are defining a home directory, and then click the Profile tab. The following dialog box appears:

Adding Users 13-4

Enter the path to the user’s home directory in the Local Path box in the Home folder section, then click OK.

Logon ScriptsYou can create a logon script that is executed whenever a user logs on to a Windows console or Telnet session. You must create the script in the directory identified by your Windows platform logon script path. If you specify the script in the User Environment Profile window, UniData executes the script whenever the user logs on.


To specify a logon script for a user, from the Start menu, double-click Adminis-trative Tools, and then double-click Computer Management. Double-click Users, double-click the user for which you are defining a home directory, and then click the Profile tab. The following dialog box appears:

Enter the path to the user’s login script, enter the path where the logon script resides in the User Profile Path box, the script name in the Logon Script box, and then click OK.

Adding Users 13-6

Monitoring User ProcessesFor troubleshooting purposes, it is often necessary to identify and monitor processes owned by a particular UniData user.

UniData CommandsUniData includes a group of commands to display a list of current UniData sessions, to display a list of users currently logged on to the system, and to display detailed information about process activity for a specific user, or for all users. These UniData commands are summarized in the following table.

Note: You do not need to log on as an Administrator to execute these commands.

UniData Command Description

WHO ECL command; displays a list of users currently logged on to the system, including users who are not UniData users.

LISTUSER ECL command; displays a list of current UniData sessions.

listuser UniData system-level command; enter at a MS-DOS prompt; displays the same information as the ECL LISTUSER command.

MYSELF ECL command; displays login ID for the current UniData session.

UniData Commands for Monitoring User Processes


The following example shows the system response to the WHO, LISTUSER, and listuser commands.

:WHOclaireg Console 09:55:40 Feb 01 2005claireg Console 09:56:18 Feb 01 2005

:LISTUSER:LISTUSER

Licensed(reg+pooled)/Effective Udt Sql iPhtm Pooled Total

( 32+10 )/42 2 0 0 0 2

UDTNO USRNBR UID USRNAME USRTYPE TTY IP-ADDRESS TIME DATE 1 3608 0 cgustafs udt pts/1 Console 13:39:43 Feb 01 2005

2 2208 0 cgustafs udt pts/2 Console 15:19:49 Feb 01 2005

C:\UniData71\claireg>listuser:LISTUSER

Licensed(reg+pooled)/Effective Udt Sql iPhtm Pooled Total

( 32+10 )/42 2 0 0 0 2


2 2208 0 cgustafs udt pts/2 Console 15:19:49 Feb 01 2005

Notice that the output of the WHO command includes the user name but not the process ID. Also, output from the LISTUSER command includes a series of identifi-cations: UDTNO (UniData user number), USRNBR (the pid), UID (the user’s uid number), and USRNAME. Displaying further information about a UniData process typically requires the pid (USRNBR).

Monitoring User Processes 13-8

Stopping User ProcessesUniData includes commands that enable you to stop a user’s udt process if the process is hung, or if you need to stop UniData while a user is still logged on. These commands are summarized in the following table.

You can log yourself out using the stopudt command, but you must log on as an Administrator to log out other users using stopudt. You must log on as an Adminis-trator to execute deleteuser.

Warning: Both of these commands can disrupt the consistency of your database, and deleteuser can also corrupt data. Do not use these commands should as a substitute for normal user logout.

Using TIMEOUTYou can execute the ECL TIMEOUT command at the ECL prompt, in a LOGIN paragraph, or in a UniBasic program. TIMEOUT forces the current udt process to log out after a specified number of seconds. If you include TIMEOUT in the LOGIN paragraphs for your UniData accounts, you can provide some improved security for terminals left idle.

Note: Be careful with TIMEOUT. Because this command can cause a UniBasic program to terminate at an INPUT statement rather than concluding normally, using TIMEOUT can cause inconsistent data in your database.

UniData Command Description

stopudt Logs a user out of UniData; UniData allows a current write to complete, but subsequent operations for that udt do not take place.

deleteuser First attempts to gracefully exit and allow a write in progress to complete. If the command is not successful in five seconds, force logs out a user, which may interrupt a write in progress, potentially causing file corruption.

UniData Commands for Removing User Processes


14Chapter

Managing Printers in UniData

Configuring and Troubleshooting a Printer . . . . . . . . . . 14-3 Physical Configuration . . . . . . . . . . . . . . . 14-3 Troubleshooting . . . . . . . . . . . . . . . . . 14-3 Definition in UniData . . . . . . . . . . . . . . . . 14-7 Default Printers . . . . . . . . . . . . . . . . . . 14-8Spooling From UniData . . . . . . . . . . . . . . . . 14-9 The Spooling Process . . . . . . . . . . . . . . . . 14-9 UniData for Windows Platforms Specifics . . . . . . . . . 14-9 Creating a Local Printer . . . . . . . . . . . . . . . 14-10Creating a Form . . . . . . . . . . . . . . . . . . . 14-20Defining a Printer Unit in UniData . . . . . . . . . . . . . 14-24 Examples . . . . . . . . . . . . . . . . . . . . 14-29 Printing to the _HOLD_ File. . . . . . . . . . . . . . 14-33 Selecting a Spooler Mode . . . . . . . . . . . . . . 14-34 Redefining the Default UniData Print Unit . . . . . . . . . 14-37 Submitting Concurrent Print Jobs . . . . . . . . . . . . 14-37UniData Printing Commands . . . . . . . . . . . . . . . 14-38

This chapter explains how UniData interacts with the Windows spooler and describes how to configure and access printers from within UniData.


Configuring and Troubleshooting a PrinterOn Windows platforms, the term “printer” refers to a printer driver. The term “print device” refers to a piece of hardware that can be accessed using one or more “printers.” In order for any user to print to a print device from UniData, all the following conditions must be true. Use these conditions as guidelines for setting up a print device and for troubleshooting print device problems.

Physical ConfigurationConfigure a print device as follows:

The print device must be physically connected to your computer or network. If you are accessing the print device from a local printer you create, the driver for the print device must be installed on the workstation or server from which you are printing.

Note: Depending on your network configuration, you may need to complete additional steps before you can print successfully from your Windows platform. For instance, you may need to install additional network software and then create a “printer” or “local printer” that identifies the device using a network address. Refer to your Microsoft documentation, the documentation for your network hardware and software, and your printer documentation for information about connecting and troubleshooting a print device.

TroubleshootingCheck cables and connections.Check power to print device and check print device for error conditions.Print a file to the print device. If you cannot print to the device from outside UniData, you will not be able to print to it from within UniData. Missing printer drivers or restrictive permissions to a device can result in print jobs failing.

Configuring and Troubleshooting a Printer 14-3

Definition in Windows Platforms

You may either print directly to a network print device or a print to a “local printer” from within UniData.

Network Print Device

A network print device is a print device that is connected to a remote print server. When you print to a network printer, the printer driver and the configuration are downloaded to your computer. To connect to a network printer, from the Start menu click Printers and Faxes, click Printers, and then double-click Add Printers. The Add Printer wizard displays, as shown in the following example:


Click Next. The following dialog box appears:


Click Network printer, and then click Next to display the Specify a Printer dialog box, as shown in the following example:


If you know the name of the printer, enter the path in the Name box. If you are connecting to a printer on the internet or on your intranet, enter the URL of the printer in the URL box. If you do not know the name of printer, click Browse, then click Next. The Browse for Printer dialog box appears, as shown in the following example:

Click Next to locate your network printer.

Local PrinterA local printer is a driver you can create that identifies a print device. When you define a local printer, your workstation becomes the print server for that printer. A local printer may point to a network print device, but you define the printer configu-ration on your workstation.

Definition in UniDataWithin a UniData session, the following commands and statements can access a printer:

UniBasic PRINT statements (following PRINTER ON statements)


UniQuery statements with the LPTR optionSPOOL commandsThe SP.EDIT command

To write to a particular printer from a UniData session, you need to link the printer to an internal print unit in UniData. Use the ECL SETPTR command with the DEST or AT option for this. For more information, see “Defining a Printer Unit in UniData” on page 14-24.

Default PrintersIf you do not map a print unit to a particular printer or queue, UniData checks for a default destination for output of printing commands as follows:

The printer or queue defined by the last previous SETPTR command in your current UniData session. If there was no prior SETPTR command, the printer identified by the system environment variable UDT_DEFAULT_PRINTER. Each UniData session checks for that variable at when users log on to the system. If the variable was set, the defined printer is treated as the default printer throughout the session.If there was no prior SETPTR command, and UDT_DEFAULT_PRINTER was not set, UniData checks for the default printer on your Windows system.

Note: If you are a local user (your account information is on a local Windows machine rather than a domain) and you log on through Telnet, and UDT_DEFAULT_PRINTER was not set, you will see an error message when you attempt to display the default printer name with SETPTR 0.


Spooling From UniData

The Spooling ProcessPrint requests from within UniData are generated by UniBasic commands (PRINT, PRINT ON), by ECL commands (SPOOL, SP.EDIT) and by using the LPTR keyword in UniQuery. When a print request is generated, the following actions happen:

UniData uses information from the print request to create a temporary file containing the output to be printed.

Note: If you executed SETPTR and set the printer mode to 3 or 6, UniData creates the print file in the _HOLD_ file of your current UniData account.

UniData prints that file with Windows Win32 API calls, using information from the printer setup (SETPTR for the printer to receive the output). After the output is printed, UniData deletes the temporary file.

UniData for Windows Platforms SpecificsUniData for Windows Platforms enables you to print to any printer you can access from outside of UniData. The DEST or AT option of SETPTR enables you to print to a particular device. SETPTR options control some output characteristics, and you can specify other characteristics by including spooler options in a quoted string on the SETPTR command line.

By using RAW spooler mode (the default in UniData), you can control formatting by using printer-specific escape sequences rather than spooler options.

Creating a Local PrinterOn Windows platforms, the term “printer” refers to a printer driver. The term “print device” refers to a piece of hardware you can be access by using one or more “printers”. You can create a local printer to print to a device local to your server or workstation. In some circumstances, you may wish to create a local printer that points to a network print device, and print to that local printer rather directly to the network device.

Spooling From UniData 14-9

Complete the following steps to create a local printer.

From the Start menu, point to Printers and Faxes, and then click Add Printer. A window similar to the following appears:


Click Next. The following dialog box appears:

Click Local printer to indicate the printer is a local printer.

Note: Your Windows machine becomes the “server” for the printer you are creating. After you add the printer, click File, then Server Properties to view and edit settings for this printer.


Click Next to display the following dialog box:

If your local printer identifies a device local to your workstation or server, scroll through the list of ports and select the check box the one where the printer is connected. Click Next and proceed to step 5.

If your local printer identifies a network print device, scroll through the list of Available Ports to determine if the UNC identifier for the network print device is listed with “Local Port” as its description. If so, proceed to step 5.

If the network print device is not on the list, or its description is not “Local Port,” click Create a new port. Select Local Port from the Type list, then click Next. The following dialog box appears:


Click OK. A dialog box similiar to the following example appears:

Select the manufacturer and model of your printer. If your printer came with an instal-lation disk, click Have Disk. If the manufacturer or model of your printer is not listed, see your printer documentation for a a compatible printer. Click Next.


Enter a name for the local printer in the Name Your Printer dialog box, as shown in the following example:

Warning: Do not use spaces in the printer name. Although Windows platforms allow spaces in the name (for instance, “LASER PRINTER”), the UniData SETPTR command does not support names that contain spaces. If you use a name containing spaces with the DEST or AT options of SETPTR, the command fails.


You can share your printer with other users on the network. In the following dialog box, enter a name for the shared printer, or select Do not share this printer.

Note: You may share a local printer if you wish. However, sharing a local printer offers no advantage in UniData. UniData only recognizes local printers created on the same Windows system where you are running UniData. Also, UniData does not use the share name to recognize a printer. Rather, UniData uses the printer name you entered previously.


When you click Next after defining Sharing properties, a dialog box similar to the following appears:

Tip: IBM recommends you print a test page to verify the printer setup.


Click Finish. A dialog box similar to the following example appears:

Click Finish to add the printer to your machine. An icon for the printer appears in the Printers window.

Display the Properties sheet for the printer you just created. The following table summarizes the dialog tab.

Dialog Tab Purpose

General Adds comments or location information, or changes printer driver. Within UniData, the first 24 characters of comment entry displays as Description in the output from LISTPTR or SP.STATUS.

Ports References a different network print device.

Scheduling Views or edits times the printer is available, job priority, and job handling.

Printer Properties Sheet


Note: Use caution modifying device settings. You can enter settings for a local printer that are inconsistent with the underlying print device.

Note: You must have Full Control permissions on a printer to assign a default form. Click Security, and then click Permissions on the Property sheet to determine what permissions you have.

To assign a default form to a printer, right-click the printer for which you want to set the default, click Properties, then click Printer Properties. A dialog box similar to the following example appears:

Select the desired form from the Form Type list. If the form you want is not included in the list, see “Creating a Form” on page 14-20. You can also choose copies, orien-tation, and duplex options from this dialog box.

Sharing Shares or unshares your printer.

Security Views or edits permissions, ownership, auditing.

Device Settings Maps forms to trays/feeders.

Dialog Tab Purpose

Printer Properties Sheet (continued)


Note: Options you select on either this tab or the Advanced tab only work if the network print device supports them.

Click OK when your selections are correct.

Note: Although you can select Copy Count from this tab, the value you select here is overridden in UniData by the COPIES option of the SETPTR command.


Creating a FormWindows platforms store information about forms that are available on your current Windows system. Not all the forms are available for all print devices, because each print device supports particular sizes of stock and loading devices. To view the list of forms available on your system, from the Start menu, click Printers and Faxes. Click the File menu, then click Server Properties, then click the Forms tab. A dialog box similar to the following example appears:

Select the Forms tab on the properties sheet, and complete the following steps to create a new form.


1.Select an Existing Form

You create new forms by editing the characteristics of existing forms. Highlight a form, and then select the Create a New Form check box.

Tip: To minimize editing, pick an existing form whose characteristics are similar to the new form you are creating.

Creating a Form 14-21

2. Edit Form Characteristics

When you select the Create a New Form check box, the name, paper size and margins are enabled for editing. Follow the instructions on the properties page to edit and save the new form. The following example shows selections for a form called test_form, based on the existing form called Letter.

Note: Although you can create forms of varying sizes, you cannot select a particular form for use on a particular printer unless the print device can support that size of stock. Refer to your Windows documentation and the documentation for your print device for information about constraints.

The new form now displays in the form list.


Click OK to exit the Forms tab.

Creating a Form 14-23

Defining a Printer Unit in UniDataUse the ECL SETPTR command to define printer units within UniData. This command maps Windows printers to logical unit numbers within a UniData session.

Syntax:

SETPTR unit [width,length,topmargin,bottommargin] [,mode] [,options] [,“spooler_options”]

With SETPTR, you can define up to 31 logical printer units in a single UniData session. Throughout UniData, you can define up to 255, but only 31 can be defined in a single user session.

The following table lists each parameter of the syntax.


unit Logical printer unit number that is internal to UniData. You can map this to a Windows printer with the DEST or AT option. Must range from 0 through 254; default is 0.

[width] The number of characters per line; must be from 0 to 1024; default is 132.

[length] The number of lines per page; must be from 1 to 32,767 lines; default is 60.

[topmargin] The number of lines to leave blank at the top of each page; must be from 0 to 25; default is 3.

[bottommargin] The number of lines to leave blank at the bottom of each page; must be from 0 to 25; default is 3.

[mode] Allows you additional flexibility to direct output; default is 1; see separate table.

[options] Report formatting and printer control options. For more infor-mation, see “SETPTR Options.”

[“spooler_options”] Options that are valid with the Windows spooler. See separate table for list of supported options. Supply these options in a quoted string.

SETPTR Parameters


Note: Users familiar with Pick® conventions should be aware that printer unit numbers set with SETPTR are not the same as Pick® printer numbers. SETPTR allows you to define logical printer units, which may be, but are not necessarily, linked to specific printers. UniData printer unit numbers are used with the PRINT ON statement in UniBasic to allow multiple concurrent jobs. Pick® printers (forms) are specified with the DEST option of SP.ASSIGN.

The next table describes modes for the SETPTR command.

The next table describes options for the SETPTR command.

Mode Description

1 Directs output to a line printer only.

2 Must be used with DEVICE option; directs output to the serial device specified by the DEVICE option.

3 Directs output to a _HOLD_ file only.

6 Directs output to both a _HOLD_ file and a printer.

9 Directs output to a line printer; suppresses display of the _HOLD_ entry name.

SETPTR Modes

Option Description

BANNER [string] Modifies the default banner line (which is the Windows user ID). Depends on MODE setting; also modifies _HOLD_ entry name.

BANNER UNIQUE [string]

Modifies the default banner line, and automatically uses attribute 1 (NEXT.HOLD) in the dictionary for the _HOLD_ file to create unique entry names for jobs sent to _HOLD_.

BRIEF Directs UniData NOT to prompt for verification upon execution of SETPTR.

COPIES n Prints n copies of the print job. Does not work with mode 3.

DEFER [time] Delays printing until the specified time. Specify the time in HH:MM format. Does not work with mode 3.

DEST unit (or AT unit) Directs output to a specific printer or queue. The unit may be either a local printer or a network printer.

SETPTR Options

Defining a Printer Unit in UniData 14-25

The next table describes spooler options you can specify in a quoted string.

DEVICE name Used with mode 2 only. Directs output to the Windows device (for instance, a COM port) identified by name.

EJECT Ejects a blank page at the end of each print job.

NOEJECT Suppresses the form feed at the end of each print job.

LNUM Prints line numbers in the left margin of each print job.

NFMT or NOFMT Suspends all UniData print formatting.

NHEAD or NOHEAD Suppresses the banner for each print job.

OPEN Opens a print file, and directs output to this file until the file is closed by the SP.CLOSE command.

Option Description

Orientation Paper orientation; must be PORTRAIT or LANDSCAPE. Defaults to the setting in the Default Document Properties sheet for the printer.

PaperSource Default paper source; must match an available paper source listed on the Device Settings tab of the printer’s Properties Sheet.

Duplex Must be NONE, HORIZONTAL, or VERTICAL; default is NONE.If the print device does not support duplex printing, this option is ignored. Jobs print single-sided and no error message displays.

Form Form to use (for instance, Letter). Must match an available paper size listed on the Device Settings tab of the printer’s Properties Sheet.

SETPTR Spooler Options

Option Description

SETPTR Options (continued)


Mode RAW or WINDOW. Default is RAW, meaning that printer-specific escape sequences are required for all formatting. Specifying formatting options (Form, Font, FontSize, Orien-tation, FontStyle, DefaultSource, or Duplex) in a quoted string automatically switches Mode to WINDOW.

Prefix stevPrinter-specific escape sequence, specified as the literal ASCII characters. Valid in RAW mode only. For example, “PREFIX = \002”

Font Font name, for instance “Courier New”. The UniData spooler creates a “logical font” using the values you provide for Font, FontSize, and FontStyle. Windows platforms attempt to find an appropriate font to use from the ones installed on your computer.

FontSize Font size in points (for instance, 8, 9, 10, 11). The UniData spooler creates a “logical font” using the values you provide for Font, FontSize, and FontStyle. Windows platforms attempt to find an appropriate font to use from the ones installed on your computer.

FontStyle Must be Regular, Italic, Bold, Underline, or StrikeOut. Default is Regular.The UniData spooler creates a “logical font” using the values you provide for Font, FontSize, and FontStyle. Windows platforms attempt to find an appropriate font to use from the ones installed on your computer.

LeftMargin Left margin of the page, in inches. For example, “LeftMargin = 1.0”

RightMargin Right margin of the page, in inches. For example, “RightMargin = 0.75”

TopMargin Top margin of the page, in inches.TopMargin is measured beginning at the value of the SETPTR topmargin option (default is 3 lines). If topmargin is 3 lines (the default) and TopMargin = 1, the first printed line is one inch below the third line on the page.

Option Description

SETPTR Spooler Options (continued)


BottomMargin Bottom margin of the page, in inches.BottomMargin is measured beginning at the value of the SETPTR bottommargin option (default is 3 lines). If bottom-margin is 3 lines (the default) and BottomMargin = 1, the first printed line is one inch above the third line from the end of the page.

Priority Must be from 1 to 99, where 1 is minimum priority and 99 is maximum.

JobState The only valid value is PAUSE, which stops all jobs to the print unit. You can reverse this option from the Printers applet.

Option Description

SETPTR Spooler Options (continued)


ExamplesYou can define local or network printers to UniData using the SETPTR command, as shown in the following examples:

:SETPTR 0,,,,,1,AT LETTER,”TopMargin=1,BottomMargin=1,Font=Courier,FontSize=12”Unit 0Mode 1 Options are:Destination LETTERLp options : TopMargin=1,BottomMargin=1,Font=Courier,FontSize=12OK to set parameters as displayed?(enter y/n) y :SETPTR 0Unit 0Width 105Length 31Top margin 3Bot margin 3Mode 1 Options are:Destination LETTERLp options : TopMargin=1,BottomMargin=1,Font=Courier,FontSize=12:SETPTR 1,,,0,0,1,AT \\DENVER4\hpzone3,"Priority=99"Unit 1Top margin 0Bot margin 0Mode 1 Options are:Destination \\DENVER4\hpzone3Lp options : Priority=99OK to set parameters as displayed?(enter y/n) y :SETPTR 2,,,,,1,AT LEGALUnit 2Mode 1 Options are:Destination LEGALOK to set parameters as displayed?(enter y/n) Y :SETPTR 3,,,,,1,AT \\DENVER4\hpzone2,"Form=A4"Unit 3Mode 1 Options are:Destination \\DENVER4\hpzone2Lp options : Form=A4OK to set parameters as displayed?(enter y/n) y



The default print device (printer unit 0) is now mapped to the local printer LETTER. If you use the PRINT command or LPTR with no print unit specified, UniData directs your print job to LETTER.Use SETPTR unit to display the current settings for a print unit.When you specify spooler options (TopMargin, BottomMargin), UniData automatically recalculates the width and length taking these into account. When you specify formatting options in a quoted string, UniData implicitly changes the spooler Mode from RAW (the default) to WINDOW.You can specify spooler options in a quoted string either before or after SETPTR options like AT, DEFER.You can map a printer unit to a network print device even if that device is not displayed in your Printers dialog.


After you have defined printers with SETPTR, you can display a list with the LISTPTR command, as shown below:

:LISTPTRUnit.. Printer................... Port.......................Status..0 LETTER \\DENVER4\hpzone3 Running1 \\DENVER4\hpzone3 hpzone3 Running2 LEGAL \\DENVER4\hpzone3 Running3 \\DENVER4\hpzone2 hpzone2 RunningNotice that, in the previous example, the two local printers point to the same network print device.Use PTRDISABLE and PTRENABLE (STOPPTR and STARTPTR) to control printers::PTRDISABLE LETTER:LISTPTRUnit.. Printer................... Port.......................Status..0 LETTER \\DENVER4\hpzone3 Paused1 \\DENVER4\hpzone3 hpzone3 Running2 LEGAL \\DENVER4\hpzone3 Running3 \\DENVER4\hpzone2 hpzone2 Running:PTRENABLE LETTER:LISTPTRUnit.. Printer................... Port.......................Status..0 LETTER \\DENVER4\hpzone3 Running1 \\DENVER4\hpzone3 hpzone3 Running2 LEGAL \\DENVER4\hpzone3 Running3 \\DENVER4\hpzone2 hpzone2 Running:

Only users with Full Control permissions on a printer can control the printer with PTRDISABLE and PTRENABLE. Check Permissions on the Security tab of the Properties sheet for the printer to determine who has permissions.

Notice that the argument for PTRDISABLE and PTRENABLE is the name of the printer (as specified with DEST or AT in SETPTR).


You can use the ECL SP.STATUS command to display information about printers defined with SETPTR and print jobs started from your UniData session.

The following example shows SP.STATUS output:

:SP.STATUSDevice for LETTER: \\DENVER4\hpzone3LETTER is Running.Device for \\DENVER4\hpzone3: hpzone3\\DENVER4\hpzone3 is Running.Device for LEGAL: \\DENVER4\hpzone3LEGAL is Running.Device for \\DENVER4\hpzone2: hpzone2\\DENVER4\hpzone2 is Running.JobId.... User............ Size.... Status... Unit.. Printer..................241 terric 543 Defered 3 \\DENVER4\hpzone2 \ :

The status of all the printers is Running, and the network print device has a deferred job.

Depending on how a print device was configured, users in console sessions may see printer notification messages when a job completes.

Note: The Printing Notification only displays if you log on to a console session. If you log on to UniData through Telnet, you will not see the notification.


Printing to the _HOLD_ FileSelecting SETPTR mode 3, 6, or 9 on the command line directs output from printing commands to the _HOLD_ file. When you print to the _HOLD_ file, UniData actually creates two entries, one for the printing command output and one for the SETPTR settings. UniData preserves the SETPTR settings so you can print from the _HOLD_ file at a later time using the settings selected with SETPTR. The following example shows the creation and contents of two _HOLD_ entries generated by a printing command:

:SETPTR 0,,,,,3Unit 0Mode 3 Options are:OK to set parameters as displayed?(enter y/n) YHold Entry _HOLD_/P_0000:LIST VOC SAMPLE 10 LPTR:LIST _HOLD__HOLD_.... P_0000P_0000.SETPTR2 records listed_HOLD_ entry P_0000 is the output from the LIST command, and P_0000.SETPTR contains the printer settings. You can display the contents of P_0000.SETPTR, as they can display any _HOLD_ entry, with SP.EDIT, as shown in the following example::SP.EDIT P_0000.SETPTR Hold item P_0000.SETPTR - (t) terminal (f) find (s) spool (d) delete or (q) quit ?TSpooler Options: Orientation..... 0PaperSize....... 0PrintQuality.... 0Color........... 0Duplex.......... 0PaperSource... 0TopMargin....... 0.000000BottomMargin.... 0.000000LeftMargin...... 0.000000RightMargin..... 0.000000Font............ NULLFontStyle....... Hold item P_0000.SETPTR - (t) terminal (f) find (s) spool (d) delete or (q) quit ?


Selecting a Spooler ModeThe UniData spooler interface enables you to print to an Windows printer using one of two spooler modes: RAW or WINDOW.

RAW Mode

In RAW mode, the default, all formatting is controlled by printer-specific escape sequences you include in your print job. UniData writes to the spooler device using the WritePrinter win32 API call. RAW mode enables you to migrate existing appli-cations and utilities without rewriting printing logic.

WINDOW Mode

In WINDOW mode, formatting is controlled by your selection of SETPTR options and spooler options. You can print in WINDOW mode by specifying “Mode=WINDOW” on the SETPTR command line or by including any of the spooler options (Form, Font, FontSize, Orientation, FontStyle, DefaultSource, or Duplex) that only work in WINDOW mode.


Examples

In the following example, the spooler mode is changed from RAW (the default) to WINDOW. Notice that UniData changes the width and length automatically:

:SETPTRUnit 0Width 132Length 60Top margin 3Bot margin 3Mode 1 Options are::SETPTR 0,,,,,1,"Mode=WINDOW"Unit 0Mode 1 Options are:Lp options : Mode=WINDOWOK to set parameters as displayed?(enter y/n) Y:SETPTRUnit 0Width 80Length 56Top margin 3Bot margin 3Mode 1 Options are:Lp options : Mode=WINDOW:


In the next example, setting Font to COURIER implicitly changes the spooler mode to WINDOW, even though the display does not indicate this. Notice that width and length were adjusted:

:SETPTR Unit 0Width 132Length 60Top margin 3Bot margin 3Mode 1 Options are::SETPTR 0,,,,,1,”Font=COURIER”Unit 0Mode 1 Options are:Lp options : Font=COURIEROK to set parameters as displayed?(enter y/n) Y:SETPTRUnit 0Width 80Length 56Top margin 3Bot margin 3Mode 1 Options are:Lp options : Font=COURIER:

If you combine incompatible options on the SETPTR command line, the command fails with an error message as shown in the following example:

:SETPTR 0,,,,,,"Mode=RAW,Font=COURIER"Unit 0Options are:Lp options : Mode=RAW,Font=COURIEROK to set parameters as displayed?(enter y/n) YInvalid combination of spooler options 'Mode=RAW,Font=COURIER':


Redefining the Default UniData Print UnitTo keep UniBasic applications general, developers typically use (or assume) printer unit 0, which is the default. The SETPTR command enables you to redefine unit 0 to direct output from different parts of an application to different physical printers or queues, or to change formatting options. The following example is a very simple paragraph that redefines the default print unit for different reports:

Submitting Concurrent Print JobsWith SETPTR, you can define up to 31 logical printer units in a single UniData session. You can use this functionality to submit concurrent print jobs from a UniBasic application. One common implementation follows:

Define two logical printer units (for instance, 0 and 1) that point to different physical print devices.Direct all lines of a report to one printer with the UniBasic PRINT ON command (for instance, PRINT ON 0 PRINT.LINE).Direct summary (break) lines to the second printer (PRINT ON 0 PRINT.LINE followed by PRINT ON 1 PRINT.LINE).

In this way, you can print a summary report and a detail report at the same time.


UniData Printing CommandsUniData includes a number of options that enable you to customize output from UniBasic programs and reports. See the UDT.OPTIONS Commands Reference for a complete listing of all available options.

The following table describes ECL commands related to printing.

Note: See the UniData Commands Reference for the syntax of these ECL commands.

Command Description

SETPTR Defines logical printer units within a UniData session.

SPOOL Prints the contents of a record to the printer.

PTRDISABLE or STOPPTR

Pauses a Windows printer. You must supply the printer name (the name you used with the DEST or AT option) rather than the UniData logical print unit number.

PTRENABLE or STARTPTR

Resumes a Windows local printer. You must supply the printer name (the name you used with the DEST or AT option) rather than the UniData logical print unit number.

SP.CLOSE Closes a print file.

SP.ASSIGN Sets characteristics of the default UniData print device, printer unit 0 (Pick® compatible syntax).

SP.EDIT Views or prints files in the _HOLD_ directory

SP.KILL Cancels a job.

SP.OPEN Opens a continuous print job. This command is equivalent to the UniData SETPTR,,,,,,OPEN command.

SP.STATUS Provides printer and queue information.

LISTPTR Displays the names of printers and the paths of devices associated with them.

LISTPEQS Lists entries in the _HOLD_ file of the current account.

ECL Printing Commands


15Chapter

Managing Cataloged Programs

UniBasic Source and Compiled Programs . . . . . . . . . . . 15-3 UniBasic Compiled Programs . . . . . . . . . . . . . 15-3Cataloging UniBasic Programs . . . . . . . . . . . . . . 15-4 Direct Cataloging . . . . . . . . . . . . . . . . . 15-4 Local Cataloging . . . . . . . . . . . . . . . . . 15-4 Global Cataloging . . . . . . . . . . . . . . . . . 15-5Managing Global Catalogs. . . . . . . . . . . . . . . . 15-7 Contents of a Global Catalog . . . . . . . . . . . . . 15-7 Verifying a Program Version. . . . . . . . . . . . . . 15-8 Activating Newly Cataloged Programs and Subroutines . . . . . 15-10Listing Programs in Use . . . . . . . . . . . . . . . . 15-14Creating an Alternate Global Catalog Space . . . . . . . . . . 15-15 Files and Directories Created by newhome . . . . . . . . . 15-16 Procedure for Creating an Alternate Global Catalog Space . . . . 15-17

This chapter describes the behavior of global, direct, and local cataloging for UniBasic programs. The chapter also describes how to create an alternate global catalog space using the newhome command.


UniBasic Source and Compiled ProgramsUniData stores UniBasic source code in DIR-type files in the UniData account where the source is developed. The default location for storing UniBasic source code files is the BP file, which UniData creates as an empty file when you create a UniData account. Developers store UniBasic source code files as records in the BP file.

Note: In a UniData DIR-type file, such as BP, each “record” is a file.

Each UniData account may contain numerous DIR files for UniBasic source.

UniBasic Compiled ProgramsWhen you issue the BASIC command to compile a UniBasic program, UniData stores the compiled code in the same DIR file where the source code resides. The compiled code is a record whose name is the same as the source record, prefixed with an underscore.

Note: See the UniData Commands Reference and Developing UniBasic Applications for information about the BASIC command.

The following example shows the contents of a program file:

:LIST BPTEST_TESTTEST2_TEST2EXAMPLE3_EXAMPLE3EXAMPLE5_EXAMPLE58 records listed

Records beginning with an underscore are compiled programs. Other records are UniBasic source files.

Note: Use the ECL RUN command to execute a compiled program. See the UniData Commands Reference and Developing UniBasic Applications for information about the RUN command.

UniBasic Source and Compiled Programs 15-3

Cataloging UniBasic ProgramsCataloging UniBasic programs simplifies program execution and can improve efficiency of system resource use by allowing multiple users to access a single copy of a compiled program from shared memory. Use the ECL CATALOG command to catalog one or more UniBasic programs.

Note: See the UniData Commands Reference and Developing UniBasic Applications for information about cataloging and the CATALOG command.

Compiled UniBasic programs can be cataloged directly, locally, or globally.

Direct CatalogingPoints to remember about direct cataloging are:

Compiled code is located in the program file in the UniData account where the program was compiled and cataloged.The VOC file in the account contains a pointer to the compiled code in the program file. Users in the same account can execute the program by entering the program name at the ECL prompt. Because users access the compiled code in the program file, developers do not need to recatalog the code if they recompile. When you execute a directly cataloged program, UniData loads a copy of the program into your address space.

Local CatalogingPoints to remember about local cataloging are:

Compiled code is located in the CTLG directory in the UniData account where the program was cataloged, as well as in the program file. CTLG is a DIR-type UniData file, and each record is a compiled UniBasic program.The VOC file in the account contains a pointer to the compiled program in the CTLG. Users in the same account can execute the program by entering the program name at the ECL prompt. Developers must recatalog a program after recompiling to place a new copy of the compiled code into the CTLG.


When you execute a locally cataloged program, UniData loads a copy of the program into your address space.

Global CatalogingPoints to remember about global cataloging are:

If you execute the CATALOG command without specifying local or direct cataloging, your program is globally cataloged.Compiled code is located in a systemwide global catalog. The default global catalog is udthome\sys\CTLG. Developers must recatalog a program after recompiling it to place a new copy of the compiled code into the global catalog.

Note: A UniData installation can have more than one global catalog space. The environment variable UDTHOME determines which global catalog space a particular UniData session accesses. See “Creating an Alternate Global Catalog Space” on page 15-15 for more information about creating multiple global catalog spaces.

A systemwide global catalog is a DIR-type file, with 26 subdirectories named a through z. Compiled code is located in the subdirectory corre-sponding to the first letter of the program name. Compiled programs that begin with nonalphabetic characters are stored in a subdirectory named X. The cataloged program name can be the same as the source and object, or you can specify a different name when you execute CATALOG.

Tip: Consider your program naming conventions if you are using global cataloging. Since UniData places the compiled code in subdirectories according to name, you may have an unbalanced situation if a large number of your program names begin with the same letter (for instance, a general ledger application where all the files begin with “gl”).

A globally cataloged program is available to users in all UniData accounts. When you execute a globally cataloged program, the shared basic code server (sbcs) checks to see if a copy already exists in the shared memory it controls.If so, sbcs notifies the udt process which shared memory segment to attach to access that copy.If not, sbcs loads a copy into one of its shared memory segments for you to execute.

Cataloging UniBasic Programs 15-5

Any object file located in the udthome\sys\CTLG file system is handled by sbcs, regardless of how the program is accessed.The sbcs process can manage up to 20 shared memory segments for globally cataloged programs. UniData determines the size of each segment by the SBCS_SHM_SIZE parameter in the UniData configuration file (\udthome\include\udtconfig). The default value for SBCS_SHM_SIZE is 1,048,576 bytes (1 MB), which is set when you install UniData. You will encounter runtime errors if this size is insufficient. You can increase the segment size as long as you do not exceed the configuration parameter SHM_MAX_SIZE.

Tip: See “Appendix A UniData Configuration Parameters” for more information about SBCS_SHM_SIZE and SHM_MAX_SIZE.


Managing Global CatalogsUniData provides a group of files and commands that manage global catalogs. These files and commands accomplish the following:

Identify the contents of a global catalog spaceVerify consistency between UniBasic source and a globally cataloged programActivate newly cataloged programs and subroutinesDisplay use of globally cataloged programs

Contents of a Global CatalogUniData maintains two files that store contents of a global catalog. The global catalog table, called CTLGTB, is a dynamically maintained file that shows the current contents of the global catalog. You can list the catalog table from a UniData account, as shown in the following example:

:LIST CTLGTB ALLLIST CTLGTB ALL 15:33:59 Jun 14 2005 1CATALOG NAME................ T ARG ORIGINATOR............ WHO.... SCHEMA_UPDATE_PRIVILEGES S 51 @UDTHOME/SYS_BP SCHEMA root _UPDATE_PRIVILEGESSCHEMA_LIST_USERS S 31 @UDTHOME/SYS_BP SCHEMA root _LIST_USERSSCHEMA_VIEW_CHECK S 71 @UDTHOME/SYS_BP SCHEMA root _VIEW_CHECKUS_EXECUTOR S 51 @UDTHOME/SYS_BP US_EXE root CUTORBUILD.CHARTBL S 01 @UDTHOME/DENAT_BP BUIL root D.CHARTBL508E S 41 @UDTHOME/SYS_BP 508E rootRPROG2_AE S 11 @UDTHOME/AE_BP RPROG2_ root AEJRNL_TEST M 0 @UDTHOME/SYS_BP JRNL_T root ESTSCHEMA_DELETE_MAP S 41 @UDTHOME/SYS_BP SCHEMA root _DELETE_MAPNFA.EXECSEL.U S 31 @UDTHOME/SYS_BP NFA.EX root ECSEL.U70E0 S 41 @UDTHOME/SYS_BP 70E0 root...

Managing Global Catalogs 15-7

The _MAP_ file also contains information about the contents of a global catalog. In addition to the information in CTLGTB, _MAP_ includes the size of each compiled program, the date it was cataloged, and the last date it was executed. The _MAP_ file is not dynamically maintained by UniData. The ECL MAP command updates the _MAP_ file to reflect recent activity. The MAP command clears the _MAP_ file, updates the file, and displays its contents, as shown in the following example:

:MAPMAP 09:42:41 Feb 03 2005 1NAME............ TYPE ARG ORIGINATOR.......... WHO.... OBJ... DATE.... LAST REF

508E S 4 @UDTHOME/SYS_BP 508E root 184 01/14/05 01/20/05COUNT.MSG S 3 @UDTHOME/DENAT_BP CO root 582 01/14/05 01/20/05 UNT.MSGSORT_AE S 1 @UDTHOME/AE_BP SORT_ root 1650 01/14/05 01/20/05 AE7201 S 4 @UDTHOME/SYS_BP 7201 root 180 01/14/05 01/20/05NFA.EXECSEL.U S 3 @UDTHOME/SYS_BP NFA. root 154 01/14/05 01/20/05 EXECSEL.US_VALID_FILE_CHE S 6 @UDTHOME/SYS_BP S_VA root 1712 01/14/05 01/20/05CK LID_FILE_CHECKERRMSG.COMMON M 0 @UDTHOME/DENAT_BP ER root 92 01/14/05 01/20/05 RMSG.COMMONRPROG_AE S 1 @UDTHOME/AE_BP RPROG root 4708 01/14/05 01/20/05 _AESCHEMA_OBJECT_TY S 4 @UDTHOME/SYS_BP SCHE root 1914 01/14/05 01/20/05PE MA_OBJECT_TYPES_VALID_NAME_CHE S 3 @UDTHOME/SYS_BP S_VA root 2184 01/14/05 01/20/05CK LID_NAME_CHECKSCHEMA_REMOVE_SC S 3 @UDTHOME/SYS_BP SCHE root 1364 01/14/05 01/20/05HEMA MA_REMOVE_SCHEMA...

By default, the CTLGTB file and the _MAP_ file are located in the same directory as the global catalog: udthome\sys.

Tip: The CTLGTB file and the _MAP_ file are UniData hashed files. You can display records in these files with standard ECL and UniQuery commands to determine if particular programs are in the global catalog.

Verifying a Program VersionThe VCATALOG command checks the date/time stamp of a UniBasic source file against the compiled program in the global catalog. If the UniBasic source file was modified after the program was cataloged, the program does not verify. The following example shows output from VCATALOG:

Syntax:

VCATALOG filename catalog.name program.name



Note: If catalog.name and program.name are the same, you need only supply the name once.

:VCATALOG BP TESTProgram 'TEST' does not verify.:CATALOG BP TESTC:\UniData71\sys\CTLG\t\TEST has been cataloged, do you want to overwrite?(Y/N)Y:VCATALOG BP TESTProgram 'TEST' does not verify.:BASIC BP TEST Compiling Unibasic: BP/TEST in mode 'u'.compilation finished:CATALOG BP TEST\UniData71\sys\CTLG\t\TEST has been cataloged, do you want to overwrite?(Y/N) Y:VCATALOG BP TESTProgram 'TEST' verifies.:

In the example, notice that recataloging the program did not make the program verify. This result indicates that the source code was changed, but was not recompiled or recataloged. After the source code was recompiled and recataloged, the program verified successfully.

See the UniData Commands Reference for more information about the VCATALOG command.


filename Name of the file containing the program (BP, for instance).

catalog.name Name given to the program when you executed CATALOG. For example, the command CATALOG BP TRIAL TEST creates a global catalog entry named TRIAL from a program called TEST. So catalog.name is TRIAL.

program.name Name of the program source file. In the example in the previous row of this table, program.name is TEST.

VCATALOG Parameters


Activating Newly Cataloged Programs and Subroutines

Main Programs

When you globally catalog a UniBasic main program, UniData:

Copies the new compiled code into the global catalog.If there is a version of the program in shared memory, marks that version as obsolete.

The users already executing the main program continue to execute the previous version. Users that execute the program after the new version is cataloged get the new version. Once all users exit the previous version, UniData removes the copy of that version from shared memory.

Note: A user executing a main program continues to execute that version until it completes.

Subroutines

If a subroutine is recataloged while the main program is running, users will not execute the newly-cataloged subroutine until the next time they execute the main program. This prevents inconsistent execution of a subroutine during one execution of the main program. Under certain circumstances, however, a user or system admin-istrator can override the default behavior. Overrides are dangerous in a production environment, but may be useful in a development or test environment.

NEWVERSION Keyword

The NEWVERSION keyword for the CATALOG command allows a user logged on as an Administrator to dynamically replace a globally cataloged subroutine. If a subroutine is cataloged with NEWVERSION, any user executing the main program accesses the new version of the subroutine with the next CALL or EXECUTE of the subroutine, rather than waiting until the main program completes. Consider the following sequence of events:

1. A user executes the main program MAIN. 2. MAIN calls a subroutine called SUBR, which completes and returns to

MAIN.


3. MAIN continues with other processing.4. MAIN calls SUBR again. SUBR completes and returns to MAIN.5. MAIN completes.

If SUBR is recataloged after step 1 without the NEWVERSION keyword, the same version of SUBR is used for both calls (step 2 and step 4). With the next execution of MAIN, the newly cataloged SUBR is used.

If SUBR is recataloged after step 1, with the NEWVERSION keyword, there are three possible results:

CATALOG happens after step 1 but before step 2. In this case, the newly cataloged SUBR gets accessed in both step 2 and step 4.CATALOG happens after step 2, but before step 4. In this case, the prior version of SUBR gets accessed in step 2, and the newly cataloged version gets accessed in step 4.CATALOG happens after step 4. In this case, the prior version gets accessed in both step 2 and step 4. With the next execution of MAIN, the newly cataloged SUBR is accessed.

Warning: Using the NEWVERSION keyword to CATALOG a subroutine can produce inconsistent results for users who are currently executing the main program. For example, the number of arguments could change.

The following sample CATALOG command shows the syntax including the NEWVERSION keyword:

:CATALOG BP SUBR NEWVERSION\UniData71\sys\CTLG\s\SUBR has been cataloged, do you want to overwrite?(Y/N) Y:

newversion System-Level Command

The UniData system-level command newversion allows a user logged on as an Administrator to dynamically replace a cataloged subroutine (just as the NEWVERSION keyword does) but limits the behavior to a selected user or users.

Syntax:

newversion path userno...



The following screen shows an example of the newversion command:

:LISTUSERLicensed(reg+pooled)/Effective Udt Sql iPhtm Pooled Total

( 32+10 )/42 2 0 0 0 2


2 2452 0 cgustafs udt pts/2 Console 09:52:50 Feb 03 2005:CATALOG BP SUBR\UniData71\sys\CTLG\s\SUBR has been cataloged, do you want to overwrite?(Y/N) Y::!newversion \UniData60\sys\CTLG\s\SUBR 2664

In the example, the newly cataloged subroutine is dynamically available to cgustafs, the owner of user number 2664. If cgustafs is executing a main program that calls a subroutine, the next call to the subroutine accesses the newly cataloged version. For all users other than cgustafs, the default behavior remains in effect. The newly cataloged subroutine is activated with the next execution of the main program, not the next subroutine call. Notice that, in the example, the subroutine is globally cataloged; this command works with locally or directly cataloged routines as well.

NEWPCODE Command

The ECL NEWPCODE command dynamically activates a cataloged subroutine. This command is useful if a developer uses a UniBasic shell program to modify, recompile, recatalog, and retest a UniBasic program without exiting to ECL.

Syntax:

NEWPCODE path


path Absolute path of the cataloged subroutine.

userno... Process ID (pid) for a user who should access the new subroutine dynam-ically. You can specify more than one userno; separate the numbers with spaces.

newversion Parameters


path is the absolute path of a cataloged subroutine. The following example shows one use of the NEWPCODE command executed in a UniBasic program:

* PROGRAM MAINPROG* NEWPCODE EXAMPLEEXECUTE "MAINPROG2"EXECUTE "BASIC BP MAINPROG2"EXECUTE "CATALOG BP MAINPROG2 DIRECT"EXECUTE "NEWPCODE \UniData71\sys\CTLG\m\MAINPROG2"EXECUTE "MAINPROG2"END

In the example, a user executing MAINPROG accesses the current version of MAINPROG2 in the first statement. Including the NEWPCODE command before the next execution of MAINPROG2 causes the program to access the newest version. (In the example, MAINPROG2 was recompiled and recataloged after the first step, so the next execution accesses the newly cataloged MAINPROG2.)

Tip: If you are developing programs with the AE editor, the N option of the FI command equates to the NEWPCODE command. For example, FIBCFN compiles a program and catalogs it (locally) with NEWPCODE. You need to use F (force) in conjunction with the N option. See the online help for the AE editor or Developing UniBasic Applications for more information.

Note: The NEWPCODE command is effective only in the udt session where it is executed. Although NEWPCODE is an ECL command, you cannot affect a different user or even a different window with NEWPCODE.


Listing Programs in UseThe UniData system-level sbcsprogs command enables any user with access to the system-level prompt to display a list of globally cataloged programs currently in use, with counters for the number of processes currently accessing each one. The following example shows typical output from sbcsprogs:

# sbcsprogs Program Name Reference Count \UniData71\sys\CTLG\a\AE 2\UniData71\sys\CTLG\a\AE_ICOM1 1\UniData71\sys\CTLG\a\AE_AE 2\UniData71\sys\CTLG\a\AE_UPS 1

In the example, two users are executing AE, and two are executing AE_AE. The sbcs daemon maintains the counter, incrementing it as users execute a program and decreasing it as users complete execution. When the counter for a routine reaches zero, sbcs removes the copy of the compiled program from shared memory, making the space available for other programs as needed.

Tip: If you run sbcsprogs regularly throughout your processing cycle, you can learn which programs are used most heavily. This information is useful if you are troubleshooting an application performance problem.

Note: The reference counter is not decremented when a user terminates abnormally (for example, when a process is killed). Because of this, the count may be inaccu-rately high, causing excess memory to remain held. Stopping and restarting UniData resets the counter and releases memory.


Creating an Alternate Global Catalog SpaceThe system-level newhome command creates a new UniData account containing an alternate global catalog space for use in development and testing.

Creating an Alternate Global Catalog Space 15-15

Files and Directories Created by newhomeUniData creates or overlays the directory indicated by path. This directory contains only the subdirectory sys, which contains the following files and directories:

Volume in drive C has no label. Volume Serial Number is 39CF-18E1

Directory of C:\IBM\ud72\sys

04/15/05 10:46a <DIR> .04/15/05 10:46a <DIR> ..04/12/05 03:23p 6,175 @README04/12/05 03:23p 1,683 @README-IMPORTANT04/12/05 03:23p 59,108 @VERSIONS04/15/05 10:46a <DIR> AE_BP04/12/05 03:23p 4,096 AE_COMS04/12/05 03:23p 10,240 AE_COMS_DEMO04/12/05 03:23p 374,784 AE_DOC04/15/05 10:46a <DIR> AE_SECURITY04/15/05 10:46a <DIR> AE_SYSTOOLS04/15/05 10:46a <DIR> AE_UPCHARS04/12/05 03:23p 77,824 AE_XCOMS04/15/05 10:46a <DIR> BP04/12/05 03:23p 12,288 COLLATIONS04/04/05 11:43a <DIR> CTLG03/29/05 03:37p 21,504 CTLGTB04/15/05 10:46a <DIR> DENAT_BP03/29/02 03:37p 2,048 DICT.DICT04/12/05 03:23p 2,048 D_AE_BP04/12/05 03:23p 2,048 D_AE_COMS04/12/05 03:23p 2,048 D_AE_COMS_DEMO04/12/05 03:23p 2,048 D_AE_DOC04/12/05 03:23p 2,048 D_AE_SCRATCH04/12/05 03:23p 2,048 D_AE_XCOMS04/12/05 03:23p 2,048 D_BP04/12/05 03:23p 2,048 D_COLLATIONS04/12/05 03:23p 2,048 D_CTLG04/12/05 03:23p 2,048 D_CTLGTB04/12/05 03:23p 2,048 D_DENAT_BP04/12/05 03:23p 2,048 D_ENGLISH.MSG04/12/05 03:23p 2,048 D_ENGLISH_G2.MSG04/12/05 03:23p 2,048 D_FRENCH.MSG04/12/05 03:23p 2,048 D_HELP.FILE04/12/05 03:23p 2,048 D_INCLUDE04/12/05 03:23p 2,048 D_JAPANESE.MSG04/12/05 03:23p 2,048 D_MSG.DEFAULTS04/12/05 03:23p 2,048 D_REP_RECV_LOG04/12/05 03:23p 2,048 D_REP_RECV_REC04/12/05 03:23p 2,048 D_SAVEDLISTS04/12/05 03:23p 2,048 D_SYS_BP04/12/05 03:23p 2,048 D_UD.ACCOUNT04/12/05 03:23p 5,120 D_UDT_GUIDE


04/12/05 03:23p 4,096 D_VOC04/12/05 03:23p 2,048 D__DEBUG_04/12/05 03:23p 2,048 D__MAP_04/12/05 03:23p 2,048 D__PH_04/12/05 03:23p 339,968 ENGLISH.MSG04/12/05 03:23p 339,968 ENGLISH_G2.MSG04/12/05 03:23p 359,424 FRENCH.MSG04/12/05 03:23p 4,046,848 HELP.FILE04/15/05 10:46a <DIR> INCLUDE04/12/05 03:23p 263,168 JAPANESE.MSG04/12/05 03:23p 367 LANGGRP04/12/05 03:23p 826 makefile04/12/05 03:23p 1,240 MULTIBYTE.CONFIG04/12/05 03:23p 12,288 REP_RECV_LOG04/12/05 03:23p 12,288 REP_RECV_REC04/04/05 11:43a <DIR> SAVEDLISTS04/12/05 03:23p 2,879 set_sys.sh04/15/05 10:46a <DIR> SYS_BP04/12/05 03:23p 4,096 UD.ACCOUNT04/12/05 03:23p 15,360 uniapi.msg04/15/05 10:46a 111,616 VOC04/15/05 10:46a 2,714 vocupgrade04/12/05 03:23p 3,588,096 X_HELP.FILE04/12/05 03:23p 2,048 _DEBUG_03/29/05 03:37p 8,192 _MAP_04/04/05 11:43a <DIR> _PH_ 69 File(s) 9,743,600 bytes 778,334,208 bytes free

The following directories make up the program catalog spaces:

D_CTLGTBCTLGTBD_CTLGCTLG, including subdirectories a through z and X for storing globally cataloged programs.

newhome does not create the entire directory structure that exists in the default UniData home directory, and it does not copy UniBasic executables developed at your site.

Procedure for Creating an Alternate Global Catalog SpaceFollow the steps below to create an alternate global catalog space:


1. Change to the New Account Directory

At the operating system prompt, change to the directory in which you intend to locate the new UniData account, as shown in the following example:

C:\UniData71>cd \UniData71\claireg

2. Execute newhome

Execute the newhome command, indicating the path to the new account. In this example, a new directory, testenv, will be created under \UniData71\claireg.

Notice that the newhome command is executed from the ECL prompt, and therefore is preceded by the ! ECL command:

:!newhome testenv Creating new udt home \UniData71\claireg\testenv ...

Unidata has created the new home account. This account contains only the include and sys directory with Unidata's cataloged programs. To access your new home account, you must reset the UDTHOME environment variable or change the value in your registry.

3. Modify VOC Entries for Users

Decide which UniData accounts should access the new global catalog space. For each account, modify the VOC entry for CTLGTB. The entry should point to the new global catalog space, as shown in the following example.

Notice that this example uses a soft pointer to @UDTHOME. This ensures that the VOC always points to the correct catalog space.

:AE VOC CTLGTBTop of "CTLGTB" in "VOC", 3 lines, 45 characters.*--: P001: F002: @UDTHOME\sys\CTLGTB003: @UDTHOME\sys\D_CTLGTBBottom.*--:

You do not need to log on as an Administrator to edit the VOC entries; however, you need write permissions on the VOC file in each account.


4. Modify UDTHOME for Users

You need to reset the UDTHOME environment variable for each user who needs to access the alternate global catalog space. The value of UDTHOME that is defined during a particular UniData session determines the global catalog space a user accesses.

Note: Even if the VOC file is set up to point to the alternate global catalog (CTLGTB), a user whose UDTHOME is set to the default value accesses the default global catalog space.

5. Copy Application Programs

After resetting UDTHOME to point to the new space, start UniData from an account that has access to the site-specific programs that you want to access from the new account, and recatalog those programs. Because you have reset the UDTHOME environment variable, the recataloged programs are placed in the new space.

6. Use the Alternate Global Catalog Space

The alternate global catalog space is now ready to use. The following example shows the output of the sbcsprogs command when two global catalog spaces are used:

% sbcsprogs

Program Name Reference Count ... 1\UniData72\testenv\sys\CTLG\a\AE\UniData72\testenv\sys\CTLG\a\AE_UPS 1\disk1\ud72\sys\CTLG\a\AE 1\disk1\ud72\sys\CTLG\a\AE_ICOM1 1\disk1\ud72\sys\CTLG\a\AE_UPS 1...%

Notice that AE is running twice, but that the two copies are cataloged in different global catalog spaces.


16Chapter

Managing and Using Tape Devices

UniData Tape Handling Commands . . . . . . . . . . . . . 16-3 SETTAPE . . . . . . . . . . . . . . . . . . . 16-4Steps for Tape Device Use . . . . . . . . . . . . . . . . 16-6

This chapter describes UniData commands for identifying and accessing Windows tape devices.

Tip: When you define tape devices within UniData, you must use the Universal Naming Convention (UNC) format for device names. Refer to your Microsoft documentation for information about UNC format.

16-2

UniData Tape Handling CommandsUniData includes a number of ECL and UniBasic commands for reading data from a tape and writing data to a tape. The ECL commands are summarized in the following table.

Note: See the UniData Commands Reference for information about ECL commands.

Command Description

SETTAPE Defines a logical tape unit in UniData; must precede any other tape commands.

T.ATT Links a logical tape unit to a UniData process; must precede any reads/writes involving the tape.

T.BAK Moves a tape backward by a specified number of files.

T.CHK Reads a tape created by T.DUMP and checks for damage.

T.DET Releases a logical tape unit when a UniData process is finished with it.

T.DUMP Copies the contents of a file or active select list to tape.

T.EOD Moves a tape unit to end of file.

T.FWD Moves a tape unit to the beginning of the next file.

T.LOAD Loads records from a tape created with T.DUMP.

T.RDLBL Reads and displays the first 80 characters of the tape label on a tape created with T.DUMP.

T.READ Reads and displays the next record from tape.

T.REW Rewinds a tape to the beginning.

T.SPACE Moves a tape forward a specified number of spaces.

T.STATUS Displays current tape device assignments.

T.UNLOAD Rewinds and unloads a tape.

T.WEOF Writes an end-of-file mark on a tape.

ECL Tape Handling Commands


The next table summarizes UniBasic commands for I/O on tape devices.

Note: See the UniBasic Commands Reference for information about these UniBasic commands.

SETTAPESyntax:

SETTAPE unit.no [dn.path.nr][dn.path.r][blocksize]

Description

The SETTAPE command defines logical tape units in your UniData environment. This command establishes a link between a UniData internal tape unit number and a tape device. You can use SETTAPE to relate unit number to tape devices or disk files.

Any user can execute SETTAPE unit.no to display the current settings for a tape unit. However, you must log on as an Administrator to define a tape unit or modify settings.

Once a tape unit has been defined using SETTAPE, it can be accessed by users in any UniData account on your system. The tape unit definition remains the same unless it is changed by an Administrator.

Command Description

READT Reads the next available record from tape.

RESIZET Changes the block size used by the WRITET statement.

REWIND Rewinds a tape to the beginning.

WEOF Writes an end-of-file mark to a tape.

WRITET Writes the value of a specified expression as a record on a tape.

UniBasic Tape Handling Commands

UniData Tape Handling Commands 16-4

Writing to a Device

To relate a tape unit number to a tape device, use the full UNC format for the device name in the SETTAPE command syntax. The following example shows how to identify a tape device with SETTAPE:

:SETTAPE 0 \\.\TAPE0 R\\.\TAPE0 16384

Writing to a File

To relate a tape unit number to a disk file, use the full path and file name in the SETTAPE command syntax. The disk file must already exist. The following example shows how to identify a disk file with SETTAPE:

:SETTAPE 1 A:\TAPEFILE RA:\TAPEFILE 4096

Parameters

The following table describes the parameters of the SETTAPE syntax.


unit.no Internal UniData tape unit number. Must be from 0 to 9. The default tape unit is 0.

[dn.path.nr] Device name, in UNC format, or full path and file name of disk file for no rewind device driver for unit.no.

[dn.path.r] Device name, in UNC format, or full path and file name of disk file, for rewind device driver for unit.no.

[blocksize] Tape block size in bytes; must be a multiple of 512. If you do not specify blocksize, the default value is 4096.

SETTAPE Parameters


Steps for Tape Device UseThe following steps must take place, in order, for successful tape device use from UniData.

1. Define Tape UnitsA user with Administrator privilege must execute the SETTAPE command to define up to 10 tape units for the UniData environment.

Note: Remember that the tape unit number must be from 0 through 9. These are logical tape unit numbers within UniData; the SETTAPE command maps these to Windows device names.

Warning: When defining tape units, be sure to define unit 0. Some of the UniData tape handling commands require unit 0 to be defined so that it can be used as a default.

When you define a tape device or modify a definition, you create or update an entry in the text file udthome\sys\tapeinfo.

2. Attach a Tape DeviceYou must attach a logical tape device to your process before accessing it. The T.ATT command attaches a tape device. Any user can execute T.ATT from the ECL prompt or from within a UniBasic program. The following screen shows some typical outputs from T.ATT:

:T.ATT 5No information for unit 5 yet, ask your system administrator for help.T.ATT failed.:T.ATT 1unit 1 is attached by another processIt is lock number 65 in LIST.LOCKS.Try again later, T.ATT failed.:T.ATT 2 BLKSIZE 16384tape unit 2 blocksize = 16384.:

Notice the following points about T.ATT.

Steps for Tape Device Use 16-6

You cannot attach a tape unit with T.ATT unless the unit was previously defined with SETTAPE.You can execute T.ATT successive times to change the tape block size and also the tape length. If you do not specify BLKSIZE, T.ATT uses the default tape block size specified in SETTAPE.Only one process can attach a tape unit at any time. You can attach more than one tape unit to a single process, but you cannot attach the same tape unit to more than one process.You can use the ECL T.STATUS command to list all defined tape units, and see which ones are attached and which are available. The following screen shows sample output from T.STATUS:

:T.STATUS UNIT STATUS UDTNO USER CHANNEL ASSIGNED NUMBER NAME NAME BLOCKSIZE 0 ASSIGNED 103 USER01 \\.\TAPE0 16384 1 ASSIGNED 121 Administrator A:\TAPEFILE 4096 2 ASSIGNED 128 terric \USERS\DEFAULT\TAPE 1638\4:

Notice that the “tape devices” for tape units 1 and 2 are actually disk files. A:\TAPEFILE is a FAT file, while \USERS\DEFAULT\TAPEFILE is a NTFS file. When using a disk file as a tape device the functionality is naturally limited to simple loads and unloads, but this may be useful for demonstration or testing.

Warning: Do not specify a disk drive (for instance, A:) as a tape device. SETTAPE may succeed, but you will be unable to write to the disk drive. If you wish to dump files to disk, create disk files and then specify the disk files as tape devices.


3. Read From, or Write To, the Tape DeviceWhen a tape unit is attached, you can access it from ECL or within a UniBasic program. The following example shows some typical outputs when a process with tape unit 1 attached executes the ECL T.DUMP command:

:T.STATUS UNIT STATUS UDTNO USER CHANNEL ASSIGNED NUMBER NAME NAME BLOCKSIZE 0 AVAILABLE 1 ASSIGNED 128 terric A:\TAPEFILE 16384 2 AVAILABLE:SELECT VOC WITH F1=PA 7 records selected to list 0. >T.DUMP VOC MU 02Unit 2 not attached yet.>T.DUMP VOC MU 4Unit 0 not attached yet.>T.DUMP VOC MU 017 record(s) dumped to tape:

Notice the following points about the example:

You cannot write to a tape device unless it is attached with T.ATT. If you have attached more than one device, you must specify the device to write to or read from. If you have attached only one device, UniData accesses the device you attached.With T.DUMP, you can write from an active select list.If you supply a single-digit value (for instance, 4) UniData interprets the digit as the conversion code, and attempts to attach the default device (unit 0).

Note: When you access a tape device, the operation fails if the device is not properly connected or if the device does not have a tape mounted. The UniData T.ATT and SETTAPE commands do not detect device configuration problems, so you may be able to define and attach a device, but be unable to complete your access to it.

Steps for Tape Device Use 16-8

4. Release the Tape DeviceWhen you have finished using a tape device, use the T.DET command to release the device so that another UniData process can use it. If you have attached more than one device, you must release each one separately. If you have attached only one, the T.DET command releases the one you have attached. You can execute T.DET from ECL or from within a UniBasic program.


17Chapter

CallC and CallBasic

Dynamic Link Libraries (DLLs) and UniData. . . . . . . . . . 17-3Calling External Routines From UniData . . . . . . . . . . . 17-4 Requirements for CALLC . . . . . . . . . . . . . . 17-4 Steps for CALLC . . . . . . . . . . . . . . . . . 17-4 CALLC and UDT.OPTIONS 88 . . . . . . . . . . . . 17-5 CALLC Syntax and Data Types. . . . . . . . . . . . . 17-6 E Type VOC Entries . . . . . . . . . . . . . . . . 17-7 Examples . . . . . . . . . . . . . . . . . . . . 17-9CALLC Example Programs . . . . . . . . . . . . . . . 17-10 C Example . . . . . . . . . . . . . . . . . . . 17-11 C++ Example . . . . . . . . . . . . . . . . . . 17-15 Pascal Style Example . . . . . . . . . . . . . . . . 17-19Accessing UniData From an External Program . . . . . . . . . 17-22 How CallBasic Works . . . . . . . . . . . . . . . . 17-22 Examples . . . . . . . . . . . . . . . . . . . . 17-23 C Program Example . . . . . . . . . . . . . . . . 17-25 UniBasic Subroutine Example . . . . . . . . . . . . . 17-29Steps for CallBasic . . . . . . . . . . . . . . . . . . 17-31

CALLC and CallBasicUniData provides the UniBasic CALLC command for executing functions written in C, C++, or Delphi from UniData, and the CallBasic API for executing UniBasic subroutines from external programs. This chapter describes commands and proce-dures for using these tools.

Note: See the UniBasic Commands Reference for more information about the syntax and use of the CALLC command.


Dynamic Link Libraries (DLLs) and UniDataBoth the CALLC implementation and the CallBasic implementation in UniData for Windows Platforms use the Microsoft Windows Dynamic Link Library (DLL) facility. This facility allows separate pieces of code to call one another without being permanently bound together. Linking between the separate pieces is accomplished at runtime (rather than compile time) through a Dynamic Link Library (DLL) interface. Both the CALLC interface (for calling external functions from UniData) and the CallBasic interface (calling UniData functions from external code) are implemented as DLLs.

For CALLC, developers create a DLL and then call that DLL from UniData. Special VOC entries for each function called from a DLL communicate interface information to UniData. For CallBasic, developers link their code with UniData.LIB (located in the UniData bin directory) and then make calls into the UniData DLL. The .LIB file supplies interface information.

Because linking between caller and DLL is accomplished at runtime, either the caller or the DLL can be modified independently. For UniData, this means that you can upgrade your UniData version without the need to relink with external routines, and you can update your external DLL without the need to relink UniData.

A DLL is language independent. Many software development environments for Windows can produce a DLL.

Note: Consult the documentation for your software development environment for information about linking code into a DLL.

Dynamic Link Libraries (DLLs) and UniData 17-3

Calling External Routines From UniDataMany applications use functions written in high-level languages like C++ for purposes such as environment definition, security, or low-level data transfers (similar to the UniBasic GET and SEND functions). Through the CALLC command, UniData enables you to access such functions from within a UniBasic application using CALLC commands.

Note: When you use CALLC, your functions are executed by a udt process. They are not visible to the end user at all.

Requirements for CALLCIf you want to use CALLC to access functions in an external DLL you need a full software development kit for the language you are using. (A base compiler may not be sufficient).

Tip: Refer to your host operating system documentation and your hardware vendor if you have questions about your development environment.

Steps for CALLCTo use CALLC, complete the following steps:

1. Code the Function Code the external program using C, C++, or Borland Delphi. Make certain that all the functions to be called from outside the program are exported in one of the following ways:

A _declspec( dllexport ) statement.An EXPORTS statement. The EXPORTS statement lists the names and optionally the ordinal values of the functions exported by the DLL. When you specify ordinal values, they must be in the range 1 through n, where n is the number of functions exported by the DLL.

See “Examples” on page 17-8 for information about exporting functions.2. Compile and Link

Compile the function or functions and link the code into a DLL.


Warning: UniData for Windows Platforms takes full advantage of the Win32 environment. The UniData DLL is a 32-bit DLL, and any DLLs you call via CALLC must also be 32-bit DLLs. You cannot call a 16-bit DLL from UniData.

3. Create VOC EntryCreate a VOC entry for every function that you can call from the DLL. You must create an E type record in the VOC file in every UniData account where you will be calling the functions. The VOC entry contains informa-tion that enables UniData to locate and execute the called function.

The following sections provide additional detail about the CALLC implementation on UniData for Windows Platforms.

CALLC and UDT.OPTIONS 88There are two ways one function can call another in a stack-based architecture:

Pascal calling convention _cdecl calling convention

The Pascal style calling convention is the default for UniData.

Note: For C and C++, the default calling convention is _cdecl. For Delphi, the default calling convention is Pascal. You can use the Pascal convention in C or C++, and you can use the _cdecl convention in Delphi; consult the documentation for your development environment for information about choosing a calling convention.

UDT.OPTIONS 88 allows CALLC to function correctly with both _cdecl and Pascal style calling conventions. The following table describes the behavior of CALLC commands with this option turned on or off:

UDT.OPTIONS 88 _cdecl Convention Pascal Convention

OFF (default) CALLC fails, terminating the UDT

CALLC executes.

ON CALLC executes CALLC fails, terminating the udt.

UDT.OPTIONS 88

Calling External Routines From UniData 17-5

Warning: As the preceding table indicates, calling a function with the wrong UDT.OPTIONS 88 setting almost certainly terminates a udt session and may produce other undesirable results.

CALLC Syntax and Data TypesThe UniBasic CALLC command has the following syntax:

rtn = CALLC function(arg1,arg2,...argn)


Valid data types for return values and arguments are listed in the following table.


rtn Return value from CALLC. Must be a valid data type.

function The name of the external function being called.

arg1,....argn Arguments to the external function. Each must be a valid data type.

CALLC Parameters

Data Type Description

CHAR Signed byte.

INT Integer (32-bit signed).

POINTER 32-bit signed long word.

SHORT Short (16-bit) integer.

LONG Long integer.

STRING Pointer to a null-terminated character string in a 34K buffer.

CHAR_PTR Pointer to a null-terminated character string.

INT_PTR Pointer to a 32-bit signed long word.

SHORT_PTR Pointer to a 16-bit integer.

LONG_PTR Pointer to a 32-bit integer.

Data Types for CALLC


E Type VOC EntriesAn E (executable) type VOC entry identifies the DLL for an external function being called using CALLC, and identifies the data types for its arguments and return value.

Tip: On UniData for UNIX, this information is stored in the cfuncdef_user file.

The following table defines the attributes required for an E type VOC entry.

DOUBLE Double.

DOUBLE_PTR Pointer to a double.

BSTRING Pointer to a binary string descriptor.

NONE Use for functions that do not return anything (for instance, VOID).

Attribute Description

@ID Function name.

Attribute 1 VOC entry type; must be E.

Attribute 2 Location of DLL. Must be a fully qualified path, a path relative to the current working directory, or a name that can be located through the user’s Path environment variable.

Attribute 3 Function name in the DLL.

Attribute 4 Data type for return value.

Attribute 5 Data type for first argument.

Attributes 6 - n Data types for second through nth arguments.

Attributes of E Type VOC Entry

Data Type Description

Data Types for CALLC (continued)

Calling External Routines From UniData 17-7

The following screen shows the VOC entry for a function named callcpp_subr1:

:CT VOC callcpp_subr1VOC: callcpp_subr1:ECALLC_DEMO\CALLC_CPP\callcpp_test.dllcallcpp_subr1INTINTSHORTLONGCHARSTRINGPOINTER:

Notice that this subroutine expects six arguments, and returns an INT. The subroutine is accessed from a dynamic linked library called callcpp_test.dll.

Warning: IBM recommends that you keep your development environment clearly separate from your production environment when developing a CALLC application. Separating environments is useful in any case, but can be critical because difficulties in the external functions can terminate udt sessions and potentially damage data.

ExamplesAt this release, UniData includes examples that demonstrate the components of CALLC for each of three supported languages: C, C++, and Delphi. Each example includes a subdirectory that contains the source code, make file, and DLL for the external routines. Each example also includes a UniBasic program that calls a function or functions from its DLL. The following section describes the CALLC examples.


CALLC Example ProgramsThe subdirectories for the three CALLC examples are all included in the CALLC_DEMO folder, which is in the demo folder in your UniData directory. The following window shows the structure of CALLC_DEMO:

Note: The example components (particularly the UniBasic programs) are greatly oversimplified. They are meant to illustrate the relationships between components in the CALLC implementation, not to illustrate particular coding techniques.

CALLC Example Programs 17-9

C ExampleThe C example contains the components shown on the following window:

The example also includes the UniBasic program EXAMPLE_C, in the BP file in the demo account.

Notice that, in the C example, a single program source file was compiled and linked to form the DLL. One function, called ps, can be called from the DLL. The function accepts a process ID, opens the Registry, and collects information about that process. The information is returned to the UniBasic program that called the ps function.


The next example shows a portion of the source code in psdll.c:

.

.

.#define DllExport _declspec( dllexport )#define DllImport _declspec( dllexport )...struct _TIME_FIELD { INT Hours; INT Mins; INT Secs; INT mSecs; }; DllExport int ps( int processid, char *process_name, char *process_creator, cha\r *processor_time, int *vmemory ){ HANDLE hProcess, hProc\essToken;...


The program was written using the _cdeclspec statement to export a function. (See the two lines that begin #define and the line that begins DllExport int ps). The DllExport specifies that a function called ps can be called from the DLL, and defines the arguments for the ps function.


The next example shows the VOC entry for the ps function:

:CT VOC psVOC: ps:ECALLC_DEMO\CALLC_C\psdll.dllpsINTINTSTRINGSTRINGSTRINGINT_PTR:

The following example is a portion of the sample UniBasic program that calls the ps function:

.

.

.PRINT "TURNING ON UDT.OPTIONS 88; REQUIRED FOR C"PERFORM "UDT.OPTIONS 88 ON" PRINT "THE ID OF MY CURRENT UNIDATA PROCESS IS: ":@USERNOPRINT "PASSING THE ID TO THE C ROUTINE."pid = @USERNOpname = ‘’cname = ‘’ptime = ‘’virt_mem = 0 RESULT = CALLC ps(pid, pname, cname, ptime, virt_mem)PRINT "THE C ROUTINE RETURNED: ":RESULTIF RESULT >= 0 THEN PRINT...END ELSEPRINT "AN ERROR HAS OCCURRED IN THE C ROUTINE."ENDPRINT "TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING"PERFORM "UDT.OPTIONS 88 OFF" STOPEND



The function name in the CALLC statement matches the name in the E type VOC entry.By default, the calling convention for a C program is the _cdecl convention. Therefore, UDT.OPTIONS 88 must be turned on.Error handling is based on the RESULT from the C function rather than the STATUS of the CALLC statement. The statement can complete success-fully (STATUS of 0) even if the C function has encountered an error.

The next example shows output from the sample program:

:RUN BP_SOURCE EXAMPLE_CTHIS UNIBASIC PROGRAM CALLS A C ROUTINE AND THEN DISPLAYS OUTPUT TO THE SCREEN.TURNING ON UDT.OPTIONS 88; REQUIRED FOR CTHE ID OF MY CURRENT UNIDATA PROCESS IS: 149PASSING THE ID TO THE C ROUTINE.THE C ROUTINE RETURNED: 1 PID COMD CREATOR PROCESSOR TIME VIRTUAL MEMORY-------------------------------------------------------------------149 udt.exe terric 00:00:04.1687 32366592 TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING:


C++ ExampleThe following screen shows the components of the C++ example:

In this example, three functions are compiled and linked into a single DLL. The file callcpp.def lists the functions that can be called from the DLL:

LIBRARY callcpp_test DESCRIPTION 'For CALLC test on .cpp files' EXPORTS callcpp_subr1 @1 callcpp_subr2 @2 callcpp_subr3 @3

Tip: The example was developed using Visual C++. Consult the documentation for your development environment for information about file naming conventions and procedures for creating a DLL.



The EXPORTS statement is used to export the three functions that can be called from the DLL.The names of the functions you can call do not need to match the names of the source files, provided they are correctly defined.

The UniBasic program EXAMPLE_CPP calls one of the three functions from callcpp_test.dll. A segment of this program is shown in the next example:

.

.

.PRINT "TURNING ON UDT.OPTIONS 88 FIRST; NEEDED FOR C++"EXECUTE "UDT.OPTIONS 88 ON"RESULT = CALLC callcpp_subr3(int,short,long,char,string,filename)PRINT "THE SUBROUTINE RETURNED: ":RESULT...PRINT "TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING"EXECUTE "UDT.OPTIONS 88 OFF"STOPEND


Because the default calling convention for C++ is the _cdecl convention, UDT.OPTIONS 88 must be turned on.The program prints the value returned by the function (a value of 0 or greater is successful) rather than the STATUS of the CALLC command. The CALLC command can complete successfully, returning a STATUS of 0, even if a problem occurred in the C++ function.The name of the function in the CALLC command must match the name in the E type VOC entry, which also matches the name in the callcpp.def file.


Notice that the program calls a single function (callcpp_subr3) from the DLL. The next screen shows the VOC entry for callcpp_subr3:

:CT VOC callcpp_subr3VOC: callcpp_subr3:ECALLC_DEMO\CALLC_CPP\callcpp_test.dllcallcpp_subr3INTINTSHORTLONGCHARSTRINGSTRING:

Tip: You can link a number of external functions into a single DLL, if this makes sense from an application point of view. Each function has its own VOC entry. You can then access one or several functions in the same UniBasic program through CALLC statements.

The following screen shows a portion of the program source for callcpp_subr3:

/* * Function: Calls several Win32 API’s to print out the values of * received parameters to a output file. */ intcallcpp_subr3(int arg_int,short arg_short,long arg_long, char arg_char,char *arg_string,char *fname){ HANDLE hOutputFile; DWORD dwStringLen, dwByteWritten; char Buf[256],WriteBuf[10*256];


The next screen shows output from the sample UniBasic program:

:RUN BP_SOURCE EXAMPLE_CPPTHIS UNIBASIC PROGRAM PASSES A GROUP OF ARGUMENTS TO A C++ ROUTINE, WHICH WRITES THE VALUES TO AN OUTPUT FILE.TURNING ON UDT.OPTIONS 88 FIRST; NEEDED FOR C++HERE ARE THE INPUT ARGUMENTS FOR THE ROUTINE.THE int ARGUMENT IS: -1.347THE short ARGUMENT IS: -12345678THE long ARGUMENT IS: 3THE char ARGUMENT IS: 1THE string ARGUMENT IS: 12345RESULTS ARE WRITTEN TO THE OUTPUT FILE NAMED: outfileTHE SUBROUTINE RETURNED: 0EXECUTION COMPLETE.THESE ARE THE RESULTS FROM THE OUTPUT FILE.value of int argument : -1value of short argument : -24910value of long argument : 3value of char argument : 1value of string argument: 12345TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING:

Notice that, in the output, the C++ function has returned the correct values based on the input arguments and data types.


Pascal Style ExampleThe following screen shows the components of the Pascal style example:

Tip: The example was developed using Borland Delphi Developer Version 2.0. Consult the documentation for your development environment for information about naming conventions and requirements for creating a DLL using Delphi.


In this example, there is a single program source file called calldelphi.dpr. A segment of this file follows:

.

.

.{ This function returns the larger number of the two input intergers }function Pascal_subr2(X, Y: Integer): Integer; stdcall; begin if X > Y then Pascal_subr2 := X else Pascal_subr2 := Y; end; exports Pascal_subr1 index 1, Pascal_subr2 index 2; begin end. ...

Notice that two Pascal functions are defined within the source file. The exports state-ments allow both functions to be called from the DLL. The sample UniBasic program EXAMPLE_DELPHI calls Pascal_subr2, as shown in the following program segment:

.

.

.LOOP WHILE I < 6 DO ret = CALLC Pascal_subr2(NUM1,NUM2) PRINT “THE FIRST NUMBER IS: ":NUM1:" AND THE SECOND NUMBER IS: ":NUM2 PRINT "THE BIGGER ONE IS:":ret NUM1-=473 NUM2+=473 I+=1REPEAT...


The next screen shows the output from the sample UniBasic program:

:RUN BP_SOURCE EXAMPLE_DELPHITHIS UNIBASIC PROGRAM CALLS A DELPHI (PASCAL-STYLE) ROUTINE THAT COMPARES TWO NUMBERS AND REPORTS THE LARGER ONE.TURNING OFF UDT.OPTIONS 88; REQUIRED FOR PASCAL STYLESTARTING WITH TWO NUMBERS; CALLING THE SUBROUTINE AND REPORTING THE RESULT, THEN CHANGING THE NUMBERS.THE FIRST NUMBER IS: 5000 AND THE SECOND NUMBER IS: 4000THE BIGGER ONE IS:5000THE FIRST NUMBER IS: 4527 AND THE SECOND NUMBER IS: 4473THE BIGGER ONE IS:4527THE FIRST NUMBER IS: 4054 AND THE SECOND NUMBER IS: 4946THE BIGGER ONE IS:4946THE FIRST NUMBER IS: 3581 AND THE SECOND NUMBER IS: 5419THE BIGGER ONE IS:5419THE FIRST NUMBER IS: 3108 AND THE SECOND NUMBER IS: 5892THE BIGGER ONE IS:5892THE FIRST NUMBER IS: 2635 AND THE SECOND NUMBER IS: 6365THE BIGGER ONE IS:6365:


Because the default calling convention for Delphi is the Pascal convention, UDT.OPTIONS 88 must be turned off before the CALLC statement.In this example, the return from the function is the larger of the two numbers passed as arguments. There is no particular error handling.


Accessing UniData From an External ProgramThe CallBasic application programming interface (API) enables you to access a UniData database by calling UniBasic subroutines from an external program written in C or other high-level languages. The CallBasic API is particularly useful for appli-cations like automated processes that gather data and then write the data into a UniData database. The main body of the application may be written in another language, and the application uses a UniBasic subroutine, called through CallBasic, to write the data into UniData hashed files in correct format.

Note: When you use CallBasic, your UniBasic routines are called from an external program. UniBasic and UniData are invisible to the users of the external program.

RequirementsThe components required to use the CallBasic API are:

Development environment—Your system should have a full software devel-opment kit for the language you are using. (A base compiler is not sufficient).

Tip: Consult your host operating system documentation and your hardware vendor if you have questions about your development environment.

Application programs—You must code and compile the application that will call UniBasic. Since you will be calling into the UniData DLL, you must link your code with UniData.LIB.Cataloged UniBasic subroutines—You must code, compile, and globally catalog your UniBasic subroutines.

How CallBasic WorksThe CallBasic API includes four functions:

udtcallbasic_init( )—This function initializes UniData and CallBasic. It serves the purpose of opening a “UniData session” for your application. Your program must execute this function once and only once.

Accessing UniData From an External Program 17-21

U_callbas( )—This function calls a UniBasic subroutine, passing arguments, and returns the address of the buffer containing the results. You may execute this function numerous times in your application, each time you want to call a UniBasic subroutine. The syntax for U_callbas is supported if the calling language is C.udtcallbasic( )—This function calls a UniBasic subroutine, passing arguments, and returns a pointer to the results. The syntax of this function is required if the calling language is not C, because the definition of the return buffer is consistent between the external program and the call with udtcall-basic. The user is responsible for allocating memory for the buffer to store results. You may execute this function numerous times in your application when you want to call a UniBasic subroutine.udtcallbasic_done( )—This function clears all UniData-related temporary files and other resources, and ends the interface between the application and UniData. You must execute this function once in your application. You must also include this function in any error exits in your application that may be taken after udtcallbasic_init.

Note: See Developing UniBasic Applications for a detailed description of the CallBasic functions and their requirements.

ExamplesAt this release, UniData supplies two simple examples that illustrate the CallBasic functionality.

Callbasic Example 1

This example consists of a C routine that calls a UniBasic subroutine to display two arguments. The C routine (which also includes C++ syntax for function declarations) is located in the CALLBASIC_DEMO subdirectory of the UniData demo account, in the EXAMPLE1 folder. The UniBasic subroutine is located in the BP file of the UniData demo account.

The following sections of this chapter use the C routine and UniBasic subroutine from this example.


Callbasic Example 2

This example consists of a Windows application written in Visual C++ that allows users to add, update, find, or delete records from a small UniData hashed file. The C++ program accesses the UniData file with CallBasic. The components of this example are in the BP file and in the subdirectory CALLBASIC_DEMO (EXAMPLE2 folder), both in the UniData demo account.

Warning: Do not execute the second example from a Telnet session; the example is a Windows application. Also, note that the examples only illustrate the relationship between components of CallBasic. They are not intended to demonstrate optimum coding technique.


Sample Programs

C Program ExampleThe following C program, called callbasic_example1.c, is an extremely simplified example that illustrates the components required for CallBasic:

#include <stdio.h> #define NT #ifdef NT#include <windows.h>#endif /* NT */ /* Declare UniData callbasic functions */ #ifdef CPP /* for c++ */extern "C" int udtcallbasic_init(int i, int j);extern "C" int udtcallbasic(char *xbuf, char *ybuf, int i, char *arg, ...);extern "C" int udtcallbasic_done(int k);extern "C" int U_callbas(char **xbuf, char *ybuf, int i, char **zbuf);#else /* for c */extern int udtcallbasic_init();extern int udtcallbasic_done();extern int U_callbas();#endif /* CPP */ #ifdef NTextern int udtcallbasic();#endif /* NT */ void main(){ /* Declare variables */ char *rtn; char arg0[BUFSIZ]; char arg1[BUFSIZ]; char *args[2]; int sts; /* Initialize the UniData environment */ udtcallbasic_init(0,0); /* Assign arguments for the UniBasic routine */ strcpy(arg0, "Plants"); strcpy(arg1, "Animals"); args[0] = arg0; args[1] = arg1; printf(“Executing UniBasic subroutine using U_callbas()...\n"); /* Call the UniBasic routine */ sts = U_callbas(&rtn, "EXAMPLE", 2, args);


if (sts == 0){ printf("Return value from UniBasic subroutine is %s\n", rtn);#ifdef NT /* Variable rtn returned by UniData come from the process heap, not the C-Runtime heap. It cannot be free'd with free(). They must be free’d with HeapFree(). */ HeapFree(GetProcessHeap(), 0, rtn);#else free(rtn);#endif /* NT */ #ifdef NT /* Allocate memory for return variable */ rtn = (char *)malloc(256); printf("\nExecuting UniBasic subroutine using udtcallbasic()...\n"); /* Call the UniBasic subroutine using udtcallbasic. */ sts = udtcallbasic(rtn, "EXAMPLE", 2, args[0], args[1]); if (sts == 0){ printf("Return value from UniBasic subroutine is %s\n", rtn); } /* Free memory */ free(rtn);#endif /* NT */ } /* Close everything properly */ udtcallbasic_done(sts);}

Notice the following points about callbasic_example1.c:

C and C++ Syntax

The example shows the correct syntax for declaring the UniBasic functions in both C++ (#ifdef CPP) and C.

Header Files

You must include stdio.h and windows.h.


Initializing CallBasic

This statement initializes CallBasic, effectively starting a udt session for your C program:

udtcallbasic_init(0, 0);

Notice that it is executed once and only once in the C program.

Warning: If you initialize CallBasic more than one time or you do not initialize at all, you will encounter errors and your program may fail with an exception.

Calling a UniBasic Subroutine: U_callbas

In this statement, we call the subroutine and assign the return to a variable.

char *rtn;.../* Call the subroutine */sts = U_callbas(&rtn, "EXAMPLE", 2, args);

Notice the definition of rtn in the program (character pointer) and the usage of rtn in the U_callbas statement (address). The difference between definition and usage is because, when you use U_callbas, the system allocates memory for the return variable. Passing the address of rtn allows U_callbas to pass back the address of the allocated memory.

Remember you can call more than one UniBasic subroutine, using the U_callbas function, as long as you do so between initializing and closing CallBasic.


Freeing Memory

Each U_callbas execution allocates memory; you must free the memory after conclusion of the subroutine. If you do not free the memory, your application is said to have a “memory leak” which can cause significant performance degradation over time. On Windows platforms, variables returned by UniData are allocated from the process heap rather than from the C-Runtime heap. Because of this, you must use the HeapFree API, rather than the free( ) function, to free the memory allocated by UniData, as shown below:

if (sts == 0){printf("Return value from UniBasic subroutine is %s\n",rtn);/* Variable rtn returned by UniData comefrom the process heap, not the C-Runtimeheap. It cannot be free'd with free().They must be free’d with HeapFree().*/HeapFree(GetProcessHeap(), 0, rtn);

Notice that you need to free the memory if the function completes successfully; UniData frees the memory if the function fails.

Calling a UniBasic Subroutine: udtcallbasic

The following program segment allocates memory for the return variable, then calls the subroutine:

/* Allocate memory for return variable */rtn = (char *)malloc(256);printf("\nExecuting UniBasic subroutine using udtcallbasic()...\n");/* Call the UniBasic subroutine using udtcallbasic. */sts = udtcallbasic(rtn, "EXAMPLE", 2, args[0], args[1]); if (sts == 0){ printf("Return value from UniBasic subroutine is %s\n", rtn); }/* Free memory */free(rtn);

When you use the udtcallbasic function, your calling process is responsible for allocating and freeing the memory for the return variables. If your process fails to free the memory, your application is said to have a “memory leak”, which can cause significant performance degradation over time.


Freeing Memory

When your process allocates the memory for the return variable, you can use free( ) to free it. Notice that the program segment illustrates this technique as well:

/* Allocate memory for return variable */rtn = (char *)malloc(256);printf("\nExecuting UniBasic subroutine using udtcallbasic()...\n");/* Call the UniBasic subroutine using udtcallbasic. */sts = udtcallbasic(rtn, “EXAMPLE”, 2, args[0], args[1]);if (sts == 0){printf("Return value from UniBasic subroutine is %s\n", rtn); }/* Free memory */free(rtn);

Ending CallBasic

The last step in the C program is:

/* Close everything properly */udtcallbasic_done(sts);

Remember that this function closes the UniData session for the C program, closing all UniData temporary files and releasing all resources held by UniData for this C program.

Warning: If you do not exit UniData cleanly, you may lose consistency of data, and you may damage files.

UniBasic Subroutine ExampleThe following UniBasic subroutine, called EXAMPLE, is a very simplified routine showing the requirements for CallBasic.

SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)PRINT "THE FIRST ARG IS ":ARG1PRINT "THE SECOND ARG IS ":ARG2RETNVAL="RETURN"RETURNEND

Notice the following points about the UniBasic subroutine.


Arguments

The arguments for the UniBasic subroutine match what is sent from the C program. Here is the U_callbas call to the subroutine:

sts = U_callbas(&rtn, “EXAMPLE”, 2, args);

Here’s the udtcallbasic call to the subroutine:

sts = udtcallbasic(rtn, “EXAMPLE”, 2, args[0], args[1]);

And here’s the first line of the subroutine:

SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)

Additional Information

The UniBasic subroutine must be created, compiled, and cataloged in a UniData account. The routine may be globally, directly, or locally cataloged. However, if you catalog the routine directly or locally, you must execute the C program from the UniData account where the subroutine is cataloged. Regardless how you catalog the UniBasic subroutine, you must execute the C program from a valid UniData account.


Steps for CallBasicComplete the following steps to access UniData from an external program with CallBasic.

Warning: IBM recommends that you keep your development environment clearly separate from your production environment when developing a CallBasic application. Separating environments is useful in any case, but can be critical because difficulties in the external programs can terminate udt sessions and potentially damage data.

1. Code and Compile the Application ProgramRefer to the documentation for your application development environment for infor-mation about compiling the external program. Make sure that:

Your declarations for the UniBasic functions use the correct syntax for your programming language. You link your code with the UniData.LIB file. The UniData.LIB file is located in the UniData bin directory.

The following segment from the makefile for callbasic_example1.c shows linking with the UniData.LIB file:

LINK32=link.exe# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib a\dvapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib\ /nologo /subsystem:console /machine:I386# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi\32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib c:\u\nidata\bin\unidata.lib /nologo /subsystem:console /machine:I386LINK32_FLAGS=kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib\ advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib\ odbccp32.lib c:\unidata\bin\unidata.lib /nologo /subsystem:console\ /incremental:no /pdb:”$(OUTDIR)/callbasic_example1.pdb” /machine:I386\ /out:”$(OUTDIR)/callbasic_example1.exe”:


Note: See the “C Program Example” on page 17-24 for a listing of callbasic_example1.c. The sample program and makefile are also in the CALLBASIC_DEMO folder in your UniData demo account.

2. Code, Compile, and Catalog the UniBasic SubroutineRemember that you can catalog the UniBasic subroutine globally, locally, or directly. The following example shows compiling and directly cataloging the sample subroutine EXAMPLE in the UniData demo account:

:AE BP EXAMPLETop of "EXAMPLE" in “BP”, 7 lines, 136 characters.*--: P 001: SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)^M002: PRINT "THE FIRST ARG IS ":ARG1^M003: PRINT "THE SECOND ARG IS ":ARG2^M004: RETNVAL="RETURN"^M005: RETURN^M006: END^M007: ^MBottom.*--: FIBC Filed "EXAMPLE" in file "B" unchanged. Compiling Unibasic: BP\EXAMPLE in mode 'u'.compilation finishedIn D:\UniData\sys\CTLG\a\AE at line 995 EXAMPLE has been cataloged, do you want\ to overwrite(y/n)? Y:

Note: Before proceeding further, be sure that both your C program and your UniBasic subroutine are thoroughly tested.

3. Use the New ExecutableTo run the new executable and call the UniBasic subroutine, your working directory must be a UniData account where the subroutine is cataloged. You can execute your routine from the operating system prompt, and you must specify the full path of the executable, or include its location in your PATH environment variable. The following window shows the results of executing the callbasic_example1 executable from the demo directory:

Steps for CallBasic 17-31

Note: If your UniBasic subroutine is globally cataloged, you can use CallBasic from any UniData account. You do not need to be in the UniData account where the subroutine was written.


18Chapter

Monitoring and Tuning UniData

Monitoring Your Windows System . . . . . . . . . . . . . 18-3UniData Performance Factors . . . . . . . . . . . . . . . 18-4 Database Design Considerations . . . . . . . . . . . . 18-4 Using Alternate Key Indexes . . . . . . . . . . . . . 18-4 Sizing Static Hashed Files . . . . . . . . . . . . . . 18-4 Sizing Dynamic Hashed Files . . . . . . . . . . . . . 18-5 UniBasic Coding Tips . . . . . . . . . . . . . . . . 18-5UniBasic Profiling . . . . . . . . . . . . . . . . . . 18-8UniData Performance Monitoring . . . . . . . . . . . . . 18-12 UniData Dynamic Array Statistics . . . . . . . . . . . . 18-14 UniData File I/O Statistics . . . . . . . . . . . . . . 18-16 UniData Index Statistics . . . . . . . . . . . . . . . 18-18 UniData Lock Statistics . . . . . . . . . . . . . . . 18-21 UniData Program Control Statistics . . . . . . . . . . . 18-23ECL Process Monitoring Commands . . . . . . . . . . . . 18-25Examples . . . . . . . . . . . . . . . . . . . . . 18-28

This chapter outlines considerations that can affect UniData performance on your Windows platform and describes UniData-specific procedures for monitoring performance.


Monitoring Your Windows SystemThe Performance Monitor provides great flexibility for monitoring the behavior of your Windows system. From the Start menu, click Control Panel, then double-click Administrative Tools, and then click Performance.

Note: A description of the Microsoft Performance Monitor is outside the scope of UniData documentation. Refer to your operating system documentation for information about how to use the Performance Monitor.

IBM recommends you monitor your system performance regularly to develop baseline expectations throughout your processing cycle. The performance history of your system provides information you can use to implement new procedures (such as scheduling certain jobs to run off-hours or purchasing more resources), as well as to identify problems quickly to minimize downtime.

Tip: You can select an individual udt session and monitor detailed information about its use of system resources, in addition to monitoring UniData as a whole.

Monitoring Your Windows System 18-3

UniData Performance FactorsWithin UniData applications, the major performance factors are: database design, file sizing, and program coding efficiency.

Database Design ConsiderationsStructure your database so records do not exceed a size limit of 4K bytes. When possible, avoid long, multivalued, variable-length records. Locate the most frequently accessed attributes near the beginning of a record.As far as possible, keep key lengths numeric and small in length.

Using Alternate Key IndexesUsing alternate key indexes speeds query access in a hashed file, but can slow down updates. Consider this factor when creating indexes. The more indexes created for a file, the longer an update takes.

Index overflows occur when the maximum length value is too small for the fields being indexed. Index overflows can degrade performance for query as well as update access. The solution for index overflows is to delete all the indexes for a file and rebuild them with a longer maximum length value.

Tip: Use the UniData LIST.INDEX tool to identify index overflow problems. Consider running LIST.INDEX periodically. See Using UniData for information about alternate key indexes.

Sizing Static Hashed Files Performance loss results if UniData hashed files are allowed to overflow. Level 2 overflow, which occurs when primary keys outgrow a block, has a particularly serious performance impact. Level 1 overflow, which occurs when data overflows a block, eventually affects performance as well.

For information about file sizing commands, see the UniData Commands Reference.


Sizing Dynamic Hashed FilesDynamic hashed files differ from static hashed files in that they split and merge with respect to a minimum modulo. Splitting prevents level 2 overflow conditions, because a group splits whenever the percentage occupied by keys exceeds a preset value. Merging supports efficient access to the file, because maintaining the file at a low modulo makes searches faster. For information about dynamic file sizing commands, see the UniData Commands Reference.

UniBasic Coding TipsThe efficiency of your UniBasic application has a significant impact on UniData performance. Use the following guidelines when designing and coding.

Use Modular Programming

Use inserts and include files consistently.Open frequently-used files to COMMON to reduce physical file opens.

Use Efficient Commands

Use the EQUATE command where possible.Use CASE statements instead of IF, THEN, ELSE structure whenever possible. Avoid nested IF, THEN, ELSE.Use UniData @variables.Minimize new assignment of variables.Eliminate GOTO statements.Use GOSUB instead of external CALLs when appropriate; use CALL when multiple programs access the same code.When using CALLs:

Avoid opening files; pass through COMMON or an argument list.Minimize local variables in subroutines.Use inserts, COMMON, and argument lists whenever possible.

Use A += B instead of A = A + B.Use LOOP and REMOVE when extracting data sequentially from a string.

UniData Performance Factors 18-5

Avoid unnecessary shell commands; minimize PERFORM, EXECUTE, and MDPERFORM statements.Use CALL or CHAIN to run another UniBasic program.Avoid repeated ITYPE( ) function calls.Minimize use of EXECUTE “SELECT.....” by:

Using UniBasic SETINDEX, READFWD, READBCK.Using the UniBasic SELECT command.

Use Dynamic Arrays and Matrices Appropriately

Use dynamic arrays when you are accessing small strings and variables.Use matrices if you are handling a large number of attributes and multi-valued strings.

Use the Correct READ in Each Situation

Use READ when you are accessing small records, and the data you want is near the beginning of each record.Use READV if your intention is to get only one attribute.Use MATREAD when:

You are handling records with a large number of attributes, and you want to access more than one attribute.You are handling large multivalued lists.

Manage Locks Carefully

Use the LOCKED clause with a loop.Remember to release locks promptly.


UniBasic ProfilingUniData allows users to generate execution profiles that track call counts and execution times for UniBasic programs, internal subroutines, and program calls. You can use these profiles to identify sections of your UniBasic application that are called most frequently, and then focus optimization efforts in those areas.

Complete the following steps to create UniBasic execution profiles.

1. Compile the Programs with -GCompile UniBasic programs with the -G option to include information about internal subroutines in the profile reports.

2. Execute the Programs with -GTo profile a UniBasic program, run the program with the -G option. See Developing UniBasic Applications for information about compiling and running programs.

3. Review the Profile OutputUniData stores profile output in the NTFS directory where the UniBasic program was executed. Output files are called profile.pid and profile.elapse.pid where pid is the process ID (USRNBR in LISTUSER output) of the user’s UniData process.

UniBasic Profiling 18-7

The following example shows a portion of a profile report for a sample UniBasic program:

%time cumsecs seconds calls name 87.6 0.19 0.19 1215 BP\_TIME_TST:C 6.7 0.20 0.01 5 BP\_TIME_TST:A 3.3 0.21 0.01 60 BP\_TIME_TST:B 2.4 0.21 0.01 1 BP\_TIME_TST called/total parentsindex %time self descendents called+self name index called/total children <spontaneous>[1] 100.0 0.01 0.21 1 BP\_TIME_TST [1] 0.01 0.19 5/5 BP\_TIME_TST:A [2] ---------------------------------------------- 0.01 0.19 5/5 BP\_TIME_TST [1][2] 97.6 0.01 0.19 5 BP\_TIME_TST:A [2] 0.01 0.18 60/60 BP\_TIME_TST:B [3] 0.00 0.00 15/1215 BP\_TIME_TST:C [4] ---------------------------------------------- 0.01 0.18 60/60 BP\_TIME_TST:A [2][3] 89.8 0.01 0.18 60 BP\_TIME_TST:B [3] 0.18 0.00 1200/1215 BP\_TIME_TST:C [4] ---------------------------------------------- 0.18 0.00 1200/1215 BP\_TIME_TST:B [3] 0.00 0.00 15/1215 BP\_TIME_TST:A [2][4] 87.6 0.19 0.00 1215 BP\_TIME_TST:C [4] ----------------------------------------------

In this example, the main program is called TIME_TST. It has three internal functions, named A, B, and C.

Note: profile.pid reports execution times as CPU execution time, while profile.elapse.pid reports “real” time.


Each profile display includes two sections. The top section presents summary infor-mation, and the bottom section presents detail. The following table describes the fields in the top section of a UniBasic Profile display. There is one line for each function of the program.

UniData sorts program functions by execution time, and assigns an index to each function for ease of reporting. For each index, UniData computes information about functions that call, or are called by, the function corresponding to the index. The detail section of a profile contains this information, grouped by index. The next table describes the fields in the detail section.

Field Description

%time Percentage of the total run time of the program used by the function

cumsecs Running sum of seconds the function and those listed above it used within a cycle

seconds Number of seconds used by the function in a cycle

calls Number of times the function was invoked in a cycle

name Name of the function

UniBasic Profiling: Summary Information

Field Description

index Assigned by UniData. The indexes are assigned in descending order of execution time for the functions of the program. The index in column 1 identifies the routine of interest for the group of data (the current index function).

%time Reported for the current index function; percentage of the execution time used by the current index function and its descendents.

self Time spent by the function either calling, or being called by, the function identified by the current index.

descendents Time spent by the descendents of the function.

called For “parents” of the current index function, the number of times the function calls the current index function. For descendents of the current index function, the number of times the function is called by the current index function.

UniBasic Profiling: Detail Information

UniBasic Profiling 18-9

The following screen shows one group of data, selected from the sample UniBasic profile:

---------------------------------------------- 0.01 0.19 5/5 BP\_TIME_TST [1][2] 97.6 0.01 0.19 5 BP\_TIME_TST:A [2] 0.01 0.18 60/60 BP\_TIME_TST:B [3] 0.00 0.00 15/1215 BP\_TIME_TST:C [4] ----------------------------------------------

This subset of the report contains data relative to the internal function A, which is identified by index number 2. “Parent” functions, or functions which call A, are listed above it; “descendents”, or functions called by A, are listed beneath it.

In the example, the report indicates that 97.6% of the execution time for the entire program is used by A. The function is called 5 times, all by the main program, BP/TIME_TST. In turn, A is responsible for all 60 of the calls to B, and 15 of the 1,215 calls to C.

called+self Reported for the current index function; the number of times the function is called by others, plus the number of times the function calls itself recursively.

name Function name.

index Index value assigned to the function.

Field Description

UniBasic Profiling: Detail Information (continued)


UniData Performance MonitoringUniData performance monitoring is integrated with the Microsoft Performance Monitor to provide an easy interface and significant reporting flexibility to system administrators. Because you can monitor UniData-specific parameters and Windows systemwide parameters with the same tool, you can monitor combinations of param-eters simultaneously. This capability allows you to explore relationships between UniData processing and underlying system behavior. The Performance Monitor allows you to generate reports, logs, or a graphical display.

Note: Examples for this manual use a graphical display. Consult your operating system documentation for detailed information about all the output options for the Microsoft Performance Monitor.

The following sample window shows the appearance of the graphical display:

You can execute the Microsoft Performance Monitor in either of two ways:

From the Start menu, click Control Panel, then double-click Administrative Tools, and then double-click Performance.

UniData Performance Monitoring 18-11

From the Start menu, point to Programs, then point to IBM, then point to UniAdmin and then click UniAdmin. When you have connected to the desired host from UniAdmin, double-click Performance Monitor, then click UniData Monitor.

You can select output options from the Edit menu. UniData monitoring categories are included in the list of Objects for each view option. Click the Pre-defined Categories arrow for a list of UniData-specific objects you can monitor, as shown in the following example:

Select any of the UniData statistics by clicking its entry in the Pre-defined Category list. The following sections describe each group of UniData statistics.

Tip: The UniData Objects are listed in alphabetical order in the Object list, and the statistics you can monitor for each category are listed alphabetically in the Counter list for each object.


UniData Dynamic Array StatisticsIf you choose UniData Dynamic Array, a window similar to the following example appears:

Tip: You can scroll through the list of itms to see all values.

The Items are counts for executions of UniBasic commands described in the following table.

Field Description

COUNT Number of dynamic array counts, from COUNT command.

DELETE Number of dynamic array deletions, from DEL command.

EXTRACT Number of dynamic array data extractions, from EXTRACT command.

Dynamic Array Counters


FIELD Number of dynamic array string extractions, from FIELD command.

FIND Number of dynamic array finds, from FIND command.

INDEX Number of dynamic array substring indices, from INDEX command.

INSERT Number of dynamic array inserts, from INS command.

LOCATE Number of dynamic array locations, from LOCATE command.

MATCHFIELD Number of dynamic array substring matches, from MATCHFIELD command.

MATPARSE Number of dynamic array matrix parses, from MATPARSE command.

REMOVE Number of dynamic array element removals, from REMOVE command.

REPLACE Number of dynamic array replacements, from REPLACE command.

Field Description

Dynamic Array Counters (continued)


UniData File I/O StatisticsWhen you select UniData File I/O from the Object list, a window similar to the following appears:

Tip: You can scroll through the list of Items to see all values.


The following table describes the counters you can monitor for File I/O, and indicates considerations for performance.

Field Description

File Open Number of files at the operating system level. On Windows platforms, if the average value in this field is more then 5 (opens per second), performance may suffer.

File Close Number of file closes at the operating system level, from UniBasic CLOSE commands.

TempFile Close UniData temporarily closes the least-recently-accessed open file when requests for file opens exceed the limit of open files per process.

Record Read Number of records read by UniData commands (other than UniQuery).

Record Write Number of records written by UniData commands (other than UniQuery).

Record Delete Number of records deleted by UniBasic commands.

Level 1 Overflow Number of level 1 overflows. Compute the total activity by summing Record Read, Record Write, Record Delete. If Level 1 Overflow is more than 10 % of the total activity, use guide to analyze your files and resize them appropriately.

Level 2 Overflow Number of level 2 overflows. If Level 2 Overflow is more than 2% of total activity, use guide utility to identify files in level 2 overflow and resize them appropriately.

File I/O Counters


UniData Index StatisticsWhen you choose UniData Index Statistics from the Object List, you will see a window similar to the following example:



The following table describes the Counters you can monitor for UniData Index Statistics, and presents some tuning recommendations.

Field Description

Node Read Number of index node reads; a node is a component of the B+ tree structure, and a node is analogous to a block in a hashed file.

Node Write Number of index node write; a node is a component of the B+ tree structure, and a node is analogous to a block in a hashed file.

Node Merge Number of times two nodes merge; this takes place when entries in one or both nodes decrease.

Node Split Number of times an index node splits in two; this happens when entries in the original node increase. An unusual amount of split/merge/reuse activity idicates that one or more indexs are not properly sized. Use the ECL LIST.INDEX command to identify these, and then delete and rebuild them.

Node Reuse Number of times a node previously freed by a node merge is used for a node split.

Log Read Number of reads from an index log file. These occure when an index which was disabled is re-enabled and updated with the contents of the index log.

Log Write Number of writes to an index log file. Thease occure while an index is disabled, as UniData tracks changes by recording them in the index log.

Overflow Read Number of times UniData reads from an index overflow node. The system creates overflow nodes when the number of keys in an index node exceeds a set limit. The overflow condition is created when the alternate key length of the index is too small for the selected attribute. Reads to and writes from overflow nodes slow system performance.

Overflow Write Number of times UniData writes an overflow node. If overflow activity (reads and writes) exceeds 5% of system activity (Index Node Reads and Index Node Writes), use ECL LIST.INDEX command to identify which indexes are overflowed, and delete and rebuild them using a larger key length. (The default key length is 20 characters.

Index Counters


UniData Lock StatisticsWhen you choose UniData Lock Statistics from the Object List, you will see a window similar the following example:



The following table describes the Counters you can monitor for UniData Lock Statistics, and indicates performance considerations.

Note: In some circumstances, the output display may indicate that more records are being unlocked than are being locked. This is a function of how UniData gathers the statistics and does not indicate a problem.

Field Display

Record Lock Number of user-level record locks set by commands such as READL and READU.

Record Unlock Number of user-level locks released by commands such as RELEASE.

Semaphore Lock Number of user-level resource locks set by commands such as LOCK and T.ATT.

Semaphore Unlock Number of user-level resource locks released by commands such as T.DET or ULOCK.

Shared Group Lock Number of user-level resource locks released by commands such as T.DET or ULOCK.

Excl. Group Lock UniData-level exclusive lock on an entire group. For most appli-cations, the number of shared group locks exceeds the number of exclusive group locks. If the number of exclusive group locks is larger than the number of shared group locks, one or more files may be overflowed. Identify these with guide utility.

Shared Index Lock UniData-level read-only lock on an index.

Excl. Index Lock UniData-level exclusive lock on an index. For most applica-tions, the number of shared index locks exceeds the number of exclusive index locks. If the number of exclusive index locks is larger than the number of shared index locks, one or more index files may be overflowed. Identify these with LIST.INDEX ECL command.

End-of-File Lock UniData file level physical lock.

Lock Failure Number of times a process attempts to get a user-level lock and fails because the record is already locked. If performance is suffering, analyze your application for lock handling.

Lock Counters


UniData Program Control StatisticsIf you choose UniData Program Control from the list of Objects, you will see a window similar to the following example:

Tip: You can scroll through the list of Counters to see all values.


The following table describes the Items you can monitor for UniData program control, and indicates performance considerations.

Field Description

Local Call Displays the current, average, minimum, maximum, and total number of UniBasic program control statement executions.

Global Call Number of calls to globally cataloged UniBasic programs. In production environment, this number should be much higher than Locall Call. If a program is globally cataloged, then users share a single copy of the object code in memory, which reduces both memory requirements and physical I/O load.

CallC Call Number of calls to an external C function, From UniBasic CALLC statements.

CHAIN Call Number of UniBasic CHAIN statement executed.

GOSUB Call Number of UniBasic GOSUB commands executed.

LOOP and GOTO Number of UniBasic LOOP and GOTO commands executed.

EXECUTE Call Number of external UniData command executions (From UniBasic EXECUTE commands).

PCPERFORM Call Number of PCPERFORM statements, which execute shell or host operating system tasks. PCPERFORM statements are expensive on NT, because creating a process is slow. If PCPERFORM Call is consistently more than 1 per second, analyze your application and consider replaceing PCPERFORM logic with C routines.

SLEEP Call Number of UniBasic SLEEP command executions. A sudden increase in this number may indicate that a number of users are attempting to get a lock on a record.

Program Control Counters


ECL Process Monitoring CommandsOn Windows platforms, UniData includes three ECL commands that you can invoke to collect and display statistics for their current UniData processes. The commands are:

ENABLE.USERSTATS—This command turns on statistics collection for the user’s current process. Executing this command starts statistics collection for that process, which continues until the user exits UniData or executes the DISABLE.USERSTATS command.DISABLE.USERSTATS—This command turns off statistics collection for the user’s current process. Users can turn statistics collection back on by executing ENABLE.USERSTATS, but all totals are zeroed out each time a user turns off statistics collection.LIST.USERSTATS—If the user turned on statistics collection with ENABLE.USERSTATS, LIST.USERSTATS displays a snapshot of the statistics for the user’s process that were collected since that time. If the user did not turn on statistics collection, or turned it off before executing LIST.USERSTATS, this command displays a list of statistics collected for the entire system since the last time the Windows system was shut down and restarted.

Warning: If you are using the Performance Monitor to monitor overall UniData behavior, and one or more users execute ENABLE.USERSTATS, those processes will not be counted in Performance Monitor output. Statistics for a udt process are recorded in only one place at one time, and the ECL Statistics commands override the performance monitor.

ECL Process Monitoring Commands 18-23

The statistics reported by LIST.USERSTATS are virtually identical to those monitored with the Performance Monitor, although they are organized somewhat differently. The following example shows the output of LIST.USERSTATS for a single udt process:

:LIST.USERSTATSFile I/O Statistics Physical File Opens........ 8 Logical File Opens......... 0 File Closes................ 9 Temp File Closes........... 0 Dynamic File Split......... 255 Dynamic File Merge......... 0 Record Reads............... 101 Record Writes.............. 20060 Record Deletes............. 1 Level 1 Overflow........... 25363 Level 2 Overflow........... 0Program Control Statistics Private Code Calls......... 1 Shared Code Calls.......... 0 Shared Code Failures....... 0 CALLC Calls................ 0 Chain Calls................ 0 Gosub Calls................ 20000 Goto Calls................. 0 Execute Calls.............. 3 Pcperform Calls............ 0Dynamic Array Statistics DELETE..................... 0 FIND....................... 0 INSERT..................... 0 LOCATE..................... 0 MATPARSE................... 0 MATCHFIELD................. 0 COUNT...................... 0 EXTRACT.................... 20000 FIELD...................... 0 REMOVE..................... 0 REPLACE.................... 0 INDEX...................... 0Lock Statistics Record Locks............... 255 Record Unlocks............. 255 Semaphore Locks............ 0 Semaphore Unlocks.......... 0 Shared Group Locks......... 178 Exclusive Group Locks...... 21626 Shared Index Locks......... 0 Exclusive Index Locks...... 0 Lock Failures.............. 0Index Statistics Index Reads................ 0


Index Writes............... 0 Log Reads.................. 0 Log Writes................. 0 Node Merges................ 0 Node Split................. 0 Node Reuse................. 0 Overflow Reads............. 0 Overflow Writes............ 0:

There are a few differences in counter names between the Performance Monitor and LIST.USERSTATS. These are described in the following table.

Performance Monitor LIST.USERSTATS

Global Call Shared Code Calls

Local Call Private Code Calls

(Not reported) Shared Code Failures (Number of times a process called a globally cataloged program and the system found insufficient memory to load the program.) This number should be zero.

Counter Names

ECL Process Monitoring Commands 18-25

ExamplesThis section contains examples that illustrate some ways of using the Windows and UniData Performance Monitoring tools.

The following window shows how you can combine monitoring a system parameter (for instance, CPU time) and a type of UniData activity (for instance, level 1 and level 2 overflow writes):

Notice that overflow writes are associated with an increase in CPU utilization.

The next window shows monitoring CPU use for a udt process and for the Windows system as a whole:


Notice that the udt process corresponds to some, but not all, of the periods of high CPU utilization.

Monitoring one process against the whole system can help differentiate UniData impacts from impacts of other processes.

Examples 18-27

Appendix A UniData Configuration Parameters

This appendix lists the names and descriptions for all UniData configuration param-eters as of Release 7.2. See Chapter 7, “Configuring Your UniData System,” for more information about modifying your udtconfig file.

The following tables describe the configuration parameters that are placed in the udtconfig file located in \udthome\include at the time of installation. They are system-dependent and should not be changed.


LOCKFIFO The locking sequence of processes in the system. This parameter should not be changed.

SYS_PV Type of P/V operations used for the Recoverable File System (RFS) only. Determined at installation; platform dependent. Do not change unless instructed by IBM.

udtconfig File Parameters That Should not be Changed

A-1 Administering UniData on Windows Platforms

The following parameters may be changed to suit your environment.


NFILES Number of physical files that can be opened at the operating system level at one time in a UniData session. This limit is for both udt and tm processes; the name of the corresponding kernel parameter varies among OS versions.

NUSERS Limit for number of UniData user processes (such as udt and PHANTOM) that can run at the same time.

WRITE_TO_CONSOLE Switch for turning on and off messaging to your console. Must be greater than zero for messages to display at console.

TMP Path of a directory for storing intermediate work files. Default is \IBM\ud61\temp.

NVLMARK Specifies a character to print to represent the null value. The ASCII character that represents the null value is nonprinting.

FCNTL_ON Used with UniData Physical Lock Manager. If a UNIX platform supports test-n-set instruction, SYS_PV is set to 3 and FCNTL_ON is set to 0. If a UNIX platform does not support test-n-set instruction, SYS_PV is set to 2 and FCNTL_ON is set to 1. Do not change this parameter unless instructed to do so by IBM.

TOGGLE_NAP_TIME If FCNTL_ON is set to 0, the length of time (in milli-seconds) that a process waits to access a shared memory address held by another process. This parameter has no effect if FCNTL_ON is set to 1. Do not change unless instructed to do so by IBM.

NULL_FLAG Toggles null value handling on and off. If 0, null value handling is off. Must be greater than 0 for null value handling to be in effect.

N_FILESYS Maximum number of UNIX file systems allowed. If you have more than 200 UNIX file systems, increase to your number of file systems.

udtconfig File Parameters That Can be Changed

A-2

N_GLM_GLOBAL_BUCKET The number of hash buckets systemwide, used to hold the lock names in shared memory. This setting directly affects performance. Normally, the default value of this parameter should not be changed. However, if you notice significant degradation in performance, or your appli-cation intensively accesses specific files, you can increase this parameter. The default value is the closest prime number to NUSERS * 3.

N_GLM_SELF_BUCKET The number of hash buckets for the per-process locking table. This parameter is highly application dependent. If the application requires a large number of locks in one transaction (more than 20), you should increase this setting to the closest prime number to the maximum number of locks per transaction.

GLM_MEM_ALLOC The number of lock nodes allocated for each memory request. This parameter is highly application dependent. If the application requires a large number of locks in one transaction, this setting should be increased to the maximum number of locks per transaction * 2.

GLM_MEM_SEGSZ The segment size for each shared memory segment required for the lock manager. The maximum number of segments is 16. Large application environments require a larger size. Each udt will register the lock names it is locking in its per-process locking table. This table is also organized as a hashed table.


udtconfig File Parameters That Can be Changed (continued)


The following parameter is related to internationalization.

BGINPUTTIMEOUT The number of seconds a background or phantom process waits before timing out. Before the timeout expires, a process may use the UNIX tandem or the UniData for Windows NT TANDEM command to attach to the process.

LB_FLAG For nonrecoverable files, turn Transaction Processing on or off by changingthe value of this parameter. If you set the value to 0, Transaction Processing is off for nonre-coverable files and TP semantics are ignored. If you set the value to 1, Transaction Processing is on.Note: If RFS is on, the LB_FLAG has no effect on recov-erable files. You cannot turn off transaction processing for recoverable files if RFS is enabled.

USE_DF The USE_DF parameter enables you to choose how UniData loads the shared memory table. Beginning in UniData 7.2, the smm daemon no longer forked a df process to create the entries in the shared memory table, as it had in prior releases. Now, UniData loads the shared memory table by reading the mount table.If you set the value of USE_DF to 0, UniData loads the shared memory table by reading the mount table. This is the default setting.If you set the value of USE_DF to 1, the smm process forks a df process to load the shared memory table.


UDT_LANGGRP The language group ID used to distinguish language groups that use similar special characters. UDT_LANGGRP is composed of the record mark, escape sequence mark, and the null value mark. The default is 255/192/129.

ZERO_CHAR The character you want to use to represent CHAR(0). See OSREAD, OSBREAD, READT in the UniBasic Commands Reference for more information.

Internationalization udtconfig Parameters


udtconfig File Parameters That Can be Changed (continued)

A-4

The following table describes shared memory related parameters. These parameters may be changed to suit your environment.


SBCS_SHM_SIZE Size, in bytes, of shared memory segments created by sbcs to store globally cataloged programs. sbcs can attach a maximum of 20 segments systemwide. Runtime errors result if you attempt to load a new global program that exceeds this limit.

SHM_MAX_SIZE Current kernel setting for maximum size (in bytes) of a shared memory segment. This parameter is set at installation; if you increase the kernel parameter shmmax, you need to increase SHM_MAX_SIZE to the same value as well.

SHM_ATT_ADD Starting address for shared memory attachment. Set at installation; do not change this unless instructed by IBM.

SHM_LBA Alignment size, in bytes, for shared memory attachment. Set at installation; do not change.

SHM_MIN_NATT The minimum number of shared memory segments that should be kept attached to a process.

SHM_GNTBLS Number of GCTs (global control tables) in CTL. Each shared memory segment is associated with a GCT. The GCT registers the use of global pages in its associated shared memory segment. Cannot exceed the kernel parameter shmmni.

SHM_GNPAGES Number of global pages in a shared memory segment.

SHM_GPAGESZ Size of each global page, in 512-byte units.

SHM_LPINENTS Number of entries in the PI table of a LCT, which is the number of processes allowed in a process group. It is set to 10 within the system, regardless of the udtconfig setting.

SHM_LMINENTS Number of entries in the MI table of a LCT, which means the number of global pages or self-created dynamic segments that can be attached by a process. Cannot exceed 255.

SHM_LCINENTS The number of entries in the CI table of each LCT, which is the number of local pages that can be attached by a process.

Shared Memory udtconfig File Parameters


The following table describes size limitation parameters.

SHM_LPAGESZ Size, in 512-byte blocks, of each local page in a global page. A global page is divided into local pages, so SHM_GPAGESZ must be a multiple of SHM_LPAGESZ.

SHM_FREEPCT Percentage of freed global pages in an active global shared memory segment that UniData keeps in the global shared memory pool. smm checks the current percentage; if the percentage is less than SHM_FREEPCT, smm creates a new shared segment.

SHM_NFREES The number of inactive shared memory segments that UniData keeps in the system. smm checks the current number of inactive segments; if the number is larger than SHM_NFREES, smm returns some inactive global shared segments to UNIX.


AVG_TUPLE_LEN Number of local pages that matches the average length of records in your applications. Specifies the length of a buffer kept by udt for holding a record. Should not exceed the number of local pages in a global page.

EXPBLKSIZE Number of local pages used for expression buffers. udt keeps a buffer of this size for intermediate results. IBM recommends you set this parameter so the buffer is one-quarter to one-half the size of a global page.

MAX_OBJ_SIZE Maximum size, in bytes, of object programs that can be loaded into shared memory. Object programs larger than this size are loaded into the user’s address space instead of shared memory.

MIN_MEMORY_TEMP The minimum number of local pages that should be kept for temporary buffers in a process group. Determined at installation.

Size Limitation udtconfig File Parameters


Shared Memory udtconfig File Parameters (continued)

A-6

The following table describes parameters related to dynamic files.

STATIC_GROWTH_ WARN_TABLE_SIZE

The number of table elements in the Static Growth Warn table. UniData uses this table to track the last time a warning was issued indicating a file was larger than the threshold. When no unused elements are present in the table, UniData uses the oldest element for a new static file. If the file is nonrecoverable, UniData writes the infor-mation to the udt.errlog file. If the file is recoverable, UniData writes the information to the sm.log file.

STATIC_GROWTH_ WARN_SIZE

The threshold value for the static file size, expressed in bytes. If the file is nonrecoverable, UniData writes the information to the udt.errlog file. If the file is recoverable, UniData writes the information to the sm.log file

STATIC_GROWTH_ WARN_INTERVAL

The time interval, expressed in seconds, to warn when a static file is larger than the threshold. If the file is nonrecov-erable, UniData writes the information to the udt.errlog file. If the file is recoverable, UniData writes the information to the sm.log file


GRP_FREE_BLK Pertains to dynamic files only; the number of free blocks kept in the free block list at the group level. If more blocks are freed, they are kept at the file level.

SHM_FIL_CNT Maximum number of dynamic files that can be open concurrently, systemwide.

SPLIT_LOAD Default loading factor option (percent) at which a group in a dynamic file using the KEYONLY option splits. Splitting occurs when the percentage of space in a group occupied by keys and pointers reaches the split load. The ECL CONFIGURE.FILE command overrides this for individual files.

Dynamic File udtconfig File Parameters


Size Limitation udtconfig File Parameters (continued)


MERGE_LOAD Default loading factor (percent) at which a group pair in a dynamic file using the KEYONLY option merges. A group pair is eligible for merging when the sum of the percentages of space occupied by keys and pointers in both groups is less than MERGE_LOAD. The CONFIGURE.FILE command lets users override this for individual files.

KEYDATA_SPLIT_ LOAD

Default loading factor (percent) at which a group in a dynamic file using the KEYDATA option splits. Splitting occurs when the percentage of space in a group occupied by keys and pointers reaches the split load. The ECL CONFIGURE.FILE command overrides this for individual files.

KEYDATA_MERGE_LOAD

Default loading factor (percent) at which a group pair in a dynamic file using the KEYDATA option merges. A group pair is eligible for merging when the sum of the percentages of space occupied by keys and pointers in both groups is less than KEYDATA_MERGE_LOAD. The CONFIGURE.FILE command overrides this for individual files.

MAX_FLENGTH Upper size limit, in bytes, of each partition file (dat00x) of a dynamic file. When a part file reaches this size, UniData does not add further blocks to it, but creates another part file using the part table. The default value is 1073741824 bytes (1 GB). Must be greater than 32768 bytes (32 KB) and less than 2147467264 bytes (2 GB-16KB).

PART_TBL Path of a UNIX text file that directs UniData where to create dynamic file part files.


Dynamic File udtconfig File Parameters (continued)

A-8

The following parameters are for NFA server.

The following table describes parameters related to Journaling.

The following table describes UniBasic file-related parameters.


EFS_LCKTIME Used by the NFA server to specify the maximum time to wait for a lock.

TSTIMEOUT Used by the udtts executable to specify the maximum number of seconds to wait for input from client about device information. If the information is not provided, UniData starts without the device information.

NFA_CONVERT_CHAR If this value is set to 1, UniData converts marks in a stream of data to host-specific marks.

NFA udtconfig File Parameters


JRNL_MAX_PROCS Maximum number of journal processes per journal path.

JRNL_MAX_FILES Maximum number of journal files allowed per journal process.

Journaling udtconfig File Parameters


MAX_OPEN_FILE Maximum number of hashed files that can be opened by UniBasic OPEN statements, per udt process. Includes RFS and non-RFS, static, dynamic, and sequentially hashed files; each dynamic file counts as one file.

MAX_OPEN_SEQF Maximum number of sequential files that can be opened at one time by UniBasic OPENSEQ statements, per udt process.

MAX_OPEN_OSF Maximum number of UNIX sequential files that can be opened at one time by UniBasic OSOPEN statements, per udt process.

MAX_DSFILES Maximum number of nonrecoverable dynamic part files (dat00x, over00x) a UniData process can open with UniBasic OPEN statements or ECL commands. Each dynamic file has at least two part files.

UniBasic File-Related udtconfig File Parameters


The following table describes parameters related to UniBasic.

The following parameter is used in semaphore operations.


MAX_CAPT_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH CAPTURING or MDPERFORM WITH CAPTURING clauses. Individual users can set an environment variable that overrides the configuration parameter.

MAX_RETN_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH RETURNING or MDPERFORM WITH RETURNING clauses. Individual users can set an environment variable that overrides the configuration parameter.

COMPACTOR_ POLICY

Used to guide BASIC memory compactor to do compaction for BASIC strings. 0 — compact when program is finished 1 — compact when EXECUTE (another BASIC pgm) is completed2 — compact when EXECUTE (another BASIC program) or CALL is completed

VARMEM_PCT The percentage of free memory that should be kept in the first global page for UniBasic variables after compacting. If the actual percentage is less than this value, UniData keeps one free global page. Otherwise, UniData returns all free global pages to UNIX.

UniBasic udtconfig File Parameters


NSEM_PSET Number of semaphores per semaphore set.

Semaphore udtconfig File Parameters

A-10

The following table describes index-related parameters.

The following parameter is used with the UniData Physical Lock Manager.

The following parameters are used with UniData _HOLD_ files.


SETINDEX_BUFFER_ KEYS Controls whether READFWD and READBCK statements use a buffering mechanism. Default value is 0 (buffering off). Individual environment variable overrides udtconfig setting; BUFFER.KEYS keyword in the SETINDEX statement overrides either.

SETINDEX_VALIDATE_KEY Controls whether READFWD and READBCK statements validate a key value just read. Default value is 0 (no validation). Individual environment variable overrides udtconfig setting. VALIDATE.KEY keyword in the SETINDEX statement overrides either.

Index udtconfig File Parameters

Parameter Name Description

MGLM_BUCKET_SIZE Number of nodes per bucket. If this parameter is inade-quate for an application, an out of memory message is displayed.

UPL_LOGGING Determines if UPL performs logging. If this parameter is set to 0, UPL does not perform any logging. If this value is set to 1, UPL performs logging.

Physical Lock Manager udtconfig File Parameters

Parameter Name Description

MAX_NEXT_HOLD_DIGITS Enables you to specify the number of digits used for the next _HOLD_ file number, found in the NEXT.HOLD record of D__HOLD.

CHECK_HOLD_EXIST Determines if UniData checks for the existence of a _HOLD_ file prior to unconditionally removing it when you specify the BANNER UNIQUE option with the SETPTR command.

_HOLD_ File udtconfig File Parameters


The following parameter is used to turn the Recoverable File System off and on.

The following parameters are related to open files with the Recoverable File System.

The following parameters are related to the active file table (AFT) used with the RFS.


SB_FLAG Toggles system buffer on and off. If zero, system buffer is off. Must be greater than zero for RFS.

Recoverable File System on/off udtconfig Parameter


BPF_NFILES Per-process logical limit for total number of RFS files that can be opened with UniBasic OPEN statements at one time. If more RFS files are opened, UniData closes files and then reopens them, causing heavy overhead. This parameter cannot exceed N_AFT.

N_PARTFILE Systemwide total number of recoverable dynamic part files that can be open at one time. This limit includes files opened by ECL and UniBasic. Each dynamic file has at least two part files, so opening a dynamic file means opening at least two part files. Even if more than one user opens the same dynamic file, each part file is counted once toward the total.

Recoverable File System udtconfig Parameters


N_AFT Systemwide limit on the number of recoverable files and indexes that can be open at one time. This is the number of slots in the system buffer AFT. Parameter is like MAX_OPEN_FILES but pertains only to recoverable files. A dynamic file counts as one file. Even if more than one user opens the same file, it is only counted once.

N_AFT_SECTION Number of sections in the AFT. Used for RFS only.

Active File Table udtconfig Parameters

A-12

The following table describes parameters related to the archiving feature of RFS.

The following parameters are used for the system buffer in the RFS.

N_AFT_BUCKET Number of hash buckets in the AFT. Used for RFS only.

N_AFT_MLF_BUCKET Number of hash buckets in the AFT for tracking multilevel files. Used for RFS only.

N_TMAFT_BUCKET Number of hash buckets in each tm process’ active file table (TMAFT). Used for RFS only.


ARCH_FLAG Toggles archiving function on and off for RFS. Must be greater than 0 for archiving.

N_ARCH The number of archive files.

ARCHIVE_TO_TAPE Switch for turning on automatic save of archive files to backup. Changing the value to 1 turns on this feature.

ARCH_WRITE_SZ Size, in bytes, of blocks for the archive process to write from the log files to the archive files. Default is zero, meaning each write is one block. If set to a nonzero value, must be a multiple of the log/archive block size.

Archiving udtconfig Parameters


N_BIG Number of block index groups. This parameter determines the size of an index table for accessing the RFS system buffer. If you enlarge N_PUT, you should enlarge N_BIG as well. Must be a prime number.

N_PUT Number of 1,024-byte pages in the system buffer. The size of the buffer cannot exceed SHMMAX. Sometimes the default value of N_PUT must be decreased in order to complete a UniData installation.

System Buffer udtconfig File Parameters


Active File Table udtconfig Parameters (continued)


The following table describes parameters used for message queues with the Recov-erable File System.

The following table describes the parameter related to the IPC mechanism between the udt and tm processes on Windows platforms only.


N_PGQ Number of message queues for tm processes to send messages to udt processes. Calculated by installation; one queue for every four licenses.

N_TMQ Number of message queues for udt processes to send messages to tm processes. Calculated by installation; one queue for every four licenses.

Message Queue udtconfig File Parameters


UDT_TM_IPC On UniData for UNIX, the udt and tm processes communicate using message queues. Since message queues are not available on Windows platforms, UniData provides three options for the communication between the udt and tm processes:? UDT_TM_IPC=1 – UniData uses its own message queues to

communicate between the udt and tm processes. If you change the value of the N_PGQ or N_TMQ udtconfig parameters, you must also change the value of the MSGMNI configuration parameter. The value of MSGMNI should be 12+N_PGQ+N_TMQ.

? UDT_TM_IPC=2 – UniData uses named pipes as the commu-nication mechanism between the udt and tm processes. Each udt process creates two named pipes, one for the udt process to write and the tm process to read, and one for the tm process to write and the udt process to read.

? UDT_TM_IPC=3 – UniData uses memory-mapped files and events to communicate between the udt and tm processes. Each udt process creates 2K memory-mapped files when it starts.

The default value for the UDT_TM_IPC udtconfig parameter is 3

IPC Mechanism Parameter

A-14

The following table describes parameters related to the before image and after image log files used with RFS.


N_AIMG Number of after image log files in each log set.

N_BIMG Number of before image log files in each log set.

AIMG_BUFSZ The size of the after image buffer, in bytes.

BIMG_BUFSZ The size of the before image buffer, in bytes.

AIMG_MIN_BLKS Minimum number of blocks required in the after image buffer before the system flushes the blocks to the after image logs. Block size is set in the log configuration table.

BIMG_MIN_BLKS Minimum number of blocks required in the before image buffer before the system flushes the blocks to the before image logs. Block size is set in the log configuration table.

AIMG_FLUSH_BLKS Number of blocks that are flushed to the after image logs from the after image buffer at one time.

Before Image/After Image udtconfig File Parameters


The following table describes the parameters that determine flushing intervals for RFS.

BIMG_FLUSH_BLKS Number of blocks that are flushed to the before image logs from the before image buffer at one time.

RFS_DUMP_DIR Defines where UniData stores the rfs.dump file when you execute the s_stat -s command. The default value is an empty string, with UniData storing the rfs.dump file in the $UDTBIN directory. If the path you specify is invalid when UniData starts, UniData writes the rfs.dump file to the $UDTBIN directory, and prints a message to the sm.log.

RFS_DUMP_HISTORY Specifies how many rfs.dump files to preserve when you execute the s_stat -s command.The default value is 1. With this value, UniData creates the rfs.dump file in the directory you specify with the RFS_DUMP_DIR parameter.If this value is set to a positive integer, for example 4, the rfs.dump files will be named rfs.dump1, rfs.dump2, rfs.dump3, and rfs.dump4. The s_stat -s command uses the first available rfs.dump file. If all rfs.dump files are full, s_stat -s reuses the oldest rfs.dump.file.If this value is set to 0, all rfs.dump files are preserved and named rfs.dump1, rfs.dump2, and so forth.


CHKPNT_TIME Checkpoint interval: number of seconds between flushes of the system buffer to disk.

GRPCMT_TIME Interval, in seconds, between flushes to the after image log set.

LOG_OVRFLO Path to the directory where UniData creates log overflow files.

Flushing Interval udtconfig File Parameters


Before Image/After Image udtconfig File Parameters (continued)

A-16

The following table describes the parameters related to the sync daemon.

The following table describes Windows platform message queue parameters.

The following table describes the parameter related to the Century Pivot date.


N_SYNC Determines how many sync daemons UniData should start.

SYNC_TIME Defines the number of seconds the sync daemon should wait before scanning the Block Index Group to flush dirty pages.

Sync Daemon udtconfig File Parameters


MSGMNI The maximum number of message queues available for UniData system-wide.

MSGMAX The maximum size of a message.

MSGTQL The maximum number of messages allowed systemwide.

MSGTX The default text size of a message per node.

Windows Platform Message Queue udtconfig Parameters


CENTURY_PIVOT Determines the century pivot date. Default is 1930.

Century Pivot udtconfig File Parameters


The following table describes the parameters related to Replication.


REP_FLAG Turns UniData Data Replication on or off. If this value is 0, UniData Data Replication is off. If this value is a positive integer, it is on.

TCA_SIZE The maximum number of entries in the Transaction Control Area. The default value is 2048.

MAX_LRF_FILESIZE The maximum Log Reserve File size, in bytes. The default value is 134217728 (128 MB). The maximum value is 2147483136.

N_REP_OPEN_FILE The maximum number of open replication log files for a udt or tm process. The default value is 8.

MAX_REP_DISTRIB Reserved for internal use.

MAX_REP_SHMSZ The maximum shared memory buffer segment size. The default value is 67108864 (64 MB).

REP_LOG_PATH The full path to the replication log file.

UDR_CONVERT_CHAR When this value is set to 1, if the publishing system and the subscribing system have a different I18N group, UniData converts marks and SQLNULL marks to those on the local machine on the data passed between the two systems. The default value is 0.

REP_CP_TIMEOUT Specifies the cm daemon timeout interval for replication. The default value is 300 seconds. If this value is set to 0, the cm daemon will not time out.

Replication udtconfig Parameters

A-18

The following table describes the udtconfig parameters related to Euro processing.


CONVERT_EURO Turns Euro conversion on or off. If this flag is set to 0, UniData does not perform conversion. If this flag is set to 1, UniData performs conversion.

SYSTEM_EURO The configurable system Euro encoding. On UNIX systems, the default is CHAR(164). On Windows Platforms, the default is CHAR(128).

TERM_EURO Sets the terminal system Euro Code. On UNIX systems, the default is CHAR(164). On Windows Platforms, the default is CHAR(128).

Euro Processing udtconfig Parameters


Appendix B Environment Variables for UniData

This appendix lists environment variables that can be set to customize a UniData environment. Users can set them before entering UniData to affect a particular UniData session. System administrators can also set them for one or more users to establish defaults for some or all users.

The following table lists environment variables in alphabetical order.

Environment Variable Description

ALLOW_DBPAUSE_OSBWRITE When this environment variable is set to 1, an OSBWRITE process is successful even if dbpause if active. If the environment variable is set to 0, an OSBWRITE process pauses.

BACKUP_CNTL_FILE Used by the Recoverable File System (RFS); specifies a path where the udt.control.file can be automatically backed up at checkpoint time. If this variable is not defined, udt.control.file is not backed up. Valid on UniData for UNIX only.

CSTACKSZ Establishes the maximum number of commands in the ECL command stack. Each stack entry can hold a 2720 character command. The default is 49.Note: You must restart UniData if you change CSTACKSZ for your change to take effect.

INIT_BREAKOFF [0 | 1]

Enables/disables break key prior to invoking UniData. If INIT_BREAKOFF is not set, the break key is enabled by default.

Environment Variables for UniData

B-1

LPREQ Identifies an alternate spooler directory. Must be a full path ending in “/”. Valid on UniData for UNIX only.

MAX_CAPT_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH CAPTURING or MDPERFORM WITH CAPTURING clauses. This environment variable overrides the configuration parameter in the udtconfig file.

MAX_RETN_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH RETURNING or MDPERFORM WITH RETURNING clauses. This environment variable overrides the configuration parameter in the udtconfig file.

MAX_TRANS_FIELD Number of TRANS fields that can be kept concurrently; default value is 12; must not be greater than 64

MAX_TRANS_REL Number of TRANS files that can be open concurrently; default value is 32; must not be greater than 32.

NFA_LOG_DIR Used by NFA; name of a directory where NFA client-side log files are created. If this variable is not defined, the logs are created in \temp.

NFA_LOG_LEVEL Used by NFA; debug level for NFA client processes. May be an integer 0-10; level 0 logs only fatal errors, and level 10 logs all traffic and many internal functions. The default is level 0.

NOCHKLPREQ Bypasses UNIX printer verification; useful for large systems with hundreds of printers defined. Valid on UniData for UNIX only.

SETINDEX_BUFFER_KEYS Controls whether READFWD and READBCK statements use a buffering mechanism. Default value is 0 (buffering off). Individual environment variable overrides udtconfig setting; BUFFER.KEYS keyword in the SETINDEX statement overrides both.



B-2 Administering UniData on Windows Platforms

SETINDEX_VALIDATE_KEY

Controls whether READFWD and READBCK statements validate a key value just read against the record. Default value is 0 (no validation). Individual environment variable overrides udtconfig setting; VALIDATE.KEY keyword in the SETINDEX statement overrides both.

SGLISTNUM Size of token stack for XREF, in UENTRY. Default is 500.

SQL_TMP_MODULO Number of temporary files used by UniData SQL for an equal join operation. Default is 7; if this is set to a number less than 7, UniData SQL uses the default. No upper limit. Must be set before entering udt/SQL, or before starting UniServer.

SUPPRESS_ORPHAN_BLOCK_ ERROR

Determines if the guide utility reports orphan blocks. Orphan blocks could exist in both the primary file and the overflow files. guide reports these errors in the GUIDE_ERRORS.LIS file. If you want to suppress these messages, set the value of SUPPRESS_ORPHAN_BLOCK_ERROR to a positive integer.

TABSTOPS Specifies a number of characters to tab in UniBasic PRINT statements. Must be 1-76. The default is 8.

TMP Identifies an alternate directory for \temp when additional work space is needed by UniData. Must be a directory path ending with \.

UDT_EDIT Identifies the path of the text editor UniData invokes when users execute the ECL ED command. The default is the MS-DOS editor. This variable cannot be set to AE.

UDT_MAXNUMSHM The number of memory mapped files a UniData process can create or attach.

UDT_SAVELIST Allows you to specify a default list name for each UniData user. Set in the user’s .login or .profile. Users can also specify a list name when executing the SAVE.LIST command.



B-3

UDT_SELECTSIZE Size of a buffer used to keep select list in memory. If a select list is larger then the size of this buffer, it will be written to a file. If UDT_SELECTSIZE is not defined, the system uses a buffer size of 10 KB.

UDTBIN Location of UniData executables.

UDTERRLOG_LEVEL Determines the logs to which file open errors are written. If the value of this environment variable is equal to or greater than 2, UniData writes file open errors to the udt.errlog, and on Windows platforms, to the Windows event log. Otherwise, UniData does not log file open errors.

UDTHOME Location of the UniData home directory, which contains directories including sys, demo, lib, work, sybase, and include.

VFIELDSIZE Increases the size for the stack of C routines used to process formulas created in virtual fields. Default is 300. Define a larger number if users see “virtual field too big” errors in UniQuery.

VOC_READONLY If set to a nonzero number, allows UniData to run with read-only access to the VOC file.

VVTERMCAP The UNIX path of the vvtermcap file needed to run the UniData commands UENTRY, shmconf, and confprod. This variable is not necessary if UDTBIN is defined.



B-4 Administering UniData on Windows Platforms

Administering UniData on Windows Platforms versions/v7.2...Administering UniData on Windows...

Documents

Transcript of Administering UniData on Windows Platforms versions/v7.2...Administering UniData on Windows...