unidata - prismhr os/400, ibm informix®, ... chapter 22 performance monitoring and tuning ... tips...

UniData

Administering UniData on UNIX

Version 6.0September, 2002Part No. 000-9101

ii Administering UniDat

IBM Corporation555 Bailey AvenueSan Jose, CA 95141

Licensed Materials – Property of IBM

© Copyright International Business Machines Corporation 2002. All rights reserved.

AIX, DB2, DB2 Universal Database, Distributed Relational Database Architecture, NUMA-Q, OS/2, OS/390,

and OS/400, IBM Informix®, C-ISAM®, Foundation.2000 ™, IBM Informix® 4GL, IBM Informix®

DataBlade® module, Client SDK™, Cloudscape™, Cloudsync™, IBM Informix® Connect, IBM Informix®

Driver for JDBC, Dynamic Connect™, IBM Informix® Dynamic Scalable Architecture™ (DSA), IBM

Informix® Dynamic Server™, IBM Informix® Enterprise Gateway Manager (Enterprise Gateway Manager),

IBM Informix® Extended Parallel Server™, i.Financial Services™, J/Foundation™, MaxConnect™, Object

Translator™, Red Brick® Decision Server™, IBM Informix® SE, IBM Informix® SQL, InformiXML™,

RedBack®, SystemBuilder™, U2™, UniData®, UniVerse®, wIntegrate® are trademarks or registered

trademarks of International Business Machines Corporation.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems,

Inc. in the United States and other countries.

Windows, Windows NT, and Excel are either registered trademarks or trademarks of Microsoft Corporation

in the United States and/or other countries.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open

Company Limited.

Other company, product, and service names used in this publication may be trademarks or service marks of

others.

This product includes cryptographic software written by Eric Young ([email protected]).

This product includes software written by Tim Hudson ([email protected]).

Documentation Team: Claire Gustafson

US GOVERNMENT USERS RESTRICTED RIGHTS

Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

a on UNIX

Table of Contents

Table ofContents

Chapter 1 IntroductionIntroduction . . . . . . . . . . . . . . . . . . . . 1-3

Audience . . . . . . . . . . . . . . . . . . . . 1-4

Chapter 2 UniData and UNIX SecurityUNIX File Permissions . . . . . . . . . . . . . . . 2-4

Additional UNIX Access Modes . . . . . . . . . . . . 2-6

UNIX umask . . . . . . . . . . . . . . . . . . 2-8

UniData Default Permissions . . . . . . . . . . . . . 2-10

UniData Processes and root . . . . . . . . . . . . . 2-11

Chapter 3 UniData and the UNIX File SystemUniData Directories and Files . . . . . . . . . . . . . 3-4

Files, Pointers, and Links . . . . . . . . . . . . . . 3-6

Creating Files . . . . . . . . . . . . . . . . . . 3-6

Setting a UniData Pointer . . . . . . . . . . . . . . 3-6

Setting an Environment Variable . . . . . . . . . . . . 3-8

Setting a UNIX Link . . . . . . . . . . . . . . . . 3-9

UniData Hashed Files . . . . . . . . . . . . . . . 3-11

Static Files . . . . . . . . . . . . . . . . . . . 3-11

Dynamic Files . . . . . . . . . . . . . . . . . . 3-12

Sequentially Hashed Files . . . . . . . . . . . . . . 3-14

DIR-Type Files . . . . . . . . . . . . . . . . . . 3-16

Multilevel Files . . . . . . . . . . . . . . . . . . 3-17

Multilevel Directory Files . . . . . . . . . . . . . . 3-18

Index Files and Index Log Files . . . . . . . . . . . . 3-19

UniData and tmp Space . . . . . . . . . . . . . . . 3-21

Changing TMP in the udtconfig File . . . . . . . . . . 3-22

Setting an Environment Variable . . . . . . . . . . . . 3-22

iv Admin

Chapter 4 UniData and DaemonsWhat Is a Daemon? . . . . . . . . . . . . . . . . 4-4

Principal UniData Daemons . . . . . . . . . . . . . 4-5

Shared Basic Code Server (sbcs). . . . . . . . . . . . 4-5

Shared Memory Manager (smm) . . . . . . . . . . . 4-6

Clean Up (cleanupd) . . . . . . . . . . . . . . . 4-7

UniRPC Service (unirpcd). . . . . . . . . . . . . . 4-8

sync Daemon . . . . . . . . . . . . . . . . . . 4-8

Monitoring UniData Daemons . . . . . . . . . . . . 4-9

showud Command . . . . . . . . . . . . . . . . 4-9

Log Files. . . . . . . . . . . . . . . . . . . . 4-9

Chapter 5 UniData and MemoryUNIX and Shared Memory . . . . . . . . . . . . . 5-4

UniData and Shared Memory . . . . . . . . . . . . 5-5

smm and Shared Memory. . . . . . . . . . . . . . 5-5

sbcs and Shared Memory . . . . . . . . . . . . . . 5-13

Self-Created Segments . . . . . . . . . . . . . . . 5-13

UniData and the UNIX Kernel . . . . . . . . . . . . 5-14

Chapter 6 UniData and UNIX ipc FacilitiesMessage Queues . . . . . . . . . . . . . . . . . 6-4

UniData and Message Queues . . . . . . . . . . . . 6-4

Semaphores . . . . . . . . . . . . . . . . . . 6-6

Chapter 7 UniData and UNIX DevicesUNIX Devices: Overview . . . . . . . . . . . . . . 7-4

UniData and Terminal Devices . . . . . . . . . . . . 7-5

UniData and Tape Devices . . . . . . . . . . . . . 7-6

UniData and Printers . . . . . . . . . . . . . . . 7-7

UniData and Serial Devices . . . . . . . . . . . . . 7-8

Chapter 8 Configuring Your UniData SystemConfiguration Procedure . . . . . . . . . . . . . . 8-4

Chapter 9 Starting, Stopping, and Pausing UniDataStarting, Stopping, and Pausing UniData . . . . . . . . . . 9-3

Normal Operation . . . . . . . . . . . . . . . . 9-4

UniData Log Files . . . . . . . . . . . . . . . . 9-4

Start UniData with startud . . . . . . . . . . . . . 9-5

istering UniData on UNIX

Stop UniData with stopud . . . . . . . . . . . . . 9-6

Pausing UniData . . . . . . . . . . . . . . . . 9-7

The dbpause Command . . . . . . . . . . . . . . 9-7

The dbpause_status Command . . . . . . . . . . . 9-9

Resuming Processing . . . . . . . . . . . . . . . 9-9

Additional Commands . . . . . . . . . . . . . . 9-10

Listing Processes with showud . . . . . . . . . . . 9-11

Stopping a User Process with stopudt . . . . . . . . . 9-11

Stopping a User Process with deleteuser . . . . . . . . 9-12

Displaying ipc Facilities with ipcstat . . . . . . . . . 9-13

Removing ipc Structures with udipcrm . . . . . . . . 9-14

Stopping UniData with stopud -f. . . . . . . . . . . 9-15

Chapter 10 Managing UniData AccountsWhat Is a UniData Account? . . . . . . . . . . . . 10-4

Creating a UniData Account . . . . . . . . . . . . 10-5

Saving and Restoring Accounts . . . . . . . . . . . 10-9

Deleting an Account . . . . . . . . . . . . . . . 10-10

Clearing Space in UniData Accounts . . . . . . . . . 10-11

CLEAR.ACCOUNT . . . . . . . . . . . . . . . 10-11

Chapter 11 Managing UniData SecurityLogins and Groups . . . . . . . . . . . . . . . 11-4

Adding a UNIX User . . . . . . . . . . . . . . . 11-4

Use Separate Logins . . . . . . . . . . . . . . . 11-5

User Groups . . . . . . . . . . . . . . . . . . 11-5

Home Directories . . . . . . . . . . . . . . . . 11-6

Startup Scripts . . . . . . . . . . . . . . . . . 11-7

Customizing Permissions . . . . . . . . . . . . . 11-8

Customizing a VOC File . . . . . . . . . . . . . . 11-12

Customizing UniData . . . . . . . . . . . . . . 11-13

Remote Items . . . . . . . . . . . . . . . . . 11-15

The SETFILE Command . . . . . . . . . . . . . . 11-17

LOGIN and LOGOUT Paragraphs . . . . . . . . . . 11-18

UniData SQL Privileges . . . . . . . . . . . . . . 11-21

Field-Level Security for UniQuery . . . . . . . . . . 11-22

Points to Remember about Field-Level Security. . . . . . 11-22

The QUERY.PRIVILEGE File . . . . . . . . . . . . 11-23

Turning on Field-Level Security . . . . . . . . . . . 11-25

Table of Contents v

vi Admin

Chapter 12 Managing UniData FilesUniData Hashed Files . . . . . . . . . . . . . . . 12-4

Static Hashed Files . . . . . . . . . . . . . . . . 12-5

Dynamic Hashed Files . . . . . . . . . . . . . . . 12-6

Dynamic Files and Overflow. . . . . . . . . . . . . 12-7

Dynamic Files, Part Files, and Part Tables . . . . . . . . 12-9

When Dynamic Files Are Created . . . . . . . . . . . 12-12

Tips and Constraints for Creating a Dynamic File . . . . . 12-14

When Dynamic Files Expand . . . . . . . . . . . . 12-15

Management Tools for Dynamic Files. . . . . . . . . . 12-19

Dynamic Files and Disk Space . . . . . . . . . . . . 12-20


File-Handling Commands. . . . . . . . . . . . . . 12-27

File Corruption . . . . . . . . . . . . . . . . . 12-31

What Causes File Corruption? . . . . . . . . . . . . 12-31

Preventing File Corruption . . . . . . . . . . . . . 12-32

UniData Detection Tools . . . . . . . . . . . . . . 12-34

guide . . . . . . . . . . . . . . . . . . . . . 12-34

guide_ndx . . . . . . . . . . . . . . . . . . . 12-39

verify2 . . . . . . . . . . . . . . . . . . . . 12-40

UniData Recovery Tools . . . . . . . . . . . . . . 12-43

dumpgroup . . . . . . . . . . . . . . . . . . 12-43

fixgroup . . . . . . . . . . . . . . . . . . . . 12-45

fixfile . . . . . . . . . . . . . . . . . . . . . 12-46

Detection and Repair Examples . . . . . . . . . . . . 12-51

How to Use guide . . . . . . . . . . . . . . . . 12-53

Error Messages . . . . . . . . . . . . . . . . . 12-56

File Access Messages . . . . . . . . . . . . . . . 12-56

Block Usage Messages . . . . . . . . . . . . . . . 12-56

Group Header Messages . . . . . . . . . . . . . . 12-57

Header Key Messages . . . . . . . . . . . . . . . 12-57

Other Header Messages . . . . . . . . . . . . . . 12-57

Free Block Messages. . . . . . . . . . . . . . . . 12-59

Long Record Messages . . . . . . . . . . . . . . . 12-59

Dynamic File Messages . . . . . . . . . . . . . . 12-60

Chapter 13 Managing UniData LocksThe Global Lock Manager. . . . . . . . . . . . . . 13-4

How GLM Works . . . . . . . . . . . . . . . . 13-4

Locking in UniBasic . . . . . . . . . . . . . . . . 13-6


How Locks Work . . . . . . . . . . . . . . . . 13-6

Locking Commands . . . . . . . . . . . . . . . 13-7

Resource Locks . . . . . . . . . . . . . . . . . 13-9

Listing Locks. . . . . . . . . . . . . . . . . . 13-10

LIST.READU. . . . . . . . . . . . . . . . . . 13-10

Parameters . . . . . . . . . . . . . . . . . . 13-10

LIST.LOCKS . . . . . . . . . . . . . . . . . . 13-12

LIST.QUEUE. . . . . . . . . . . . . . . . . . 13-13

LIST.QUEUE Display . . . . . . . . . . . . . . . 13-14

Commands for Clearing Locks . . . . . . . . . . . 13-18

SUPERCLEAR.LOCKS Command . . . . . . . . . . 13-18

SUPERRELEASE Command . . . . . . . . . . . . 13-20

Procedure for Clearing Locks . . . . . . . . . . . . 13-21

Chapter 14 Managing UniData UsersAdding Users . . . . . . . . . . . . . . . . . 14-4

Every User Needs a Login . . . . . . . . . . . . . 14-4

Create Logins at the UNIX Level . . . . . . . . . . . 14-4

Assign Users to Groups . . . . . . . . . . . . . . 14-5

Monitoring User Processes . . . . . . . . . . . . . 14-6

UniData Commands . . . . . . . . . . . . . . . 14-6

Removing User Processes . . . . . . . . . . . . . 14-8

Using TIMEOUT . . . . . . . . . . . . . . . . 14-9

Chapter 15 Managing Printers in UniDataUniData and UNIX Spoolers . . . . . . . . . . . . 15-4

Configuring the Spooler . . . . . . . . . . . . . . 15-4

SETOSPRINTER Command . . . . . . . . . . . . 15-7

Spooling from UniData . . . . . . . . . . . . . . 15-8

UniData Printing Commands . . . . . . . . . . . . 15-9

Configuring and Troubleshooting a Printer . . . . . . . 15-11

Physical Connection . . . . . . . . . . . . . . . 15-11

Spooler Definition . . . . . . . . . . . . . . . . 15-11

Definition in UniData. . . . . . . . . . . . . . . 15-12

SETPTR . . . . . . . . . . . . . . . . . . . 15-13

Environment Variables . . . . . . . . . . . . . . 15-17

Disabling Printer Validation . . . . . . . . . . . . 15-17

Defining an Alternate Search Path . . . . . . . . . . 15-17

Examples . . . . . . . . . . . . . . . . . . . 15-18

Redefining the Default UniData Print Unit . . . . . . . 15-18

Table of Contents vii

viii Adm

Submitting Concurrent Print Jobs . . . . . . . . . . . 15-18

Printing to a UNIX Device . . . . . . . . . . . . . 15-19

Passing Spooler Options to UNIX . . . . . . . . . . . 15-20

Decoding a UniData Print Statement . . . . . . . . . . 15-21

Chapter 16 Accessing UNIX DevicesUniData Tape Handling Commands . . . . . . . . . . 16-4

SETTAPE . . . . . . . . . . . . . . . . . . . 16-6

Steps for Tape Device Use . . . . . . . . . . . . . . 16-7

UniData LINE Commands . . . . . . . . . . . . . 16-10

Communicating with GET and SEND . . . . . . . . . 16-11

Dual-Terminal Debugging in UniBasic . . . . . . . . . 16-13

Setting Up Dual-Terminal Debugging . . . . . . . . . 16-14

Chapter 17 Managing MemoryUniData Monitoring/Configuring Tools . . . . . . . . . 17-4

udtconf Main Display . . . . . . . . . . . . . . . 17-4

Calculating udtconfig Parameters . . . . . . . . . . . 17-5

Checking Configuration Parameters . . . . . . . . . . 17-6

Saving Configuration Parameters . . . . . . . . . . . 17-6

Recalculating the Size of the CTL . . . . . . . . . . . 17-7

Viewing Current and Suggested Settings . . . . . . . . 17-7

Exiting udtconf . . . . . . . . . . . . . . . . . 17-8

Setting Shared Memory Parameters . . . . . . . . . . 17-9

shmconf: Main Display. . . . . . . . . . . . . . . 17-9

shmconf: Viewing Current and Suggested Settings . . . . . 17-10

shmconf: Recalculating the Size of CTL . . . . . . . . . 17-11

shmconf: Recalculating Other Parameters . . . . . . . . 17-11

Shared Memory and the Recoverable File System . . . . . 17-12

Analyzing UniData Configuration Parameters . . . . . . 17-12

Checking and Changing UniData Configuration Parameters . . 17-14

Checking Kernel Parameters . . . . . . . . . . . . . 17-16

sms . . . . . . . . . . . . . . . . . . . . . 17-16

Learning about Global Pages. . . . . . . . . . . . . 17-20

Learning about Local Control Tables . . . . . . . . . . 17-21

UNIX Monitoring Tools . . . . . . . . . . . . . . 17-23

UniData Configuration Parameters . . . . . . . . . . 17-24

UNIX Kernel Parameters . . . . . . . . . . . . . . 17-24

UniData Error Messages for smm . . . . . . . . . . . 17-25

inistering UniData on UNIX

Chapter 18 Managing ipc FacilitiesMessage Queues, Shared Memory, and Semaphores . . . . 18-4

UniData Log Files . . . . . . . . . . . . . . . . 18-7

Removing ipc Structures. . . . . . . . . . . . . . 18-8

Chapter 19 Managing Cataloged ProgramsUniBasic Source and Compiled Programs . . . . . . . . 19-4

UniBasic Compiled Programs . . . . . . . . . . . . 19-4

Cataloging UniBasic Programs . . . . . . . . . . . 19-5

Direct Cataloging . . . . . . . . . . . . . . . . 19-5

Local Cataloging . . . . . . . . . . . . . . . . 19-5

Global Cataloging . . . . . . . . . . . . . . . . 19-6

Managing Global Catalogs . . . . . . . . . . . . . 19-8

Contents of a Global Catalog . . . . . . . . . . . . 19-8

Verifying a Program Version . . . . . . . . . . . . 19-10

Listing Programs in Use . . . . . . . . . . . . . . 19-16

Creating an Alternate Global Catalog Space . . . . . . . 19-17

Files and Directories Created by newhome . . . . . . . 19-17

Procedure for Creating an Alternate Global Catalog Space . . 19-17

Chapter 20 CallBasic, CALLC, and makeudtLinking C Routines into UniData. . . . . . . . . . . 20-4

Overview . . . . . . . . . . . . . . . . . . . 20-4

Requirements . . . . . . . . . . . . . . . . . 20-4

Rebuilding for Troubleshooting . . . . . . . . . . . 20-5

makeudt . . . . . . . . . . . . . . . . . . . 20-6

File Examples . . . . . . . . . . . . . . . . . 20-7

Creating cfuncdef_user . . . . . . . . . . . . . . 20-10

Steps for Linking in C Functions . . . . . . . . . . . 20-11

Steps for Setting Up a Development Environment . . . . . 20-15

Accessing UniData from a C Program . . . . . . . . . 20-20

Requirements . . . . . . . . . . . . . . . . . 20-20

How CallBasic Works. . . . . . . . . . . . . . . 20-20

C Program Example . . . . . . . . . . . . . . . 20-22

UniBasic Subroutine Example . . . . . . . . . . . . 20-25

Steps for CallBasic . . . . . . . . . . . . . . . . 20-26

Chapter 21 General TroubleshootingCrashes and Restart Problems . . . . . . . . . . . . 21-4

UniData Crashes . . . . . . . . . . . . . . . . 21-4

Table of Contents ix

x Admin

UniData Cannot Start . . . . . . . . . . . . . . . 21-5

Response Problems in UniData . . . . . . . . . . . . 21-6

UniData Consistently Slow . . . . . . . . . . . . . 21-6

UniData is Hung . . . . . . . . . . . . . . . . . 21-6

Error Messages . . . . . . . . . . . . . . . . . 21-7

Common Error Messages . . . . . . . . . . . . . . 21-7

Chapter 22 Performance Monitoring and TuningPerformance Monitoring and Tuning . . . . . . . . . . . 22-3

UNIX Performance Considerations . . . . . . . . . . 22-4

UNIX Performance Monitoring . . . . . . . . . . . . 22-5

Tools . . . . . . . . . . . . . . . . . . . . . 22-5

Tips . . . . . . . . . . . . . . . . . . . . . 22-5

UniData Performance Factors . . . . . . . . . . . . 22-7

Database Design Considerations . . . . . . . . . . . 22-7

Using Alternate Key Indexes . . . . . . . . . . . . . 22-7

Sizing Static Hashed Files . . . . . . . . . . . . . . 22-7

Sizing Dynamic Hashed Files . . . . . . . . . . . . 22-8

UniBasic Coding Tips . . . . . . . . . . . . . . . 22-8

UniBasic Profiling . . . . . . . . . . . . . . . . 22-11

UniData Performance Monitoring: udtmon. . . . . . . . 22-15

udtmon: UniData User Statistics . . . . . . . . . . . 22-18

udtmon: File I/O Statistics . . . . . . . . . . . . . 22-19

udtmon: Program Control Statistics . . . . . . . . . . 22-21

udtmon: Dynamic Array Statistics . . . . . . . . . . . 22-24

udtmon: Lock Statistics . . . . . . . . . . . . . . 22-25

udtmon: Data Conversion Statistics . . . . . . . . . . 22-28

udtmon: Index Statistics . . . . . . . . . . . . . . 22-29

udtmon: Mglm Performance . . . . . . . . . . . . . 22-31

Appendix A UniData Configuration Parameters

Appendix B Environment Variables for UniData

Appendix C Configuring SSL for TelnetServer Side Configuration: . . . . . . . . . . . . . . . C-1


1Chapter

Introduction

Audience . . . . . . . . . . . . . . . . . . . . . 1 -4

1-2 Adm

IntroductionThe 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 UNIX. 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.

Note: Before you try repeating the examples in this manual, make sure that you haveset the environment variables UDTHOME and UDTBIN, and make sure that yourPATH includes udtbin. See “Configuring Your UniData System,” for informationabout setting these variables.

Many of the administrative functions you can execute from the command

line are available through UniAdmi. For more information, see UsingUniAdmin.

1-3

AudienceAdministering UniData on UNIX is intended for people whose responsibilities

include the following:

■ Tasks performed at the host level

■ Reviewing and modifying kernel configuration

■ Modifying file protections

■ Adding UNIX users

■ Creating directories

■ Starting and stopping UniData

■ Backing up UniData files

■ Tasks performed within UniData

■ Creating and managing UniData accounts

■ Optimizing UniData configuration

■ Customizing security

■ Managing files

■ Monitoring and accessing files, peripherals, and system

resources

1-4 Administering UniData on UNIX

2Chapter

UniData and UNIX Security

UNIX File Permissions . . . . . . . . . . . . . . . . 2 -4

Additional UNIX Access Modes . . . . . . . . . . . . . 2 -6

UNIX umask . . . . . . . . . . . . . . . . . . . 2 -8

UniData Default Permissions . . . . . . . . . . . . . . 2 -10

UniData Processes and root . . . . . . . . . . . . . . 2 -11

2-2 Adm

This chapter describes UNIX security mechanisms and outlines how these

are used by UniData. It is important to understand UNIX security, because

UNIX file permissions form the basis of UniData security.

2-3

UNIX File PermissionsIn UNIX, each file or directory has permissions set for the owner (called user),

for members of the group owner (called group), and for all other users except

root (called other). The root user has all access to all files on the system,

regardless of their owners or group owners.

UniData uses UNIX permissions as a principal security mechanism. The

following table shows what the UNIX permissions mean when applied to a

file.

Note: Scripts or compiled programs are called executables throughout this manual.

The meaning of the permissions is somewhat different when they are applied

to a directory, as shown in the following table.

Permission Description

r (read) Read or copy a file

w (write) Modify a file

x (execute) Execute a script or program

UNIX Permissions for Files

Permission Description

r (read) List the directory’s contents

w (write) Add or remove files from the directory

x (search) cd to the directory, or include it in a path

UNIX Permissions for Directories


The following screen shows a long listing for the contents of a UNIX

directory:

% ls -ldrwxrwxrwx 2 ump01 other 24 May 21 13:14 ACCOUNT-rw-rw-rw- 1 root sys 0 Apr 30 10:51 FileInfodrwxrwxrwx 12 root unisrc 4096 Apr 30 16:06 bindrwxrwxrwx 12 root unisrc 2048 May 17 18:40 demodrwxr-xr-x 2 root sys 1024 Apr 30 16:05 includedrwxr-xr-x 2 root unisrc 1024 Apr 11 12:23 libdrwxrwxrwx 3 root sys 1024 Apr 17 11:55 logsdrwxrwxrwx 4 root unisrc 1024 Apr 10 18:28 objcalldrwxrwxrwx 5 us_admin users 1024 May 1 12:50 ods-rw-r--r-- 1 root sys 7 Apr 11 12:22 parttbldrwxrwxrwx 4 root unisrc 1024 Apr 10 19:12 sybasedrwxrwxrwx 4 root unisrc 1024 May 20 19:31 sysdrwxr-xr-x 2 root unisrc 1024 Apr 30 15:58 work

Entries beginning with “d” are directories; entries beginning with “-” are

files. Permissions for owner, group, and all others are shown in the next nine

characters. For example, the directory ACCOUNT is owned by “ump01,”

and the group owner is “other.” The owner, “ump01,” members of the group

“other” and all other users all have read, write, and search permission on

ACCOUNT.

To delete a file from a directory, a user needs write permission to the

directory, but does not need any permissions to the file. On most UNIX

versions, if the user does not have write permissions to the file, the system

displays the octal format for the current permissions and asks for

confirmation to override them, as shown on the following screen:

% rm testfiletestfile: 644 mode ? (y/n)

On some systems, you can set an additional access mode called the “sticky

bit,” which prevents users from deleting a file unless they have write

permission on that file. See “Additional UNIX Access Modes” in this chapter

for more information.

Note: The UNIX commands ls, chmod, chown, and chgrp are used for viewing andmodifying file ownership and permissions. Refer to your host operating systemdocumentation for detailed information about these commands.

2-5

Additional UNIX Access ModesUNIX supports three additional file access modes, as shown in the following

table.

Warning: Setting SUID or SGID on executables allows users access they would notbe granted based on the permissions. These access modes, if not used with caution,can compromise the security of your system. Also, these access modes behavesomewhat differently in different UNIX versions. Review your host operating systemdocumentation before setting SUID or SGID.

The following screens show how to set these access modes, and what

permissions look like when each of them is set.

The first screen shows the sticky bit:

% ls -ltotal 2drwxrwxrwx 2 ump01 unisrc 24 May 21 13:48 testdir%% chmod a+t testdir% ls -ltotal 2drwxrwxrwt 2 ump01 unisrc 24 May 21 13:48 testdir%

Access Mode Description

t (sticky bit) Varies with UNIX version; when set on a directory,restricts delete access on files within the directory.

s (set UID or SUID) Set on executable files; allows a user to invoke theexecutable, which runs with the privileges of the owner ofthe file.

s (set GID or SGID) Set on executable files; allows a user to invoke theexecutable, which runs with the privileges of the owner ofthe group.

Additional UNIX Access Modes


The next screen shows how to set SGID on a file called testfile:

% ls -l-rwxrwxrwx 1 ump01 unisrc 0 May 21 15:58 testfile%% chmod g+s testfile% ls -l-rwxrwsrwx 1 ump01 unisrc 0 May 21 15:58 testfile%

The group owner must have x (execute) permission on the file, and you must

be logged in as the file owner or as root to set SGID.

The next screen shows how to set SUID on a file called newfile:

% ls -l-rwxrwxr-x 1 ump01 unisrc 0 May 21 16:03 newfile%% chmod u+s newfile% ls -l-rwsrwxr-x 1 ump01 unisrc 0 May 21 16:03 newfile%

The owner of the file must have x (execute) permission on the file, and you

must be logged in as the owner or as root to set SUID.

2-7

UNIX umaskThe UNIX umask command sets default permissions for file creation. umask

allows you to specify permissions that apply when a file is created. To use

umask, you need to know the octal values of the basic permissions (read,

write, execute), and the UNIX default permissions for files and directories.

The following table shows the octal values for the permissions and for

common combinations.

The UNIX default permissions for file creation are shown in the next table.

Permission Octal Value

read 1

write 2

execute (or search) 4

read+execute 5

read+write 6

write+execute 3

read+write+execute 7

UNIX Permissions (Octal Values)

Type UNIX Default Permission

File rw-rw-rw- (octal: 666)

Directory drwxrwxrwx (octal: 777)

UNIX Default Permissions for File Creation


The value of umask is also expressed in octal format, and its effect is shown

by subtracting the value from the UNIX default. For example, if you set

umask to 002 and create a file, the permissions on that file are represented by

the difference between the default (666) and umask (002), or 664. Permissions

of 664 translate to rw-rw-r--. The following screen shows three umask

settings and their effects:

% umask 022% touch umask.tst1% ls -l umask.tst1-rw-r--r-- 1 ump01 unisrc 0 May 21 17:43 umask.tst1% umask 222% touch umask.tst2% ls -l umask.tst2-r--r--r-- 1 ump01 unisrc 0 May 21 17:43 umask.tst2% umask 007% mkdir umask.tst3% ls -ldrwxrwx--- 2 ump01 unisrc 24 May 21 17:43 umask.tst3

Notice that, in the example, the UNIX touch command creates empty files.

Note: When a user invokes the UniData ECL CREATE.FILE command, UniDatasets file permissions in most cases according to the user’s current umask. Theexceptions are the directories for dynamic files and multilevel files and directories.Permissions for these are set to 775 octal (rwxrwxr-x).

Note: For security purposes, a system administrator can set a default value of umaskin any user’s .login or .profile file. However, if users have access to the UNIX prompt,they can override the default before entering UniData.

Refer to your host operating system documentation for detailed information

about the umask command.

2-9

UniData Default PermissionsWhen you install UniData software on your system, the installation process

sets the ownership of the files being installed to root. The installation process

then prompts you to enter a group, which must be a valid group defined on

your system. UniData then sets default permissions for all the files it installs.

For each file, the owner permissions apply to root. The group permissions

apply to all members of the group you specify in the installation procedure.

The final set of permissions applies to all other users on your system. The

following screen shows a long listing for the file

/usr/ud60/include/udtconfig, illustrating the default permissions set when

you install UniData.

% cd /usr/ud60/include% ls -l udtconfig-rw-r--r-- 1 root sys 809 Apr 30 16:05 udtconfig%

In this case, the file is owned by root, and the installation process sets the

group to sys. Root has read and write access to the file, and all other users

have read access only.

If you log in as root and create a new UniData account with the newacct

command, the system allows you to specify the owner and group for the

account. The system sets the owner and group owner accordingly.

You can customize the file permissions to meet specific needs for your

system. See Chapter 11, “Managing UniData Security,” for information about

customizing file protections.

UniData also allows you to fine-tune your system security by customizing

the VOC files in your UniData accounts and by granting specific privileges to

UniData SQL users via the UniData SQL GRANT command. See Chapter 11,

“Managing UniData Security,” for information about tuning UniData

security.

Note: The ECL SETFILE command lets you set pointers in the UniData VOC file toallow files to be shared among accounts or distributed among file systems. For eachfile, the permissions that control access are those at the location where the file resides,which may be different from those in the directory containing the VOC file.


UniData Processes and rootSince the principal UniData daemons, smm, sbcs, unirpcd, and cleanupd

must run as root, UniData must be started by root. Those daemons have all

access to all files on your system. (If you are using the Recoverable File

System (RFS), the RFS daemons also run as root.) For security reasons,

UniData users should not have root privileges. When a user enters UniData,

the user process (called a udt) runs under the UID of the user. Since the udt

process drives all file access, users can perform only actions allowed to them

by your system’s security, which consists of UNIX file permissions, the local

VOC file, and SQL privileges.

2-11

3Chapter

UniData and the UNIX FileSystem

UniData Directories and Files . . . . . . . . . . . . . . 3 -4

Files, Pointers, and Links . . . . . . . . . . . . . . . 3 -6

Creating Files . . . . . . . . . . . . . . . . . . 3 -6

Setting a UniData Pointer . . . . . . . . . . . . . . 3 -6

Setting an Environment Variable . . . . . . . . . . . 3 -8

Setting a UNIX Link. . . . . . . . . . . . . . . . 3 -9

UniData Hashed Files . . . . . . . . . . . . . . . . 3 -11

Static Files . . . . . . . . . . . . . . . . . . . 3 -11

Dynamic Files . . . . . . . . . . . . . . . . . . 3 -12

Sequentially Hashed Files . . . . . . . . . . . . . . 3 -14

DIR-Type Files. . . . . . . . . . . . . . . . . . 3 -16

Multilevel Files . . . . . . . . . . . . . . . . . 3 -17

Multilevel Directory Files . . . . . . . . . . . . . . 3 -18

Index Files and Index Log Files . . . . . . . . . . . . 3 -19

UniData and tmp Space . . . . . . . . . . . . . . . . 3 -21

Changing TMP in the udtconfig File . . . . . . . . . . 3 -22

Setting an Environment Variable . . . . . . . . . . . 3 -22

3-2 Adm

This chapter describes relationships between UniData file types and UNIX

file types, and outlines the structures of various types of UniData files.

3-3

UniData Directories and FilesUniData uses UNIX files, directories, and links to organize its database. A

UniData account is, in simplest terms, a UNIX directory that contains a VOC

file, its dictionary (D_VOC), and other files created by the newacct command.

The VOC file serves as the central repository for information about the

account. It contains direct information (such as commands and keywords

you can use) and pointers to menus, data, dictionary files, and cataloged

programs. See Chapter 10, “Managing UniData Accounts,” for information

about the newacct command.

Note: The data and dictionary files referenced in a VOC file are not necessarilylocated in the same UNIX directory as the VOC file. You can list the files that aredefined for a UniData account by listing VOC entries. It is normal for the resultingfile list to differ from a UNIX or UniData listing (ls) of the files actually located inthe directory.

In UniData, as in UNIX, a directory is treated as a type of file. The following

table shows the relationships between UniData file types and UNIX file

types.

UniData File Type UNIX File Type

Static hashed file Data file.

Dynamic hashed file UNIX directory that contains data files and overflow files(or UNIX symbolic links to these) and indexes (if any arebuilt). The data, overflow, and index files are UNIX datafiles.

Sequentially hashedfile

UNIX directory that contains data files and overflow filesand indexes whose records are stored in sequential orderbased on the @ID. A sequentially hashed file has a fixedmodulo, just like a static hashed file.

Dictionary (DICT) file(A static hashed file)

Data file that contains attribute and record definitions fora UniData file.

Alternate key index(for static file)

Data file located in the same directory at the same levelas the file being indexed.

UniData and UNIX Files


You can define links and pointers within UniData to reference files located in

different UNIX file systems. You can also define environment variables for

the paths of UniData accounts, and then use those variables when setting

pointers in VOC entries.

Alternate key index(for dynamic file)

Data file located in the dynamic file directory along withthe data file and the overflow file.

DIR file UNIX directory. You can copy records from another fileinto a DIR file with the ECL COPY command; each suchrecord is stored as a UNIX text file.

MULTIFILE(multilevel file)

UNIX directory that contains one or more UniDatahashed files. There is one dictionary for the MULTIFILE,which is shared by all hashed files in the directory. Youcan copy records from one file into any other file withinthe directory.

MULTIDIR(multilevel DIR file)

UNIX directory that contains one or more subdirectories.There is one dictionary for the MULTIDIR, which isshared by each subdirectory. If you copy records fromanother file into one of the subdirectories, each record isstored as a UNIX text or data file.

UniData File Type UNIX File Type

UniData and UNIX Files (continued)

UniData Directories and Files 3-5

Files, Pointers, and Links

Creating Files

By default, the physical location of a UniData file is the UniData account

directory where the file was created. The following screen shows the ECL

CREATE.FILE command (creating a static file) and the ECL LS command

(displaying the account directory).

UniData Release 6.0 Build: (4085)(c) Copyright IBM Corporation 2002.All rights reserved.

Current UniData home is /disk1/ud60/.Current working directory is /disk1/ud60/demo.

: CREATE.FILE STATIC.TST 5Create file D_STATIC.TST, modulo/1,blocksize/1024Hash type = 0Create file STATIC.TST, modulo/5,blocksize/1024Hash type = 0Added "@ID", the default record for UniData to DICT STATIC.TST.: LSBP D_SAVEDLISTS D__REPORT _SAVEDLISTS _REPORT_CTLG D_STATIC.TST D__SCREEN STATIC.TST _SCREEN_D_BP D_VOC D__V__VIEW VOC __V__VIEWD_CTLG D__HOLD_ D_savedlists_HOLD_ savedlistsD_MENUFILE D__PH_ MENUFILE _PH_

Setting a UniData Pointer

You can set a pointer in a UniData VOC file to a data file in another UniData

account. This feature allows users working in different UniData accounts to

share data files. There are two points to remember about setting a VOC

pointer:

■ A VOC pointer is internal to UniData. It is not the same thing as a

UNIX link. Because of this, even backup utilities that follow symbolic

links do not automatically follow VOC pointers. See “Setting a UNIX

Link” in this chapter for more information about UNIX links.


■ Setting a VOC pointer does not alter the physical location of the data

file. Although you can access the file from the directory where the

pointer resides, the physical location of the file and its indexes

remains unchanged.

The following screen shows the ECL SETFILE command (setting a VOC

pointer):

: SETFILE /usr/ud60/demo/INVENTORY INVENTORYEstablish the file pointerTree name /usr/ud60/demo/INVENTORYVoc name INVENTORYDictionary name /usr/ud60/demo/D_INVENTORYOk to establish pointer(Y/N) = YSETFILE completed.: LIST INVENTORY WITH FEATURES LIKE "Portable..." FEATURESLIST INVENTORY WITH FEATURES LIKE "Portable..." FEATURES 18:56:11May 21 2002 1INVENTORY. Features......................

39300 Portable, Sports Model 12006 Portable Color Ink Jet 39400 Portable Model 39000 Portable Sports Model 38000 Portable, 5-disk 52070 Portable Color, 3 ppm 52060 Portable Ink Jet, 5 ppm 10008 Portable, B/W, 6 ppm 30000 Portable Clock Radio 10009 Portable Color, 6 ppm 39100 Portable, Basic Functions11 records listed: LSBP D_SAVEDLISTS D__REPORT _SAVEDLISTS _REPORT_CTLG D_STATIC.TST D__SCREEN STATIC.TST _SCREEN_D_BP D_VOC D__V__VIEW VOC __V__VIEWD_CTLG D__HOLD_ D_savedlists _HOLD_ savedlistsD_MENUFILE D__PH_ MENUFILE _PH_

Notice that you can set the pointer and then access the file. However, the

physical location of the file remains in /usr/ud60/demo, and the

INVENTORY file is not included in the LS display.

Note: See the UniData Commands Reference manual and Using UniData for moreinformation about creating and listing UniData files.

Files, Pointers, and Links 3-7

Setting an Environment Variable

You can replace the “path” portion of a file reference in a VOC entry with a

UNIX environment variable. This makes it easy to move a file or files when

necessary without having to change each associated VOC entry. The

following screen shows how to set an environment variable for the UniData

demo account:

% setenv DEMO /usr/ud60/demo% printenv DEMO/usr/ud60/demo% cd $DEMO% pwd% /usr/ud60/demo%

Notice that you can use the environment variable to access the demo

database.

Note: The preceding example shows the C shell syntax for setting the environmentvariable. If you are using the Bourne or Korn shell, use the following syntax:

DEMO=/usr/ud60/demo; export DEMO

The following screen shows a VOC entry that uses the environment variable

to identify a file in the demo database:

: WHERE/users/testacct: !printenv DEMO/usr/ud60/demo: CT VOC INVENTORYVOC:

INVENTORY:F@DEMO/INVENTORY@DEMO/D_INVENTORY:

When users access the INVENTORY file, UniData uses the environment

variable to locate the file. If you move the entire demo database, you can

simply redefine the environment variable to the new path. Users can

continue to access the files.

Note: If you use an environment variable in a VOC entry, precede the environmentvariable with the @ character as shown in the previous example. The @ characterdirects UniData to handle the path reference with the environment variable.


Warning: You can use environment variables only in VOC entries for files. Youcannot use them in other types of entries that include file paths (for instance, catalogpointer items).

Setting a UNIX Link

You can create a pointer to a file in another account directory by setting a

symbolic link at the UNIX level. When you set a symbolic link, UNIX creates

an entry in your current working directory that points to the location you

linked to. The following screen shows how to set a symbolic link to a UniData

file in another account:

% pwd/users/ump01/testacct% ln -s /usr/ud60/demo/ORDERS ORDERS% ln -s /usr/ud60/demo/D_ORDERS D_ORDERS: udt

UniData Release 6.0 Build: (4085)(c) Copyright IBM Corporation 2002.All rights reserved.

Current UniData home is /disk1/ud60/.Current working directory is /users/ump01/testacct.: LSBP D_ORDERS D__REPORT_ ORDERS _REPORT_CTLG D_SAVEDLISTS D__SCREEN_ SAVEDLISTS _SCREEN_D_BP D_VOC D___V__VIEW VOC __V__VIEWD_CTLG D__HOLD_ D_savedlists _HOLD_ savedlistsD_MENUFILE D__PH_ MENUFILE _PH_:

Notice that ORDERS and D_ORDERS appear in the LS output. UNIX creates

an entry in the current working directory for the link, although the ORDERS

file remains physically located in /usr/ud60/demo.

Files, Pointers, and Links 3-9

To access ORDERS from the current account, you must add a VOC entry for

the file. You can use SETFILE (by entering SETFILE ORDERS ORDERS at the

colon prompt), or you can use AE, as shown in the following example:

: LIST ORDERS WITH ORD_DATE LIKE "...1996"Not a filename : ORDERS: AE VOC ORDERSTop of New "ORDERS" in "VOC".*--: I001= F002= ORDERS003= D_ORDERS*--: FIFiled "ORDERS" in file "VOC".LIST ORDERS WITH ORD_DATE LIKE "...1996" ORD_DATELIST ORDERS WITH ORD_DATE LIKE "...1996" ORD_DATE 11:37:30 May 222002 1 OrderORDERS.... Date......

912 01/13/1996 941 01/14/1996 830 01/24/1996 970 01/15/1996 834 01/24/1996

Notice that even though ORDERS appeared in the LS output, you need to

add a VOC entry to define the file to your current UniData account.

Note: Refer to your host operating system documentation for additional informationabout UNIX symbolic links. Refer to Using UniData for additional informationabout the VOC file.


UniData Hashed Files

Static Files

Hashed files are binary data files. They cannot be read by text editors external

to UniData. Each UniData hashed file consists of a file header and one or

more groups of data. UniData supports two proprietary hashing algorithms,

which determine which data groups contain each record. Hashing allows

direct access to a record by translating its record key into its location in a data

file. The following screen shows some characteristics of a UniData static

hashed file:

: LSAE_COMS D_BP D_VOC D_savedlists _HOLD_AE_SCRATCH D_CTLG D__HOLD_ MENUFILE _PH_BP D_MENUFILE D__PH_ ORDERS_REPORT_CTLG D_ORDERS D__REPORT_ SAVEDLISTS_SCREEN_D_AE_COMS D_SAVEDLISTS D__SCREEN_ STATIC.TEST__V__VIEWD_AE_SCRATCH D_STATIC.TEST D___V__VIEW VOCsavedlists: !ls -l STATIC.TEST-rw-rw-rw- 1 claireg unisrc 4096 May 22 11:41 STATIC.TEST: !file STATIC.TESTSTATIC.TEST: data

When you create a static hashed file, you specify the modulo (number of

groups) and the block size of the file. Static hashed files overflow if one or

more groups cannot store all the data (level 1 overflow) or keys (level 2

overflow) of records hashed to the group. UniData adds overflow blocks to

the file, but subsequent accessing and updating of records is then resource-

intensive and performance suffers. UniData provides utilities to resize static

files by adding more groups (changing the modulo) or by making the groups

larger (changing the block size).

Points to Remember About Static Files

Remember the following points about static files:

■ A UniData static file is a binary data file.

UniData Hashed Files 3-11

■ You define the size of a static file when you create the file, by

specifying the number and size of groups in the file.

■ When you add records to the file, each record is hashed to a group

using a proprietary hashing algorithm.

■ Static files can overflow, causing performance problems.

■ A static hashed file cannot be larger than 2 GB. If a file exceeds 2 GB,

you must make it a dynamic file.

See Chapter 12, “Managing UniData Files,” for more information about file

management commands.

Dynamic Files

A dynamic file is a UNIX directory file, containing index, data, and overflow

files (and/or symbolic links to these). UniData dynamic files can grow and

shrink with respect to modulo (number of groups) as records are added and

deleted. Dynamic files can also expand beyond the limits of a single UNIX file

system. The following screen shows some characteristics of a simple dynamic

file:

: CREATE.FILE DYNAMIC.TEST 1 DYNAMIC1 is too small, modulo changed to 3.Create file D_DYNAMIC.TEST, modulo/1,blocksize/1024Hash type = 0Create dynamic file DYNAMIC.TEST, modulo/3,blocksize/1024Hash type = 0Split/Merge type = KEYONLYAdded "@ID", the default record for UniData to DICT DYNAMIC.TEST.: LSBP D_DYNAMIC.TEST D__PH_ MENUFILE_REPORT_CTLG D_MENUFILE D__REPORT_ SAVEDLISTS_SCREEN_DYNAMIC.TEST D_SAVEDLISTS D__SCREEN_ VOC__V__VIEWD_BP D_VOC D___V__VIEW _HOLD_savedlistsD_CTLG D__HOLD_ D_savedlists _PH_vocupgrade: !ls -l DYNAMIC.TESTtotal 10-rw-rw-rw- 1 terric unisrc 4096 Jun 25 17:13 dat001-rw-rw-rw- 1 terric unisrc 1024 Jun 25 17:13 over001


Notice that the UniData dynamic file is a UNIX directory, containing UNIX

files dat001 and over001. The dat001 file is a UniData hashed file, and the

blocks in over001 are linked to groups in the dat001 file.

The dat001 File

The dat001 file is also called the primary data file. As you add records to a

dynamic file, UniData hashes the keys to groups in dat001. As the file fills up,

UniData adds additional groups to the dat001 file. If the current file system

fills up or if dat001 grows larger than a UniData limit, UniData creates a

dat002 file. If dat002 is in another file system, UniData creates a UNIX link to

the dat002 file in the original dynamic file.

The over001 File

As you add records to a dynamic 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 over002 file is in

a file system different from the current one, UniData creates a UNIX link to

over002 in the original dynamic file.

If you specify the OVERFLOW keyword 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 on. When the file is cleared, UniData maintains this overflow structure.

Points to Remember About Dynamic Files

Remember the following points about dynamic files:

■ A UniData dynamic file is a UNIX directory. The directory contains

files or UNIX links.

■ Dynamic files expand and shrink with respect to modulo. Expansion

and shrinking take place automatically during UniData processing.

■ Dynamic files can expand across UNIX file systems. The original

dynamic file contains UNIX links to any “part files” that are created

on other file systems.


■ Because the parts of a dynamic file are related by symbolic links, you

need a backup utility that follows symbolic links to guarantee

complete backups of dynamic files.

Note: Chapter 12, “Managing UniData Files,” includes detailed information aboutthe behavior of UniData dynamic files.

Sequentially Hashed Files

A 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 File


sequentially 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 File

As 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 over002 file resides in a different file system than the over001 file,

UniData creates a link to over002 in the original sequentially hashed file.


If the sequentially hashed file has level 2 overflow, the file should be rebuilt

using the shfbuild command.

The gmekey File

Each sequentially hashed file contains a static, read-only file called the

gmekey file. This file is read 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 blocksize multiplier] [-i infile] outfile

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".

For more information about sequentially hashed files, see AdministeringUniData.


DIR-Type Files

A UniData DIR-type file is a UNIX directory that contains UNIX text or data

files. Each UNIX 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 screen shows the structure of a sample BP file:

: LIST BPLIST BP 12:08:40 May 22 2002 1BP........

MAINPROG_MAINPROGSUBR_SUBR4 records listed

In the example, MAINPROG and SUBR are UniBasic source files.

_MAINPROG and _SUBR are compiled programs.


Multilevel Files

A UniData multilevel (LF-type) file is a UNIX 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: !ls -l MULTI1total 24-rw-rw-rw- 1 claireg unisrc 4096 May 22 12:31 MULTI1-rw-rw-rw- 1 claireg unisrc 4096 May 22 12:31 MULTI2-rw-rw-rw- 1 claireg unisrc 4096 May 22 12:31 MULTI3: LIST MULTI1,MULTI2 WITH F1 = PALIST MULTI1,MULTI2 WITH F1 = PA 12:46:08 May 22 2002 1

ECLTYPECPlistdictCTSP.OPENLISTDICT6 records listed

Note: If the subfile of a multilevel file has the same name as the directory, you can usethe directory name only to access the subfile. For instance, LIST MULTI1 is correctsyntax if the directory MULTI1 contains subfile MULTI1.

Points to Remember about Multilevel Files

Remember the following points about multilevel files:

■ A UniData multilevel file is a UNIX directory that contains UniData

hashed files.

■ Each multilevel file can 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

applications. However, accessing and maintaining multilevel files is

less efficient than accessing and maintaining ordinary static or

dynamic files. The leveled structure requires more system resources

to read and update these files. For this reason, we recommend using

ordinary static or dynamic hashed files rather than multilevel files

whenever possible. You can share a single dictionary among

UniData files by modifying the VOC entries for each file to reference

the same dictionary.

Multilevel Directory Files

A UniData multilevel directory (LD) file is a UNIX directory. The UNIX

directory contains one or more UNIX subdirectories (UniData DIR type files).

All of the DIR files share the same dictionary. To access a record, you must

specify both the multilevel directory file and the DIR file where the record

resides. The following screen shows some characteristics of a multilevel

directory file:

: LSAE_COMS D_CTLG D_VOC MULTI1 _REPORT_AE_SCRATCH D_DYNAMIC.TEST D__HOLD_ MULTID _SCREEN_BP D_MENUFILE D__PH_ ORDERS __V__VIEWCTLG D_MULTI1 D__REPORT_ SAVEDLISTS savedlistsDYNAMIC.TEST D_MULTID D__SCREEN_ STATIC.TESTD_AE_COMS D_ORDERS D___V__VIEW VOCD_AE_SCRATCH D_SAVEDLISTS D_savedlists _HOLD_D_BP D_STATIC.TEST MENUFILE _PH_: !ls -l MULTIDtotal 4drwxrwxr-x 2 claireg unisrc 24 May 22 12:49 TEST1drwxrwxr-x 2 claireg unisrc 24 May 22 12:49 TEST2: LIST MULTID,TEST1LIST MULTID,TEST1 12:51:57 May 22 2002 1MULTID....

MAINPROG_MAINPROGSUBR_SUBR4 records listed

Note: If a subdirectory of a multilevel directory file has the same name as the maindirectory, you can use the main directory name to access the subdirectory. Forinstance, LIST MULTID is correct syntax if the directory MULTID contains thesubdirectory MULTID.


Points to Remember about Multilevel Directory Files

Remember the following points about multilevel directory files:

■ A UniData multilevel directory file is a UNIX directory that contains

UniData DIR files (UNIX subdirectories).

■ All of the DIR files in a multilevel file share the same dictionary.

■ Each record in a multilevel directory is a UNIX file.

■ UniData supports multilevel directory files to simplify conversion of

legacy applications. However, accessing and maintaining multilevel

directory files is 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 among UniData DIR files by

modifying the VOC entries for each file to reference the same

dictionary.

Index Files and Index Log Files

UniData creates an index file whenever a user creates the first alternate key

index on a UniData hashed file. Index information is stored in B+ tree format.

UniData index files are UNIX 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 a UniData data file is updated, its associated indexes are

updated. 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 for a file,

UniData creates a log file and stores all updates to it. The ECL

UPDATE.INDEX command allows you to apply updates from index logs to

indexes in batch mode, and the ECL ENABLE.INDEX command turns

automatic updating back on. Either CLEAR.FILE or DELETE.INDEX (with

the ALL option) removes the index log file.


Note: See the UniData Commands Reference for additional information about indexhandling commands.

Index-Related Files for a Static Hashed File

For 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 screen shows a

sample account where a static file named STATIC.TEST has been indexed:

: LSAE_COMS D_CTLG D_VOC MULTI1 _PH_AE_SCRATCH D_DYNAMIC.TEST D__HOLD_ MULTID _REPORT_BP D_MENUFILE D__PH_ ORDERS _SCREEN_CTLG D_MULTI1 D__REPORT_ SAVEDLISTS __V__VIEWDYNAMIC.TEST D_MULTID D__SCREEN_ STATIC.TEST savedlistsD_AE_COMS D_ORDERS D___V__VIEW VOCx_STATIC.TESTD_AE_SCRATCH D_SAVEDLISTS D_savedlists X_STATIC.TESTD_BP D_STATIC.TEST MENUFILE _HOLD_

X_STATIC.TEST is the index file for the data file STATIC.TEST, and

x_STATIC.TEST is the index log file.

Index-Related Files for a Dynamic Hashed or Sequentially Hashed File

For a dynamic hashed or sequentially hashed file, UniData creates both the

index file and the index log file in the dynamic file directory. The following

screen shows a sample account where a dynamic file named DYNAMIC.TST

has been indexed:

: LSAE_COMS D_CTLG D_VOC MULTI1 _REPORT_AE_SCRATCH D_DYNAMIC.TEST D__HOLD_ MULTID _SCREEN_BP D_MENUFILE D__PH_ ORDERS __V__VIEWCTLG D_MULTI1 D__REPORT_ SAVEDLISTS savedlistsDYNAMIC.TEST D_MULTID D__SCREEN_ STATIC.TESTD_AE_COMS D_ORDERS D___V__VIEW VOCD_AE_SCRATCH D_SAVEDLISTS D_savedlists _HOLD_D_BP D_STATIC.TEST MENUFILE _PH_: LS DYNAMIC.TESTdat001 idx001 over001 xlog001

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.


UniData and tmp SpaceUniData uses temporary disk storage for a variety of purposes including:

■ Storing work files for UniQuery SORT and for sorting with the

ORDER BY option in UniData SQL

■ Building print files

■ Using DELETE.FILE to delete UniData files

■ Storing log and output files for layered products

■ Storing work files for commands such as LIST.READU, listuser,

BUILD.INDEX, UPDATE.INDEX, SP.EDIT

■ Storing work files for file repair tools

■ Storing work files for the UniBasic compiler

By default, UniData uses the UNIX partition /tmp for temporary disk

storage. You can define an alternate temporary disk storage location by

setting an environment variable called TMP, or by changing the TMP

parameter in the udtconfig file, located in /usr/ud60/include. If both are set,

the environment variable overrides the configuration parameter.

Note: You can override the default location for many UniData work files. However,there are some that cannot be overridden. Among these are working files used bySP.EDIT (copies of hold files you are editing), working files used by UniData SQLfor sorting with the ORDER BY clause, and working files for the UniBasic compiler.UniData creates these files in /tmp regardless of any other setting.

In most cases, UniData removes its temporary work files when they are no

longer needed. There are certain files that UniData does not remove,

including output files it generates from filetools. Because the default /tmp is

routinely cleared on many systems, you should consider defining alternate

temporary storage if you know you are going to be repairing files, for

example. Otherwise, you risk losing crucial data if the workfiles are removed

before you are finished.

UniData and tmp Space 3-21

Changing TMP in the udtconfig File

The following screen shows a sample udtconfig file with the TMP parameter

changed:

## Unidata Configuration Parameters## Section 1 Neutral parameters# These parameters are required by all Unidatainstallations.## 1.1 System dependent parameters, they should not be changed.LOCKFIFO=1SYS_PV=3

# 1.2 Changable parametersNFILES=60NUSERS=40WRITE_TO_CONSOLE=0TMP=/users/tmp/

.

.

.

Notice that the path name for TMP ends with the “/” character. This is

required.

Setting an Environment Variable

You can set the environment variable TMP in individual users’ .login or

.profile files to define alternate temporary disk storage for those users. A user

with access to a UNIX prompt can set the environment variable as well.

In the C shell, use the following commands to set and display the TMP

environment variable:

setenv TMP directory-name/

printenv TMP

In the Bourne or Korn shell, use the following commands to set and display

the TMP environment variable:

TMP=directory-name/;export TMP

printenv TMP


4Chapter

UniData and Daemons

What Is a Daemon? . . . . . . . . . . . . . . . . . 4 -4

Principal UniData Daemons . . . . . . . . . . . . . . 4 -5

Shared Basic Code Server (sbcs). . . . . . . . . . . . 4 -5

Shared Memory Manager (smm) . . . . . . . . . . . 4 -6

Clean Up (cleanupd) . . . . . . . . . . . . . . . 4 -7

UniRPC Service (unirpcd). . . . . . . . . . . . . . 4 -8

sync Daemon . . . . . . . . . . . . . . . . . . 4 -8

Monitoring UniData Daemons . . . . . . . . . . . . . 4 -9

showud Command . . . . . . . . . . . . . . . . 4 -9

Log Files. . . . . . . . . . . . . . . . . . . . 4 -9

4-2 Adm

This chapter explains what UNIX daemons are, and describes daemons

specific to UniData.

4-3

What Is a Daemon?A daemon is a background process that performs a specific task or set of

tasks. Daemons wait in the background until they receive a request for their

specific function. A number of standard UNIX daemons run on every UNIX

platform to control system processes, schedule commands, handle print

requests, and perform other similar functions. Refer to your host operating

system documentation for detailed information about the UNIX daemons

that run on your system.


Principal UniData DaemonsThree UniData daemons control your UniData environment. All three of

these UniData daemons run as root. When a user starts a UniData session, the

user’s process, called a udt, communicates with the daemons. The udt runs

with the permissions valid for the user, preventing inappropriate file access

by the UniData daemons.

■ Lock tracking — smm records all UniBasic locks and semaphore

locks, identifying which UniData user holds each.

■ Process cleanup — At periodic intervals, the cleanupd daemon

checks the cleanupd daemon 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 you execute 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 yet, 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.

Principal UniData Daemons 4-5

■ Controlling shared memory—The sbcs daemon can attach up to 20

shared memory segments. (On some platforms sbcs cannot attach 20

segments because the operating system imposes a lower limit. For

instance, AIX allows a process to attach only 10 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 UNIX when it no longer needs the memory.

■ Process cleanup — At periodic intervals, the sbcs process checks the

cleanupd daemon 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, the program is removed 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.

Note: See Chapter 19, “Managing Cataloged Programs,”, for additional informationabout sbcs.

Shared Memory Manager (smm)

The shared memory manager, smm, builds and manages structures and

tables within shared memory. UniData starts smm when you execute startud,

and stops it when you execute stopud.

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 in to UniData. smm also displays warning messages

when a license is about to expire.

■ User process tracking — When a user logs in 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.

■ Process cleanup—At periodic intervals, the smm process checks the

cleanupd daemon 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. See Chapter

5, “UniData and Memory,”, and Chapter 7, “Managing Memory,” for more

information about smm.

Clean Up (cleanupd)

The clean up daemon, cleanupd, detects terminated user processes at check

time intervals. If cleanupd detects a terminated process, internal flags are set.

The smm and sbcs daemons periodically check to see if cleanupd has set

internal flags. If these daemons detect flags, each daemon performs the

necessary cleanup and resets its own flag to zero. The cleanupd daemon

performs clean up that is not handled by smm or sbcs. When the smm and

sbcs daemons have reset their flags to zero, the cleanupd daemon resets its

flag to zero, makes the user process id available, and frees the local control

table.

Principal UniData Daemons 4-7

UniRPC Service (unirpcd)

The UniRPC service is used by UniAdmin, UniObjects, UniObjects for Java,

UniData ODBC, UniOLEDB, and UCI to communicate with UniData on the

server.

sync Daemon

If you notice significant performance degradation during a checkpoint when

running the Recoverable File System (RFS), you can start sync daemons by

setting the udtconfig parameters N_SYNC and SYNC_TIME. Sync daemons

periodically flush updated pages from the system buffer to the log files,

reducing the amount of time it takes to complete a checkpoint.

N_SYNC determines the number of sync daemons UniData starts.

SYNC_TIME defines, in seconds, the amount of time the sync daemons wait

before scanning the system buffer for updated pages.

Note: The Recoverable File System creates and uses a group of additional UniDatadaemons. If you are using the Recoverable File System, refer to Administering theRecoverable File System for information about those daemons.


Monitoring UniData DaemonsUniData provides a command and several log files to monitor the status of

the daemons.

showud Command

The system-level command showud displays UniData daemons that are

currently running. The following screen shows output from showud:

# showud UID PID TIME COMMAND root 19503 0:00 /disk1/ud60/bin/aimglog 0 27543 root 19504 0:00 /disk1/ud60/bin/aimglog 1 27543 root 19505 0:00 /disk1/ud60/bin/bimglog 2 27543 root 19506 0:00 /disk1/ud60/bin/bimglog 3 27543 root 19494 0:06 /disk1/ud60/bin/cleanupd -m 10 -t 20 root 19500 1:14 /disk1/ud60/bin/cm 27543 root 19490 0:00 /disk1/ud60/bin/sbcs -r root 19499 0:01 /disk1/ud60/bin/sm 60 10705 root 19483 0:05 /disk1/ud60/bin/smm -t 60 root 19525 0:00 /disk1/unishared/unirpc/unirpcd#

Log Files

The sbcs, cleanupd, and smm daemons 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.

Daemon/Process Routine Messages Error Messages

lcp $UDTBIN/lcp.log $UDTBIN/lcp.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

Log Files for UniData Daemons and Processes

Monitoring UniData Daemons 4-9

See Chapter 9, “Starting, Stopping, and Pausing UniData,” for additional

information and examples.

The udt.errlog file

If a UniData process encounters file corruption in a data file during

processing, the process 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,Sep 12 12:44:461:grpno error in U_blkread for file 'TEST', key '', number=3

udtno=1,pid=937,uid=1172,cwd=/home/claireg,Sep 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,Sep 12 12:44:461:read_all_block_in_group error in U_gen_read_group for file ' ',key ' ', number=0


5Chapter

UniData and Memory

UNIX and Shared Memory . . . . . . . . . . . . . . . 5 -4

UniData and Shared Memory . . . . . . . . . . . . . . 5 -5

smm and Shared Memory. . . . . . . . . . . . . . 5 -5

sbcs and Shared Memory . . . . . . . . . . . . . . 5 -13

Self-Created Segments . . . . . . . . . . . . . . . 5 -13

UniData and the UNIX Kernel . . . . . . . . . . . . 5 -14

5-2 Adm

This chapter describes how UniData interacts with the UNIX kernel to

configure, attach, and release shared memory.

5-3

UNIX and Shared MemoryShared memory is a region of memory that one or more processes may access.

Shared memory resides on a UNIX system outside the address space of any

process. It is partitioned into segments, depending on the configuration of

the system. As a process requires memory, the process attaches a segment to

its own address space. Processes use UNIX system calls to create, attach, and

release shared memory segments.

UNIX kernels define certain limits, such as the maximum and minimum size

of a shared memory segment and the maximum number of shared memory

segments the system supports. The names of these kernel parameters vary

from system to system. The following table lists kernel parameters related to

shared memory on an HP-UX system.

Note: Kernel configurations vary among UNIX versions. In some UNIX versions(AIX for example), all resources are allocated dynamically, and the systemadministrator has limited ability to affect the configuration. Some UNIX versionsalso have fixed limits on some parameters (for instance, AIX, where shmseg is 10).Other UNIX versions allow the system administrator to change parameter values,but procedures vary from system to system. Refer to your host operating systemdocumentation for detailed information about your UNIX kernel.

Note: You can distinguish between UNIX kernel parameter names and UniDataconfiguration parameter names in this manual. UNIX kernel parameter names are inlowercase (for instance, shmmax) and UniData parameters are in uppercase (forinstance, SHM_MAX_SIZE).

UNIX Parameter Description

shmmax The size, in bytes, of the largest shared memory segmentthe system supports.

shmmni The maximum number of shared memory segments thesystem supports.

shmseg The maximum number of shared memory segments thesystem can assign to one process.

UNIX Parameters for Shared Memory


UniData and Shared MemoryUniData interacts with UNIX shared memory by using UNIX system calls,

UniData daemons, and UniData configuration parameters (within the limits

imposed by the host UNIX system) to build its own structures in shared

memory.

UniData, like UNIX, defines shared memory segments that can be attached

by UniData processes. The sbcs daemon creates shared memory structures

for storing active globally cataloged UniBasic programs.

See Chapter 19, “Managing Cataloged Programs,” for additional information

about sbcs.

The smm daemon creates shared memory structures for internal tables

required by UniData processes. UniData processes request memory for:

■ Buffering UniBasic variables

■ Storing intermediate results

■ Storing a current modulo table for dynamic files

Note: The Recoverable File System (RFS) makes use of a specially allocated region ofmemory called the system buffer. If you are using RFS, refer to Administering theRecoverable File System for information about the system buffer.

smm and Shared Memory

The smm daemon creates shared memory segments as needed. The size and

characteristics of segments smm creates are determined by UniData

configuration parameters. Whenever UniData is started, UniData reads the

udtconfig file, located in /usr/ud60/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 optimize the efficiency of memory use by

releasing unneeded shared memory pages back to UNIX.

UniData and Shared Memory 5-5

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

execute the stopud command.

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

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 Table

Memory Information

Control Information

localcontroltable


The following table describes the structures in the CTL.

CTL Structure Description

GI Segment header; also called general information table.

GCTs (global controltables)

Each GCT records the use of global pages in a sharedmemory segment. UniData determines the number ofGCTs in the CTL by the configuration parameterSHM_GNTBLS. SHM_GNTBLS must not exceed thekernel parameter shmmni.

LCTs (local controltables)

Each LCT records the shared memory activity of aUniData process group. UniData determines the numberof LCTs in the CTL by the configuration parameterNUSERS. Each LCT comprises four subtables: PI, CT, MI,and CI. A process group is related to a process groupleader, which can be a udt or SQL session, or a userexecuting UniData system-level commands from a UNIXprompt.

PI (processinformation) table

Each PI table registers all processes within a processgroup.

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

MI (memoryinformation) table

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

CI (controlinformation) table

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

Structures Within UniData’s 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.

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:

((2+SHM_GNPAGES)*4)*SHM_GNTBLS

3. Compute the space (in bytes) needed for LCTs:

((96+(4*SHM_LPINENTS)+

(12*LMINENTS)+(8*SHM_LCINENTS))*NUSERS

4. Add the values from the first three steps.

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

See Chapter 17, “Managing Memory,” for more information.

Parameter Description

SHM_GNTBLS The number of GCTs in the CTL, which is also themaximum number of shared memory segments thatUniData can attach at a time.

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

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

SHM_LPINENTS The number of entries in the PI table of each LCT, which isalso the number of processes that can be included in aUniData process group.

SHM_LCINENTS The number of entries available in the CI table of eachLCT; this is the maximum number of local memorysegments that a process group can use at one time. A localsegment is made up of one or more contiguous localpages.

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

Configuration Parameters for CTL Structures


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

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 requesting processes’ LCT. When the requesting

process has finished 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 smm’s 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

UNIX 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 ofshared memory.

SHM_GPAGESZ The size (in 512-byte blocks) of a global page of sharedmemory. SHM_GPAGESZ must be an integral multiple ofSHM_LPAGESZ. Divide SHM_GPAGESZ bySHM_LPAGESZ to obtain the number of local pages in aglobal page.

SHM_GNPAGES The number of global pages in a shared memory segment.Compute the size, in bytes, of a shared memory segmentby multiplying the size of a single global page(512*SHM_GPAGESZ) by the number of global pages persegment (SHM_GNPAGES). This total cannot exceed themaximum segment size defined in your UNIX kernel.

Configuration Parameters for Memory Structure Sizes


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

SHM_NFREES Number of free shared memory segments that should bekept for UniData. If the number of free segments is largerthan this value, smm releases the additional segmentsback to the operating system. If the number drops belowthis value, smm creates another segment. This parameteris 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:

% sms -hShmid of CTL: 6201-------------------------------- IDs ---------------------------------smm_pid smm_trace PtoM_msgqid MtoP_msgqid ct_semid(values)17758 0 1400 1401 792(1,1,1)

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

NUSERS = 50 (max 50 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 = 1

SHM_FIL_CNT = 2048JRNL_BUFSZ = 53248

Note: Refer to Appendix A, “UniData Configuration Parameters,” for furtherinformation about these parameters.


sbcs and Shared Memory

sbcs 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 Segments

A UniData process can attach a segment of shared memory larger than a

standard global page. UniData requires that a UniBasic variable it reads into

memory be contained in a single global page. If a variable is larger than the

size of a global page, smm creates a special segment in shared memory. These

“self-created” segments, also called “indirect” segments, are attached to the

requesting udt process. Some circumstances resulting in self-created

segments are:

■ Editing a large report with AE. AE is a UniBasic program, and

UniData 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. smm determines

the maximum size by the UNIX kernel parameter shmmax. 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 sbcs creates.sbcs uses the segments to store globally catalogedprograms. sbcs can attach a maximum of 20 segments. (Onsome UNIX versions, the kernel parameter shmsegconstrains sbcs to 10 segments.)

MAX_OBJ_SIZE Maximum size, in bytes, of object code files that sbcs canload into shared memory. sbcs loads object code fileslarger than this size into the address space of the userinstead of shared memory.

Configuration Parameters for sbcs


Warning: Creating these segments of memory is not an efficient resource use, andmay result in poor performance or in thrashing. Use the system-level lstt commandor the ipcstat command to determine if your application is using self-createdsegments 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) tohandle the variables. Also, consider modifying the application to read arrays byelement rather than as a single variable.

UniData and the UNIX Kernel

When optimizing configuration parameters for shared memory, certain

changes may impact parameters in the UNIX kernel. Before implementing

configuration changes, you should explore the impact of these changes on

your kernel parameters, and determine if the kernel parameters should be

changed. The following table describes relationships between UNIX kernel

parameters and UniData.

Note: If you are using RFS, UniData allocates a portion of shared memory as asystem buffer for RFS processing. When you start UniData with RFS, UniDatareserves this buffer, and it is therefore not available to smm or sbcs. SeeAdministering the Recoverable File System for information about the system buffer.

UNIX Kernel Relationship to UniData

Maximum size ofshared memorysegment (shmmax)

Must be larger than CTL, and larger than a sharedmemory segment created by smm or sbcs. UniData maynot start if this kernel parameter is too low. If you changethe configuration parameters that control the size ofmemory structures, you may need to adjust this kernelparameter.

Maximum number ofshared memorysegments (shmmni)

Must be greater than SHM_GNTBLS, the number of GCTsin the control table. This parameter should be set highenough to accommodate all the GCTs, plus one segmentfor CTL, and one or more (up to 20) for sbcs.

Maximum number ofshared memorysegments per process(shmseg)

Must be greater than SHM_LMINENTS, the number ofentries available in the MI table for each LCT, which is thenumber of global pages that can be attached to a process.

UniData and the UNIX Kernel


6Chapter

UniData and UNIX ipc Facilities

Message Queues . . . . . . . . . . . . . . . . . . 6 -4

UniData and Message Queues . . . . . . . . . . . . 6 -4

Semaphores . . . . . . . . . . . . . . . . . . . . 6 -6

6-2 Adm

Interprocess communication (ipc) facilities consist of message queues, shared

memory segments, and semaphores. Chapter 5, “UniData and Memory,”describes shared memory handling. This chapter describes how UniData

uses message queues and semaphores.

Note: The UNIX ipcs and ipcrm commands, and the UniData system-level ipcstatand udipcrm commands, are useful for tracking and managing ipc resources. Referto your host operating system documentation for information about ipcs and ipcrm,and see Chapter 18, “Managing ipc Facilities,” for information about ipcstat andudipcrm.

6-3

Message QueuesA message queue is a system resource that can accept input from a number

of processes. Processes can then retrieve messages from the queue, with some

degree of selectivity. UNIX kernels generally include parameters that define

the number of message queues, their size, and the number of outstanding

messages the system can support.

The following table shows UNIX kernel parameters related to message

queues and messages.

Note: UNIX parameter names differ among versions of UNIX. These parameternames were read from a HP-UX kernel.

UniData and Message Queues

The smm and sbcs daemons use message queues for interprocess

communication. When you start UniData, UniData initializes log files for

each daemon, and lists the queues assigned to each daemon in its log.


msgmni The number of message queues the system can support.

msgmax The maximum size of a message, in bytes, allowed on the system.

msgmnb The maximum length, in bytes, of a message queue. This is the sumof the length of all messages in the queue.

msgmap Maximum number of entries in an internal table that UNIX uses tomanage shared memory segments for holding messages.

msgseg Number of shared memory segments that UNIX reserves at kernelstartup time for holding messages.

UNIX Parameters for Message Queues


The following table describes the queues required for the UniData daemons.

Note: If you are using RFS, you need additional message queues to handlecommunications for the RFS daemons. See Administering the Recoverable FileSystem for information about RFS requirements for message queues.

Tip: If one or more of your UniData daemons will not start, check the error logs foreach daemon. Your UNIX kernel may not be configured with a sufficient number ofmessage queues. Often, kernels are configured for a minimal number of queues. Referto your host operating system documentation for information about kernelconfiguration.

UniData Daemon Queues

smm Two queues: one request queue and one reply queue.

sbcs Three queues: one request queue, one reply queue, and one “newversion” queue, used to replace a cataloged program with a newversion.

UniData Message Queue Requirements

Message Queues 6-5

SemaphoresUNIX system semaphores are used to control access to resources (like

segments of shared memory) that can handle a limited number of

simultaneous users. When a process acquires a semaphore, that process has

access to the system resource the semaphore controls. When the process is

finished with the resource, the process releases the semaphore.

A semaphore undo structure is a resource used to recover a semaphore if the

process that acquired it terminates abnormally.

The following table lists UNIX kernel parameters that are important for the

use of system semaphores.

Note: UNIX parameter names differ between versions of UNIX. These parameternames were read from a HP-UX kernel.

UniData uses one system semaphore for smm. Informix also recommends

that semmnu, the number of undo structures system-wide, be set to three

times the number of licensed UniData users.

Note: If you are using RFS, you may need additional system semaphores. RFSsemaphore operations may be handled at the UNIX system level, or by C or assemblerinstructions, depending on what method is most efficient for your UNIX version. SeeAdministering the Recoverable File System for further information.

UNIX Parameter Description

semmni The maximum number of semaphore identifierssystemwide.

semmnu The maximum number of semaphore “undo” structuressystemwide.

semmns The maximum number of semaphores availablesystemwide.

UNIX Parameters for Semaphores


7Chapter

UniData and UNIX Devices

UNIX Devices: Overview . . . . . . . . . . . . . . . 7 -4

UniData and Terminal Devices . . . . . . . . . . . . . 7 -5

UniData and Tape Devices . . . . . . . . . . . . . . . 7 -6

UniData and Printers . . . . . . . . . . . . . . . . . 7 -7

UniData and Serial Devices . . . . . . . . . . . . . . 7 -8

7-2 Adm

This chapter briefly outlines how the UNIX operating system communicates

with devices such as terminals, disk drives, tape drives, and printers. The

chapter also outlines how UniData interacts with UNIX devices and device

handling.

7-3

UNIX Devices: OverviewThe UNIX operating system uses device drivers to communicate with disk

drives, tape drives, terminals, printers, and other hardware. Device drivers

are programs that know how to communicate with each type of hardware.

The UNIX kernel accesses these programs whenever a process requests

interaction with a device.

The UNIX communication interface is set up so that any device can be

viewed as a file. Data can be read from and written to a device file. The UNIX

kernel translates actions on the device file into requests from the appropriate

device driver program.

On most UNIX systems, device files reside in the /dev directory. This

directory contains special files for serial devices, terminals of various sorts,

disk devices, tape devices, and so forth. The names for these special device

files vary among UNIX versions.

Note: Refer to your host operating system documentation for additional informationabout device files and device drivers on your system.


UniData and Terminal DevicesFor virtually all terminal input/output, UniData relies on your host UNIX

operating system to perform terminal emulation. UniData does not maintain

its own terminal definition files. Different versions of UNIX handle terminal

definitions differently. Some store terminal definition information in a

termcap file while others use a terminfo database. Refer to your host

operating system documentation for information about terminal definitions

for your system.

Because terminal emulation in UniData happens at the UNIX level, terminal

emulation problems that occur within UniData must be resolved at the UNIX

level.

Note: There are a handful of UniData utilities that require a specific terminaldefinition file. For these utilities, your UniData product includes a file calledvvtermcap, which is a termcap-like file with extensions. This file is located in udtbin.To execute the utilities that require it (which include USAM, confprod, udtconf, andshmconf) you must define either the UDTBIN or the VVTERMCAP environmentvariable. See Appendix B, “Environment Variables for UniData,” for furtherinformation.

7-5

UniData and Tape DevicesNames for tape device files vary considerably between UNIX versions. The

name of a tape device file often identifies a tape drive and an access method

(such as rewind/no rewind).

UniData includes a number of commands that allow you to read data from

or write data to UNIX tape devices. To use these commands effectively, you

need to understand the tape device naming conventions on your system,

because you need to specify device names to define them in UniData. Refer

to your host operating system documentation for this information.

UniData uses a variety of proprietary methods, as well as some standard

UNIX commands, to read/write data to tape devices. Tape devices must be

defined in a UniData file before you can access them via UniData commands.

See Chapter 16, “Accessing UNIX Devices,” and the UniData CommandsReference for more information.


UniData and PrintersUniData uses the UNIX spooler on each system to perform all printing. In

order to print from within UniData to a UNIX printer, that printer must be

connected to your system and defined within your spooler software. UniData

provides commands and options that interface with your spooler and enable

you to direct output to a printer or a class of printers.

Many printer problems that appear within UniData must be resolved outside

of UniData, since the UniData commands do not interact directly with a

printer device. You need to understand the printer configuration and spooler

software on your system to troubleshoot UniData printing problems.

Since different UNIX versions use different spooler commands, UniData

enables you to define the translation between UniData printing options and

UNIX spooler options by defining a spooler configuration file. You can

determine your current spooler selection with the ECL LIMIT or SETPTR

command. For more information on defining spooler commands, refer to

Chapter 15, “Managing Printers in UniData.”

Note: IBM offers a spooler replacement product, called USAM/Print. This productis sold and licensed separately from the UniData RDBMS.

7-7

UniData and Serial DevicesUniData includes a group of commands that allow you to read data from or

write data to a UNIX serial device. Although you can use these commands to

access a terminal or printer device, they are most commonly used for

communicating between UniData and a device, such as a bar code reader or

scale. If such a device has a physical connection to your system, you can

define it within UniData and communicate with it through UniBasic

commands.

To make effective use of these UniData capabilities, you need to understand

your configuration and device naming conventions. Refer to your host

operating system documentation for this information. See Chapter 16,

“Accessing UNIX Devices,” and Developing UniBasic Applications for

information about communicating with serial devices.


8Chapter

Configuring Your UniDataSystem

Configuration Procedure . . . . . . . . . . . . . . . 8 -4

8-2 Adm

This 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.

8-3

Configuration ProcedureIf you are installing or upgrading UniData, see Installing and LicensingUniData 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 Requirements

Disk space and disk configuration are key factors that determine system

performance. The initial estimates in Installing and Licensing UniData Productsshould allow you to install and run UniData. However, IBM recommends

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:

■ /tmp directory—Locate your /tmp directory on a different

physical device from your data for improved performance.

■ UniData accounts—If your application uses more than one

UniData account, locate the account directories on separate

devices to distribute load.

■ Logical volume management—Consider implementing a logical

volume management protocol that includes disk striping.

Various products and utilities are available; consult with your

hardware vendor for recommendations. Striping, which allows

you to create logical volumes that span physical devices, can

provide significant performance improvements by balancing the

load on the system.

Tip: If your application frequently accesses data files that are larger than 300MB insize, IBM strongly recommends striping.


2. Identify Memory Requirements

The 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)

■ The memory segments controlled by smm

■ The memory segments for sbcs

■ If you use the Recoverable File System (RFS), the system buffer.

Refer to Chapter 5, “UniData and Memory,” for information about estimating

memory needs.

3. Verify Version Compatibilities

If you are considering major upgrades to your hardware or to your operating

system version, 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 UNIX Kernel Parameters

Depending on your version of UNIX, you may or may not be able to modify

kernel parameters directly. The following categories of parameters may need

adjustment when you first implement UniData:

■ Memory — Review parameters that limit the number of shared

memory segments systemwide, the maximum and minimum size of

a segment, and the maximum number of segments per process. See

Chapter 5, “UniData and Memory,” and Chapter 17, “ManagingMemory,” for additional information.

■ Files and Users — Review parameters that define the maximum

number of open files and file locks supported systemwide, the

maximum number of files per user process, and the maximum

number of user processes the system can support at one time.

Configuration Procedure 8-5

■ ipc Facilities — Review parameters that define the number and size

of message queues your system supports, the number of semaphore

sets and semaphores your system supports, and the number of

semaphore undo structures supported. Refer to Chapter 6, “UniData

and UNIX ipc Facilities,” and Chapter 18, “Managing ipc Facilities,”

for additional information.

Warning: The number of systemwide semaphores, normally semmns, should be aminimum of NUSERS + 10. The number of semaphore identifiers, normally semmni,must be at least NUSERS/NSEM_PSET + 1. If either of these kernel parameters arenot adequate for the number of licensed users, UniData displays an error messagesimilar to “Exit: smm: cannot allocate semaphore for udtno xx errno 28. Exit: SMMcan’t setup Control Table List,” and fails to start.

Note: If you discover that you need to change both UNIX kernel parameters andUniData configuration parameters, identify all your requirements and then plan torebuild the UNIX kernel first. If you attempt to start UniData with new parameters,and the UNIX kernel parameters are insufficient, UniData may not start.

5. Check/Reset UniData Configuration Parameters

The UniData udtconfig file, located in /usr/ud60/include, contains a set of

parameters that are given default values when you install UniData. When

you start a UniData session, UniData sets UNIX environment variables for

each value in the udtconfig file.

Note: The udtconfig file is always located in /usr/udnn/include, where nn is therelease number of UniData. For example, the udtconfig file for Release 6.0 is locatedin /usr/ud60/include, the udtconfig file for Release 5.2 is located in/usr/ud52/include, and so forth. Do not move the directory to another location, orUniData will not run.

The udtconfig file enables you to define values for each parameter that

applies to your UniData environment. Most udtconfig parameters can be

adjusted 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 be logged in as root to modify udtconfig parameters.


The following screen displays a sample udtconfig file:

# Unidata Configuration Parameters## Section 1 Neutral parameters# These parameters are required by all Unidatainstallations.## 1.1 System dependent parameters, they should not be changed.LOCKFIFO=1SYS_PV=3

# 1.2 Changable parametersNFILES=55NUSERS=40WRITE_TO_CONSOLE=0TMP=/tmp/NVLMARK=FCNTL_ON=0TOGGLE_NAP_TIME=91NULL_FLAG=0N_FILESYS=200N_GLM_GLOBAL_BUCKET=101N_GLM_SELF_BUCKET=23GLM_MEM_SEGSZ=4194304

# 1.3 I18N related parameterUDT_LANGGRP=255/192/129ZERO_CHAR=131

## Section 2 Non-RFS related parameters## 2.1 Shared memory related parametersSBCS_SHM_SIZE=1048576SHM_MAX_SIZE=67108864SHM_ATT_ADD=0SHM_LBA=4096SHM_MIN_NATT=4SHM_GNTBLS=40SHM_GNPAGES=32SHM_GPAGESZ=256SHM_LPINENTS=10SHM_LMINENTS=32SHM_LCINENTS=100SHM_LPAGESZ=8SHM_FREEPCT=25SHM_NFREES=1

# 2.2 Size limitation parametersAVG_TUPLE_LEN=4EXPBLKSIZE=16MAX_OBJ_SIZE=307200MIN_MEMORY_TEMP=64


# 2.3 Dynamic file related parametersGRP_FREE_BLK=5SHM_FIL_CNT=2048SPLIT_LOAD=60MERGE_LOAD=40KEYDATA_SPLIT_LOAD=95KEYDATA_MERGE_LOAD=40MAX_FLENGTH=1073741824PART_TBL=/liz1/ud60/parttbl

# 2.4 NFA/Telnet service related parameterEFS_LCKTIME=0TSTIMEOUT=60NFA_CONVERT_CHAR=0

# 2.5 Journal related parametersJRNL_MAX_PROCS=1JRNL_MAX_FILES=400

# 2.6 UniBasic file related parametersMAX_OPEN_FILE=500MAX_OPEN_SEQF=150MAX_OPEN_OSF=100MAX_DSFILES=1000

#2.7 UniBasic related parametersMAX_CAPT_LEVEL=2MAX_RETN_LEVEL=2COMPACTOR_POLICY=1VARMEM_PCT=50

# 2.8 Number of semaphores per semaphore setNSEM_PSET=8

# 2.9 Index related parametersSETINDEX_BUFFER_KEYS=0SETINDEX_VALIDATE_KEY=0

# 2.10 UPL/MGLM parameterMGLM_BUCKET_SIZE=50UPL_LOGGING=0

# 2.11 Printer _HOLD_ file related parametersMAX_NEXT_HOLD_DIGITS=4CHECK_HOLD_EXIST=0

## Section 3 RFS related parameters# These parameters are only used for RFS which is turned by# setting SB_FLAG to a positive value.## 3.1 RFS flagSB_FLAG=1


# 3.2 File related parametersBPF_NFILES=80N_PARTFILE=500

# 3.3 AFT related parametersN_AFT=200N_AFT_SECTION=1N_AFT_BUCKET=101N_AFT_MLF_BUCKET=23N_TMAFT_BUCKET=19

# 3.4 Archive related parametersARCH_FLAG=0N_ARCH=2ARCHIVE_TO_TAPE=0ARCH_WRITE_SZ=0

# 3.5 System buffer parametersN_BIG=233N_PUT=8192

# 3.6 TM message queue related parametersN_PGQ=10N_TMQ=10

# 3.7 After/before image related parametersN_AIMG=2N_BIMG=2AIMG_BUFSZ=102400BIMG_BUFSZ=102400AIMG_MIN_BLKS=10BIMG_MIN_BLKS=10AIMG_FLUSH_BLKS=2BIMG_FLUSH_BLKS=2

# 3.8 Flushing interval related parametersCHKPNT_TIME=300GRPCMT_TIME=5

# 3.9 Sync Daemon related parametersN_SYNC=0SYNC_TIME=0

## Section 6 Century Pivot Date#CENTURY_PIVOT=1930

## Section 7 Repliation parameters#REP_FLAG=1TCA_SIZE=128


MAX_LRF_FILESIZE=134217728N_REP_OPEN_FILE=8MAX_REP_DISTRIB=1MAX_REP_SHMSZ=67108864UDR_CONVERT_CHAR=1

## Euro data handling symbols#CONVERT_EURO=0SYSTEM_EURO=164TERM_EURO=164LOG_OVRFLO=/liz1/ud60/log/log_overflow_dirREP_LOG_PATH=/liz1/ud60/log/replog#

6. Define Peripherals within UniData

You need to define tape devices, printers, and line devices need to within

UniData before they can be accessed from UniData. Before defining a device

within UniData, make certain that it is properly installed and functioning in

your UNIX environment. Refer to your host 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 7, “UniData and UNIX Devices,”

Chapter 15, “Managing Printers in UniData,” and Chapter 16, “Accessing

UNIX Devices,” for additional information.

7. Create UniData Accounts

When you implement UniData, you may need to create one or more UniData

accounts for your application. A UniData account is a UNIX directory that

contains a UniData VOC file and its dictionary. The VOC file identifies

commands, paragraphs, and all data files in the UniData account. The data

files may be in the same UNIX directory as the VOC file, or the VOC file may

contain pointers to data files in other UNIX file systems. Your system may

have a single UniData account or several, depending on your application.

Note: A UNIX account (login, password) is not the same as a UniData account.Every UniData user should have a separate UNIX account (login and password), butmany users can access the same UniData account.


Use the UNIX mkdir command and the UniData system-level newacct

command to create UniData accounts. Refer to your host operating system

documentation for information about the mkdir command, and see Chapter

10, “Managing UniData Accounts,” for information about the newacct

command.

8. Add UNIX Users

Accessing UniData requires each user to have a login and password on your

UNIX system. IBM recommends you create a separate UNIX login (UNIX

account) for each UniData user. Refer to your host operating system

documentation for detailed information on creating UNIX accounts. See

Chapter 11, “Managing UniData Security,” for UniData-specific information.

9. Set Environment Variables

A user wishing to access UniData 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.

Note: See Installing and Licensing UniData Products for information aboutinstallation types.

UDTHOME — This variable identifies the absolute 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

Each user needs UDTHOME and UDTBIN set to access UniData. You can

add commands to set these environment variables to each user’s .login or

.profile, or a user can set them at the UNIX prompt. If you are using the C

shell, use the following commands to set these variables:

setenv UDTHOME /directory-name

setenv UDTBIN /directory-name


If you are using the Bourne or Korn shell, use these commands:

UDTHOME=/directory-name;export UDTHOME

UDTBIN=/directory-name;export UDTBIN

Setting PATH

Each user’s PATH should include the directory corresponding to UDTBIN. If

you are using the C shell, use the following command:

set path = ($path $UDTBIN)

Use the following command for Bourne or Korn shells:

PATH=$PATH:$UDTBIN;export PATH

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 a user’s

login script or defined from a UNIX prompt before entering UniData.

Note: While you are in a UniData session, you cannot change environment variablesfor that session. Even if you execute setenv, for instance, from the ! prompt, the newsetting affects only processes started from the ! prompt. The new settings do not affectthe current UniData session.

10. Review UniData Security

Depending 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 udthomeand its contents that were set when you installed UniData.

■ Users and groups—Assign UniData users to separate UNIX groups,

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.

Refer to Chapter 11, “Managing UniData Security,” for additional

information.

11. Convert Data Files

Depending upon the nature of your system change, you may need to perform

some conversion of UniData hashed files. Consider the following:

■ Recoverable files—If you are implementing UniData’s Recoverable

File System, you need to create recoverable files and/or convert

existing hashed files to recoverable files. See Administering theRecoverable File System for detailed information.

■ 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 theSchema 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.

Refer to Chapter 12, “Managing UniData Files,” and to the UniDataCommands Reference for additional information.

12. Perform makeudt

UniData provides the capability to invoke C functions from within UniBasic

programs. It is necessary to rebuild the UniData executable (the binary file

udtbin/udt) whenever you wish to link in additional C functions.


13. Review Backup Procedures

Special considerations are needed to back up UniData accounts. Make certain

your backup procedures have the following capabilities:

■ Subdirectories—Your backup procedure should be able to back up

at least three levels of subdirectories to support UniData MULTIDIR

and MULTIFILE files.

■ Symbolic links—Your backup procedure should be able to follow

UNIX symbolic links to support large dynamic files.

■ Backing up selected files—Your backup procedure should allow

you to input a list of files to back up to support full backups of

UniData accounts. Simply backing up the directory that contains the

VOC file may be insufficient, since data files may not be located in

the same UNIX directory as the VOC file. The ECL SETFILE

command creates VOC entries with pointers to files in other

locations. However, backup utilities do not follow these SETFILE

pointers like they do UNIX symbolic links. To create a complete

backup of an account, make sure you back up and verify each

physical file associated with the account.


9Chapter

Starting, Stopping, and PausingUniData

Normal Operation . . . . . . . . . . . . . . . . . . 9 -4

UniData Log Files . . . . . . . . . . . . . . . . 9 -4

Start UniData with startud . . . . . . . . . . . . . 9 -5

Stop UniData with stopud . . . . . . . . . . . . . 9 -6

Pausing UniData . . . . . . . . . . . . . . . . . . 9 -7

The dbpause Command . . . . . . . . . . . . . . 9 -7

The dbpause_status Command . . . . . . . . . . . . 9 -9

Resuming Processing . . . . . . . . . . . . . . . 9 -9

Additional Commands . . . . . . . . . . . . . . . . 9 -10

Listing Processes with showud . . . . . . . . . . . . 9 -11

Stopping a User Process with stopudt . . . . . . . . . 9 -11

Stopping a User Process with deleteuser. . . . . . . . . 9 -12

Displaying ipc Facilities with ipcstat . . . . . . . . . . 9 -13

Removing ipc Structures with udipcrm . . . . . . . . . 9 -14

Stopping UniData with stopud -f . . . . . . . . . . . 9 -15

9-2 Adm

Starting, Stopping, and Pausing UniDataThis 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.

9-3

Normal OperationUse the UniData startud and stopud commands, respectively, for normal

startup and shutdown. These commands start and stop the sbcs, cleanupd,

and smm daemons, in the correct order.

Note: You must be logged in as root to execute startud or stopud. Make sure you havedefined the environment variables UDTHOME and UDTBIN, and make sure yourPATH includes udtbin. If you are running more than one version of UniData, makesure that these environment variables are set for the version of UniData you want tostart and stop.

UniData Log Files

startud makes entries in the log files (smm.log, sbcs.log, and cleanupd.log)

that identify the system resources used by the daemons. If you are using the

Recoverable File System (RFS), startud and stopud also start the sm daemon

and record information in its sm.log.

The following example shows a sample sbcs.log:

% pg sbcs.log

The next example shows a sample smm.log:

# pg sbcs.log

SBCS version: 6.0

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:

% pg smm.logSMM version: 6.0

Number of users......: 32SMM checking interval: 60 secondsSMM process id.......: 2469

IPC facilities:

q - 203 (request queue)q - 204 (reply queue)m - 1405 (ctl)m - 406 (glm)m - 407 (shmbuf)s - 140 (ctl)s - 141 (journal)s - 142 (SUPERRELEASE/SUPERCLEAR.LOCKS)s - 135 (latch)s - 136 (latch)s - 137 (latch)s - 138 (latch)s - 139 (latch)

The next example shows 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:

# startudUsing UDTBIN=/disk1/ud60/bin

All output and error logs have been saved to ./saved_logsdirectory.

SMM is started.SBCS is started.CLEANUPD is started.SM is started.Unirpcd is started

UniData R6.0 has been started.#

Normal Operation 9-5

Note: You can configure your system so that UniData starts up automatically whenyou boot your computer. You need to add or modify a startup script to accomplishthis. Refer to your host operating system documentation for detailed informationabout startup scripts.

Warning: If you are using RFS, IBM recommends that you not start UniDataautomatically at reboot. If your system is rebooting because of a machine failure, andone or more file systems has been damaged, UniData failure recovery will notcomplete successfully.

Stop UniData with stopud

For 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:

# stopudUsing UDTBIN=/disk1/ud60/bin

SM stopped successfully.CLEANUPD stopped successfully.SBCS stopped successfully.SMM stopped successfully.Unirpcd has already been stopped

Unidata R6.0 has been shut down.#


Pausing UniData

The dbpause Command

UniData 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

UniData starts a new archive file when you resume processing.

Note: You must log in as root to issue the dbpause command.

dbpause blocks most updates to the database that are made within UniData.

UniData completes writes or transactions in process when you issue the

dbpause command before dbpause takes effect. Updates are blocked until the

system administrator executes the dbresume command.

UniData does not block UNIX commands, such as cp or mv. In addition,

UniData does not block updates to the _HOLD_ file and the _PH_ file, and

does not interrupt report printing. If you execute dbpause while running

RFS, UniData forces a checkpoint, flushes the after image logs to the archive

files (if archiving is enabled), and marks the next available logical sequence

number in the archive file for use after the backup. UniData displays this

information on the screen from which you execute dbpause, and writes it to

udtbin/sm.log.

Note: Some UniData system-level commands, such as cntl_install and verify2,require that UniData not be running. These commands do not execute successfullywith dbpause in effect. You cannot stop UniData with dbpause in effect.

The following ECL commands are not blocked when dbpause is in effect:

■ ACCT.SAVE, T.ATT, T.DUMP

■ BLOCK.PRINT, BLOCK.TERM

■ CHECKOVER, dumpgroup, fixfile, fixgroup, guide

■ CLEAR.ACCOUNT, CLEARDATA, CLR

Pausing UniData 9-7

■ COMO

■ CONFIGURE.FILE, HASH.TEST

■ LIST.TRIGGER

■ DATE.FORMAT

■ CLEAR.LOCKS, DELETE.LOCKED.ACTION, LOCK, SUPER-

CLEAR.LOCKS, SUPERRELEASE

■ BLIST, VCATALOG

■ deleteuser, ipcstat, makeudt, stopudt, updatevoc

■ ECLTYPE, UDT.OPTIONS

■ FLOAT.PRECISION

■ HELP

■ LINE.ATT

■ LIST.INDEX

■ LOGTO (unless a login paragraph exists in the account you are

logging to, and an action is defined in the login paragraph that is

paused)

■ MIN.MEMORY

■ SET.DEC, SET.MONEY, SET.THOUS, SET.WIDEZERO

■ SETOSPRINTER, SETPTR, SP.ASSIGN, SP.EDIT

■ TERM

■ WHAT

The following example illustrates the output from the dbpause command:

# dbpauseDBpause successful.#

If you are running RFS, it is important that you synchronize your archive files

with your backup files when using the dbpause command. For more

information about using dbpause with RFS, see Administering the RecoverableFile System.


The dbpause_status Command

The 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:

% dbpause_statusDBpause is ON.%

Resuming Processing

To 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

You must log in as root to issue the dbresume command.

The following screen illustrates the output from the dbresume command:

# dbresumeDBresume successful.#

Pausing UniData 9-9

Additional CommandsUniData provides a number of system-level commands to assist you in

clearing users, processes, and system resources from UniData, if necessary.

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, udipcrm, and stopud -f all carry the riskof disturbing the integrity of your data. They should never be used as a routinesubstitute for normal user logoff.

UniData Command Function

listuser Lists all current UniData users.

showud Lists all UniData daemons.

stopudt Logs a user out of UniData; a current write completes, butsubsequent operations for that udt do not take place.stopudt executes the UNIX kill -15 command.

deleteuser Forces a user out of UniData and removes the user’s entryfrom the lcp table. deleteuser first issues the UNIX kill -15command. If kill -15 is not successful after 5 seconds,deleteuser issues the UNIX kill -9 command. Kill -9 mayinterrupt a write in progress, causing inconsistent dataand file corruption.

ipcstat Lists all ipc structures in use on the system; identifies thoseused by UniData daemons.

udipcrm Removes all ipc facilities associated with UniData(queues, shared memory segments, semaphores). Thiscommand shuts UniData down and may corrupt files; usethe command only if a daemon has been killed and has leftipc structures behind.

stopud -f Forces all UniData daemons to stop regardless of systemactivity.

UniData System-Level Commands


Listing Processes with showud

The showud command lists all UniData processes that are currently running.

The following screen shows an example of showud output:

# showud UID PID TIME COMMAND root 20376 0:00 /disk1/ud60/bin/aimglog 0 14553 root 20377 0:00 /disk1/ud60/bin/aimglog 1 14553 root 20378 0:00 /disk1/ud60/bin/bimglog 2 14553 root 20379 0:00 /disk1/ud60/bin/bimglog 3 14553 root 20367 0:00 /disk1/ud60/bin/cleanupd -m 10 -t 20 root 20373 0:00 /disk1/ud60/bin/cm 14553 root 20363 0:00 /disk1/ud60/bin/sbcs -r root 20372 0:00 /disk1/ud60/bin/sm 60 30482 root 20356 0:00 /disk1/ud60/bin/smm -t 60 root 20393 0:00 /disk1/unishared/unirpc/unirpcd#

Stopping a User Process with stopudt

The stopudt command logs out a user, as opposed to stopud, which stops

UniData.

Syntax:

stopudt pid

The argument pid is a UNIX process ID.

Additional Commands 9-11

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.

% listuser Max Number of Users UDT SQL TOTAL~~~~~~~~~~~~~~~~~~~ ~~~ ~~~ ~~~~~ 32 3 0 3

UDTNO USRNBR UID USRNAME USRTYPE TTY TIMEDATE

1 645 1182 miker udt ttyp2 09:06:46 Jun 272002

2 3717 1172 claireg udt pts/3 10:31:14 Jun 272002

3 670 1179 joand udt ttyp3 09:16:24 Jun 272002

# stopudt 3717# listuserMax Number of Users UDT SQL TOTAL~~~~~~~~~~~~~~~~~~~ ~~~ ~~~ ~~~~~ 32 2 0 2



3 670 1179 joand udt ttyp3 09:16:24 Jun 272002 #

You must log in as root 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 udtprocess you are removing. If you use the UNIX ps command to get the number, thepid is clearly labeled. If you use the UniData listuser command, as shown in thepreceding screen, the pid is called USRNBR.

Stopping a User Process with deleteuser

The deleteuser command first tries to kill the user process with the UNIX kill

-15 command. If the kill -15 is unsuccessful after five seconds, a kill -9 is

issued.

Syntax:

deleteuser pid

The argument pid is the UNIX process ID.


Warning: Because deleteuser may execute the UNIX kill -9 command, it isparticularly important that you verify the pid carefully.

The following screen shows an example of the deleteuser command:

% listuser

Max Number of Users UDT SQL TOTAL~~~~~~~~~~~~~~~~~~~ ~~~ ~~~ ~~~~~ 32 4 0 4




3 3930 1283 carolw udt pts/2 12:47:07 Jun 272002

5 3953 1172 claireg udt pts/3 13:32:01 Jun 272002

# deleteuser 3953# listuser

Max Number of Users UDT SQL TOTAL~~~~~~~~~~~~~~~~~~~ ~~~ ~~~ ~~~~~ 32 3 0 3




3 3930 1283 carolw udt pts/2 12:47:07 Jun 272002

Note: You must log in as root to execute deleteuser.

Displaying ipc Facilities with ipcstat

The 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

in as root to execute ipcstat.

Syntax:

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


The following screen shows an example of ipcstat output:

% ipcstat -mIPC status from /dev/kmem as of Tue Jun 22 14:48:14 2002T ID KEY MODE OWNER GROUPShared Memory:m 0 0x00000000 D-rw------- root sys -> unknownm 1 0x411c031b --rw-rw-rw- root root -> unknownm 2 0x4e0c0002 --rw-rw-rw- root root -> unknownm 3 0x41201102 --rw-rw-rw- root root -> unknownm 2404 0x431cdb10 --rw-rw-rw- root sys -> unknownm 1405 0x00000000 --rw-rw-rw- root sys -> unknownm 406 0x00000000 --rw-rw-rw- root sys -> unknownm 407 0x00000000 --rw-r--r-- root sys -> unknownm 208 0x631cdb10 --rw-rw-rw- root sys -> unknownm 820 0x00000000 D-rw-rw-rw- root sys -> unknownm 1021 0x441c063f --rw-rw-rw- root sys -> smm R5.2 (ctl)m 422 0x00000000 -Crw-rw-rw- root sys -> smm R6.0 (glm)m 423 0x00000000 -Crw-rw-rw- root sys -> smm R6.0 (shmbuf)m 424 0x00000000 --rw-r--r-- root sys -> sbcs R6.0m 225 0x641c063f --rw-rw-rw- root sys -> sm R5.2 (ctl)m 226 0x00000000 --rw-rw-rw- root sys -> sm R6.0 (sysbuf)##

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 fromipcstat indicates which ones are used by UniData processes. The ones that correspondto “unknown” are not associated with UniData daemons.

Removing ipc Structures with udipcrm

The udipcrm command uses the UNIX ipcrm command to remove any and

all ipc facilities associated with any UniData process. After an abnormal

shutdown, you may be unable to start UniData because some ipc facilities

did not stop cleanly. You can use either the UNIX ipcrm command or

udipcrm to remove them.

Syntax:

udipcrm

The udipcrm command is related to the ipcstat command. ipcstat lists all ipc

facilities currently in use on a system, and identifies which ones are used by

UniData processes. udipcrm only removes the ones associated with UniData.


Warning: Do not use udipcrm to shut down UniData. Use this command only ifUniData is down, you cannot restart UniData, and there are ipc facilities that didnot stop normally. Use the system-level command showud to verify that the UniDatadaemons are not running, and use ipcstat to identify ipc facilities that did not stopnormally. See Chapter 18, “Managing ipc Facilities,” for further information.

Stopping UniData with stopud -f

This command stops all daemons and UniData processes regardless of

activity on the system. Use this only if your system is hung and stopud fails

to work.

Syntax:

stopud -f

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

# stopud -fUsing UDTBIN=/disk1/ud60/bin

WARNING: 'stopud -f' will stop the Unidata System with force.This may not guarantee the consistency of the database files.

Would you like to continue?(y/n) [n]ySM stopped successfully.CLEANUPD stopped successfully.SBCS stopped successfully.SMM stopped successfully.Unirpcd has already been stopped

Unidata R6.0 has been shut down.

#

You must log in as root to run stopud -f.

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


10Chapter

Managing UniData Accounts

What Is a UniData Account? . . . . . . . . . . . . . . 10-4

Creating a UniData Account . . . . . . . . . . . . . . 10-5

Saving and Restoring Accounts . . . . . . . . . . . . . 10-9

Deleting an Account . . . . . . . . . . . . . . . . . 10-10

Clearing Space in UniData Accounts . . . . . . . . . . . 10-11

CLEAR.ACCOUNT . . . . . . . . . . . . . . . . 10-11

10 -2 Ad
ministering UniData on UNIX

This chapter describes UniData accounts, and describes procedures used to

create, save, and clear the accounts.

10-3

What Is a UniData Account?A UniData account is a UNIX directory that contains a default set of UniData

files, including a VOC file and its dictionary.

Note: The default files UniData requires for an account are created by the UniDatasystem-level newacct command.

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 UNIX

directory as the VOC file, or the VOC file may contain pointers to data files

in other UNIX directories. Your system may have a single UniData account,

or several, depending on your application.

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


Creating a UniData AccountComplete the following four steps to create a UniData account:

1. Make sure the environment variable UDTHOME is set.

2. Use the UNIX 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.

3. Change to the directory with the UNIX cd command.

4. Use the UniData newacct command to create the VOC and other

UniData-specific files in the directory.

Note: You do not need to log in as root to create a UniData account. However, thenewacct command prompts you for a user and group for your account. If you arelogged in as root, UniData uses this information to set ownership and permissionsfor the account. If you are not logged in as root, UniData ignores your responses anduses your current login and group ID.

The following three screens illustrate how to create an account, how to enter

UniData in the new account, and how to use the UniData LS command to list

the contents of the account:

# mkdir ACCOUNT# cd ACCOUNT# newacct% newacctThe UDTHOME for this account is /disk1/ud60/.Do you want to continue(y/n)?

Please enter the account group name: users...

Notice that, in the example, UDTHOME was already set to the path of

/usr/ud60. When you execute newacct, UniData creates the new VOC file

using a standard VOC file located in udthome/sys.

Tip: If you want to tailor your standard VOC file before creating new accounts, youmay do so. IBM recommends that you save a copy of the standard VOC before makingchanges.

Creating a UniData Account 10-5

The next example shows output from newacct:

Initializing the account ...

VOC and D_VOC file are createdCreating file D_SAVEDLISTS modulo /1Added "@ID", the default record for UniData to D_SAVEDLISTS.Creating file D_savedlists modulo /1Added "@ID", the default record for UniData to D_savedlists.Creating file D__PH_ modulo /1Added "@ID", the default record for UniData to D__PH_.Creating file D__HOLD_ modulo /1Added "@ID", the default record for UniData to D__HOLD_.Creating file D_BP modulo /1Added "@ID", the default record for UniData to D_BP.Creating file D_CTLG modulo /1Added "@ID", the default record for UniData to D_CTLG.D__REPORT_ file createdCreate file _REPORT_(&report&), modulo/17D__SCREEN_ file createdCreate file _SCREEN_, modulo/17D_MENUFILE file createdCreate file MENUFILE, modulo/2D___V__VIEW file createdCreate file __V__VIEW, modulo/11

The next example shows output from udt and LS:

% udtUniData Release 6.0 Build: (4088)(c) Copyright IBM Corporation 2002.All rights reserved.

Current UniData home is /disk1/ud60/.Current working directory is /disk1/ud60/demo.:

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.

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 UniData creates in a new

UniData account.

savedlists Used to store temporary information for BY.EXP sorts.UniData automatically creates and deletes the contents ofthis subdirectory.

_HOLD_ Used to store print files.

_PH_ Used to store output from background processes (createdby the UniData ECL PHANTOM command) and capturedterminal I/O (created by the UniData ECL COMOcommand).

File Description

MENUFILE Stores user-generated menu definitions.

VOC VOC (vocabulary) file, containing references for ECLcommands, sentences, paragraphs, and filenames.

_REPORT_ Used to store UReport report definitions.

_SCREEN_ Used to store UEntry screen definitions.

__V__VIEW Used to store UniData SQL view specifications.

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_.

Hashed Files in a UniData Account

Subdirectory Description

Subdirectories in a UniData Account (continued)

Creating a UniData Account 10-7

Note: See Developing UniBasic Applications and Using UniData SQL forinformation about UniBasic and UniData SQL

D__REPORT_ Dictionary for _REPORT_.

D__SCREEN_ Dictionary for _SCREEN_.

D___V__VIEW Dictionary for __V__VIEWS.

D_savedlists Dictionary for savedlists.

File Description

Hashed Files in a UniData Account (continued)


Saving and Restoring AccountsUniData includes two commands specifically designed for backing up and

restoring UniData accounts. These are described in the following table.

Note: These commands do not function if you are using the Recoverable File System.An error message displays to the terminal if you attempt to execute them.

Note: Use ACCT.SAVE and acctrestore carefully. These commands do not followeither UniData pointers to other directories (set with the SETFILE command) orsymbolic links for large dynamic files. They are designed for use with small, self-contained UniData accounts.

Most UniData customer sites use the UNIX tar or cpio utilities, or commercial

backup utilities, to back up UniData files and accounts. Consult your host

operating system documentation and vendor documentation to determine

the procedures to use at your site.

UniData Command Description

ACCT.SAVE Saves a current UNIX directory and its subdirectories totape; uses UNIX cpio utility, and writes only to the devicedefined as tape unit 0. (Use the SETTAPE command todefine a tape unit, and T.ATT to obtain exclusive use of itwithin UniData.)

acctrestore [n] Restores a UniData account that was saved withACCT.SAVE; uses UNIX cpio utility; restricted to a singletape volume. Specify the tape unit number n; the tapeunit must be defined with SETTAPE. If you executeacctrestore while UniData is running, you may corruptyour data files.

UniData Save and Restore Commands

Saving and Restoring Accounts 10-9

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 should be deleted.

Take care not to delete shared files that other UniData accounts may

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 UNIX rm -r command to delete the

account directory. If the account has file pointers to other file

systems, or dynamic files with part files on 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 rm -r. This command removes all files and subdirectoriesbelow the directory you specify. If you have nested accounts (a UniData accountwithin a UniData account) and you remove an account directory with rm -r, youcould remove more than one account.


Clearing Space in UniData AccountsThe _PH_ and _HOLD_ subdirectories of each UniData account store output

from background processes and temporary print files, respectively. These

subdirectories can become large, causing disk space problems. The UniData

ECL CLEAR.ACCOUNT command removes all files from either or both of

these subdirectories.

CLEAR.ACCOUNT

Syntax:

CLEAR.ACCOUNT

You must log in to the UniData account you are clearing. You do not need to

log in as root, however, you must have write permission for the _PH_ and

_HOLD_ directories. When you issue the command, UniData prompts you

for confirmation to clear each directory, as shown in the following example:

: WHERE/disk1/ud60/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 thiscommand only if you are certain none of the information is needed. Use the UniDataDELETE command or the UNIX rm command, if necessary, to remove only selectedfiles.

Clearing Space in UniData Accounts 10-11

11Chapter

Managing UniData Security

Logins and Groups . . . . . . . . . . . . . . . . . 11-4

Adding a UNIX User . . . . . . . . . . . . . . . . 11-4

Use Separate Logins . . . . . . . . . . . . . . . . 11-5

User Groups . . . . . . . . . . . . . . . . . . . 11-5

Home Directories . . . . . . . . . . . . . . . . . 11-6

Startup Scripts . . . . . . . . . . . . . . . . . . 11-7

Customizing Permissions . . . . . . . . . . . . . . . 11-8

Customizing a VOC File. . . . . . . . . . . . . . . . 11-12

Customizing UniData . . . . . . . . . . . . . . . 11-13

Remote Items . . . . . . . . . . . . . . . . . . . 11-15

The SETFILE Command. . . . . . . . . . . . . . . . 11-17

LOGIN and LOGOUT Paragraphs . . . . . . . . . . . . 11-18

UniData SQL Privileges . . . . . . . . . . . . . . . . 11-21

Field-Level Security for UniQuery . . . . . . . . . . . . 11-22

Points to Remember about Field-Level Security . . . . . . 11-22

The QUERY.PRIVILEGE File . . . . . . . . . . . . . 11-23

Turning on Field-Level Security . . . . . . . . . . . . 11-25

11 -2 Ad

While UniData uses UNIX permissions as its primary security mechanism,

there are a number of procedures you can use for customizing the security of

your UniData applications. This chapter describes how to use UNIX logins

and groups, how to modify default permissions, how to customize your VOC

file, and how to use remote pointers. The chapter also describes the

relationship between SQL privileges and other UniData security

mechanisms.

11-3

Logins and GroupsTo access UniData, users need a UNIX login (account).

Note: Utilities for adding and maintaining UNIX accounts are available on manysystems. Examples are sam or smit. They require root access, and automate therequired steps. For consistency, IBM recommends that you use your UNIX systemadministration utility to create and maintain UNIX accounts. Refer to your hostoperating system documentation and vendor documentation for information aboutprocedures available on your particular system.

UNIX typically stores user and group information in two files, as shown in

the following table.

Note: Some UNIX systems use additional files for security. For example, Solaris usesa file called /etc/shadow, and AIX uses one called /etc/security/passwd. Refer to yourhost operating system documentation for complete information about these files.

Adding a UNIX User

Adding a UNIX user, either manually or through your system administration

utility, involves the following steps:

1. Edit the /etc/passwd and /etc/group files (and /etc/shadow if

required).

2. Set a password for the user.

3. Create the home directory, and install startup scripts, if necessary.

UNIX Filename Description

/etc/group Contains a record for each group ID number (gid). Eachrecord includes a group name and defines the user IDnumbers (uid) associated with the group.

/etc/passwd Contains a record for each user ID. Each record includes alogin name, uid, gid, password, home directory, defaultshell identifier, and other optional information.

UNIX Security Files


Use Separate Logins

Although other database systems make use of group logins, which are shared

by a number of users, UniData allows you to define a separate login for each

user. IBM strongly recommends using separate logins for the following

reasons:

■ Most UNIX operating systems impose limits for system resources

(such as number of processes) that can be associated with one user.

Using separate logins makes your system utilize resources more

effectively.

■ It is easier to identify processes belonging to an individual user,

which facilitates troubleshooting.

■ Using separate logins allows you to define your users’

responsibilities for protecting their passwords and your data.

User Groups

Every UNIX user is assigned to a default group. The system recognizes the

user as a member of that default group at login. UNIX permissions allow you

to differentiate access among members of a group and users who are not

members of that group. You can use this feature to provide security in

UniData by defining applications (or accounts) that should be accessible to

certain users, defining groups to which those users belong, and setting the

group owners of the files and directories accordingly. For example, consider

the directory structure shown in the following example:

.

.

.drwxrwxr-- 2 root apusers 24 Jun 18 18:18 PAYABLESdrwxrwxr-- 2 root arusers 24 Jun 18 18:19 RECEIVABLES...

The example shows a long style listing for separate UniData accounts for two

applications: PAYABLES and RECEIVABLES. Notice the following:

Logins and Groups 11-5

■ Users in group apusers have read, write, and execute access to the

contents of PAYABLES, but only read access to RECEIVABLES. They

can list the contents of RECEIVABLES, but they cannot add or delete

files in RECEIVABLES, or cd to that directory, or access it with the

ECL LOGTO command.

■ Users in group arusers have read, write, and execute access to

RECEIVABLES, but only read access to PAYABLES. They can list the

contents of PAYABLES, but they cannot add or delete files in

PAYABLES, or cd to that directory, or access it with the ECL LOGTO

command.

You can assign users to more than one group. Refer to your host operating

system documentation for information about your system. The UNIX id

command enables root users to display the current uid and group

assignment for any login name. The UNIX newgrp command lets users

change between groups. A user can function as a member of only one group

at any time.

A user must be defined as a member of a group (in /etc/group) before using

newgrp to change to it. In the above example, a user who is a member of only

group arusers cannot use newgrp to change to apusers.

Home Directories

UNIX requires you to define a home directory for each login. This directory

is the working directory of the user at login time. 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.

Tip: A user’s home directory can contain startup scripts as well as output from non-UniData applications (such as UNIX text editors). The UniData command stack isalso saved here. If you use UniData accounts as home directories, and users generateother kinds of output there, you may encounter space or performance problems.

Note: The home directory you define for a user must exist. If you define a directoryand you do not create it or set appropriate permissions, the user may be unable to login to UNIX. Some administrative utilities create the directory and set permissionswhen you add a user. Check the documentation for your UNIX systemadministration utility to determine procedures at your site.


Startup Scripts

When a user logs in, the default shell (specified in /etc/passwd) executes a

startup script, if there is one, in the user’s home directory. The filename of the

startup script depends on the user’s default shell. If the shell is the Bourne or

Korn shell, the startup script is called “.profile”. If the shell is the C shell, the

startup script is called “.login”.

Tip: Many UNIX systems offer a default shell script that you can copy into a user’shome directory and then customize. Some systems also execute a system-wide scriptfor all logins. Refer to your host operating system documentation for specificinformation about your system. A sample .login file follows:

setenv TERM vt100stty erase ^Hset path=( $path /usr/ud60/bin)umask 002cd /usr/ud60/PAYABLESudt

This example shows how to use a startup script to ensure that a user logs into

a particular UniData account and receives an ECL prompt, rather than a

UNIX prompt. The example also defines the user’s terminal type, defines the

key sequence for erasing characters, modifies the user’s path to include the

UniData bin directory, and specifies the default permissions on files the user

creates.

Logins and Groups 11-7

Customizing PermissionsWhen you install UniData, the system sets default permissions on system

files and directories, as shown in the following table.

File or Directory NamePermission Settings ofFile/Directory

Permission Settings ofFiles/Subdirectories

udtbin drwxr-xr-x See next rows

udtbin/product.info -rw-r--r-- Not applicable

udtbin/us_admin -r-sr-xr-x Not applicable

udtbin/us_update_db -r-sr-xr-x Not applicable

udthome drwxr-xr-x See following rows

udthome/demo drwxrwxrwx -rwxrwxrwx

udthome/lib drwxr-xr-x

udthome/objcall drwxrwxr-x See next rows

udthome/objcall/demo drwxrwxr-x rw-rw-rw-

udthome/objcall/include drwxrwxr-x rw-r--r--

/usr/ud60/ods drwxrwxr-x Varies

udthome/parttbl Not applicable -rw-r--r--

udthome/sybase drwxrwxr-x Varies

udthome/sys drwxr-xr-x Varies

udthome /sys/HELP.FILE -rw-r--r-- Not applicable

udthome/sys/udtpath -rw-rw-rw Not applicable

udthome/work drwxr-xr-x -rw-rw----

/usr/ud60/include drwxr-xr-x -rw-r--r--

Default Permission for UniData Directories and Files


IBM makes a series of recommendations for customizing these permissions,

as shown in the next table.

Directory or File Guidance

udthome/sys/CTLGTB The default permissions for CTLGTB, the globalcatalog table file, are -rw-rw-rw-. Users responsible forcataloging or deleting cataloged programs need writepermission. Other users need only read permission.

udthome sys/DICT.DICT Users need only read permission. Administrators needwrite permission as well.

udthome/sys/VOC Users need only read permission. Administrators needwrite permission as well.

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

udthome/sys/ CTLG/nand directories and fileswithin thesesubdirectories

CTLG contains a subdirectory for each letter of thealphabet and one for symbols. Users need executepermission to these directories and read access to thefiles in them. Programmers may need read and writepermissions so that they can catalog or delete catalogedprograms.

udthome/demo This directory is used 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 readand write permissions.

Guidelines for Permissions for UniData System Files

Customizing Permissions 11-9

When you create a UniData account, IBM suggests the following guidelines

for setting permissions for the directory, subdirectories, and files in the

account:

Directory or File Guidance

./ Only users who need to create files in the directoryshould have write permission.

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

./CTLG Users need read and execute permissions so they can runlocally cataloged programs. Programmers andadministrators need write permission so they can locallycatalog 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 VOCfile in udthome/sys.) Users must have read and writeaccess to enter their accounts unless you’ve set theVOC_READONLY environment variable. See UsingUniData for more information about the VOC file.

Suggested Permissions for a UniData Account


The following screen shows a long listing for a UniData account called

PAYABLES, incorporating the suggestions outlined in the preceding tables:

% ls -l /usr/PAYABLEStotal 386drwxrwxr-x 2 root unisrc 24 Mar 7 2000 BPdrwxrwxr-x 2 root unisrc 24 Mar 7 2000 CTLG-rwxrwxr-x 1 root unisrc 2048 Mar 7 2000 D_BP-rwxrwxr-x 1 root unisrc 2048 Mar 7 2000 D_CTLG-rw-rw-rw- 1 root unisrc 2048 Mar 7 2000 D_MENUFILE-rwxrwx--- 1 root unisrc 2048 Mar 7 2000 D_SAVEDLISTS-rw-rw-rw- 1 root unisrc 4096 Mar 7 2000 D_VOC-rwxrwx--- 1 root unisrc 2048 Mar 7 2000 D__HOLD_-rwxrwx--- 1 root unisrc 2048 Mar 7 2000 D__PH_-rw-rw-rw- 1 root unisrc 2048 Mar 7 2000 D__REPORT_-rw-rw-rw- 1 root unisrc 2048 Mar 7 2000 D__SCREEN_-rw-rw-rw- 1 root unisrc 2048 Mar 7 2000 D___V__VIEW-rw-rw-rw- 1 root unisrc 2048 Mar 7 2000 D_savedlists-rw-rw-rw- 1 root unisrc 3072 Mar 7 2000 MENUFILEdrwxrwx--- 2 root unisrc 24 Mar 7 2000 SAVEDLISTS-rwxrwx--- 1 root unisrc 105472 Mar 7 2000 VOCdrwxrwx--- 2 root unisrc 24 Mar 7 2000 _HOLD_drwxrwx--- 2 root unisrc 24 Mar 7 2000 _PH_-rw-rw-rw- 1 root unisrc 18432 Mar 7 2000 _REPORT_-rw-rw-rw- 1 root unisrc 18432 Mar 7 2000 _SCREEN_-rw-rw-rw- 1 root unisrc 12288 Mar 7 2000 __V__VIEWdrwxrwxrwx 2 root unisrc 24 Mar 7 2000 savedlists

Customizing Permissions 11-11

Customizing a VOC FileDepending on your application, you may wish to prevent users from

executing certain ECL commands. If you remove the entries corresponding

to these commands from the VOC file in the account, users logged in 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 2002 1VOC.......

COPY1 record listed: DELETE VOC COPY'COPY' deleted.: COPY FROM DICT INVENTORY TO DICT ORDERS ALLNot a verbCOPY

The following table lists ECL commands that create or modify UniData files,

or allow users to execute UNIX system-level commands. You may want to

consider removing some or all of these from the VOC files for your accounts.

Command Description

! Escapes to a UNIX shell prompt.

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

CNAME Changes a filename.

COPY Copies records.

CREATE.FILE Creates files.

CREATE.INDEX Creates an alternate key index.

DELETE Deletes records from VOC or other files.

DELETE.CATALOG Deletes catalog entries.

VOC Commands Security


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

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

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

Customizing UniData

The UDT.OPTIONS command enables you to customize your UniData

environment. UDT.OPTIONS 19 allows you to choose whether superusers

(root access) can bypass security restrictions created by removing entries

from the VOC file. If UDT.OPTIONS 19 is on, UniData prevents even

superusers from executing commands after you remove the entries are from

the VOC file.

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 11-13

If UDT.OPTIONS 19 is off (the default), UniData allows superusers to execute

ECL commands even if the command entries were removed from the VOC

file. When a user logged in as root 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, root users 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 root users to

execute commands that users cannot; turn it on to make root users consistent

with other users.

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

UDT.OPTIONS 19 Command Status Behavior

ON VOC entry exists root can execute command

Others can executecommand

OFF VOC entry exists root can execute command

Others can executecommand

ON No VOC entry root cannot executecommand

Others cannot executecommand

OFF No VOC entry root can execute command

Others cannot executecommand

UDT.OPTIONS 19


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

you to store a record definition 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

UNIX 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 2002 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.

Remote Items 11-15

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 LISTThe next screen shows what happens if VALID is 1 (true):: LIST VOC WITH F1 = PALIST VOC WITH F1 = PA 11:13:27 May 24 2002 1VOC.......

ECLTYPECPCTSP.OPENlistdictLISTDICT6 records listed


The SETFILE CommandYou can also customize security by placing data files in a location with

different UNIX permissions than your UniData account, and then modifying

the corresponding VOC entries to point to the location. Use the SETFILE ECL

command to establish the file pointers, as shown in the following example:

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

You can set the UNIX 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.

The SETFILE Command 11-17

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 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 a user’s .login or .profile 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 UNIX shell prompt or the ECL prompt.

The behavior of LOGIN and LOGOUT paragraphs are summarized as

follows:

■ When a user enters UniData, UniData checks the VOC file in the

account the user is entering for a LOGIN paragraph. If there is one,

UniData automatically executes it.

■ If the user changes accounts with the ECL LOGTO command,

UniData does NOT execute the LOGOUT paragraph in the account

the user is leaving. UniData looks in the VOC file of the account the

user is entering, and executes the LOGIN paragraph there, if there is

one.

■ When a user exits UniData, UniData checks the VOC file in the user’s

current account and executes the LOGOUT paragraph, if one is

there.

Note: You can also use the ECL ON.ABORT command to prevent users fromaccessing the ECL or UNIX prompt. ON.ABORT defines a paragraph that executeswhenever a UniBasic program aborts. See the UniData Commands Reference forinformation about ON.ABORT.


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:

: WHERE/users/testacct: CT VOC LOGINVOC:

LOGIN:PAUDT.OPTIONS 19 ONUDT.OPTIONS 20 ONDISPLAY ENTERING UNIDATA APPLICATION: CT VOC LOGOUTVOC:

LOGOUT:PADISPLAY EXITING UNIDATA APPLICATION:: LOGTO /usr/ud60/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.

LOGIN and LOGOUT Paragraphs 11-19

The next screen shows the response when two of these paragraphs are

executed:

% pwd/users/testacct% udtUniData Release 6.0 Build: (4088)(c) Copyright IBM Corporation 2002.All rights reserved.

Current UniData home is /disk1/ud60/.Current working directory is /users/testacct.ENTERING UNIDATA APPLICATION: LOGTO /usr/ud60/demo: WHERE/users/ud60/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

UNIX shell 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 in as root canaccess an account through the LOGTO command without executing the LOGINparagraph. If a user logged in as root accesses the account directly, UniData executesthe LOGIN paragraph regardless of the setting of UDT.OPTIONS 20.


UniData SQL PrivilegesWhen a user creates a UniData SQL table or view, that user has exclusive

UniData SQL access to it. Regardless of file permissions set at the UNIX level,

no other user can execute UniData SQL operations against the table or view

until the owner grants privileges via the UniData SQL GRANT command.

The UniData SQL REVOKE command allows the owner (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 UNIX file permissions, tables you create in UniData SQL can beaccessed by other UniData tools, such as ECL or UniQuery. The GRANT andREVOKE commands affect UniData SQL operations only.

See the UniData SQL Commands Reference and Using UniData SQL for

additional information about UniData SQL privileges.

UniData SQL Privileges 11-21

Field-Level Security for UniQueryUniData includes functionality to determine UniQuery access on an

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 the UNIX group, 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 UNIX file permissions, other UniData security

implementations, and privileges granted using the QUERY.PRIVILEGE

table. In a SECURE system, unless privileges are granted in the

QUERY.PRIVILEGE table, users cannot access files via UniQuery, regardless

of UNIX permissions or other implementations.

Points to Remember about Field-Level Security

Remember 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.

The QUERY.PRIVILEGE File

UniQuery 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 filewith any records, UniData does not allow any user to access any files on the systemthrough UniQuery.

When you install UniData, the UniQuery security is not implemented, and

there is no QUERY.PRIVILEGE file. If you wish to turn on this feature, 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 FORMATSM ASSOC 15:20:26 Jun 02 2002 1@ID............ TYP LOC.......... CONV NAME........... FORMAT SMASSOC.....

@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

Field-Level Security for UniQuery 11-23

The following table describes each QUERY.PRIVILEGE attribute:

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

The following table shows a very simple example of a QUERY.PRIVILEGE

file:

LIST QUERY.PRIVILEGE PRIV 15:28:31 Jun 02 2002 1QUERY.PRIVILEGE................................... PRIVILEGES

user01*/usr/ud60/demo/INVENTORY 1 2 3 4 5 11/user01*/usr/ud60/demo/CLIENTS ALLDEFAULT OPEN3 records listed

This QUERY.PRIVILEGE file means:

Attributes Description

@ID Defines the user or UNIX group and the file for which youare setting privileges. If you are setting up a systemdefault, @ID is DEFAULT. Otherwise, @ID must be of theformat username*path or PUBLIC*path.

PRIV Multivalued; lists the field(s) to which you are grantingaccess by location in the data file record. You can grantprivileges on all fields in a data file by setting PRIV toALL. If you are setting up a system default, set PRIV toeither OPEN or SECURE.

FULLPATH The absolute UNIX path of the file on which you aresetting UniQuery privileges.

USERNAME The UNIX ID of the user (or group) to which you aregranting privileges.

QUERY.PRIVILEGE Record Attributes


■ 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.

■ 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 Processing

If you have turned on the security feature by creating and populating the

QUERY.PRIVILEGE file, every time a user logs in 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 information, following the following steps:

1. Check for privileges granted to the user’s UNIX group.

If the user’s UNIX group 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 sufficient 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 Security

Complete the following steps to implement the UniQuery field-level security

feature:


1. Log In

With UniData running, log in as the root user. Users do not need to log off.

2. Create QUERY.PRIVILEGE

Change your working directory to udthome/sys, and enter udt to start a

UniData session. Use the ECL CREATE.FILE command as follows:

: WHERE/usr/ud60/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 DICTQUERY.PRIVILEGE.

Make the QUERY.PRIVILEGE file a static hashed file.

3. Set Permissions

The QUERY.PRIVILEGE file and its dictionary should be read-only to all

users except root. Check the UNIX permissions and change them, if

necessary, as follows:

: !ls -l *QUERY*-rw-rw-rw- 1 root sys 2048 Jun 2 16:03D_QUERY.PRIVILEGE-rw-rw-rw- 1 root sys 104448 Jun 2 16:03QUERY.PRIVILEGE:: !chmod 744 *QUERY*: !ls -l *QUERY*-rwxr--r-- 1 root sys 2048 Jun 2 16:03D_QUERY.PRIVILEGE-rwxr--r-- 1 root sys 104448 Jun 2 16:03QUERY.PRIVILEGE:


4. Edit the Dictionary

Use UniEntry, AE, or ED to edit D_QUERY.PRIVILEGE. The dictionary must

look like the following example:

@ID............ TYP LOC.......... CONV NAME........... FORMAT SMASSOC.....

@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)

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

5. Add Records to QUERY.PRIVILEGE

For this step, you may prefer to have users logged out of UniData. As you

add records to the QUERY.PRIVILEGE file, users logging in to UniData

access whatever records are present at the time they log in, which may cause

unexpected results.

Use AE, UniEntry, or ED to populate the QUERY.PRIVILEGE file.


12Chapter

Managing UniData Files

UniData Hashed Files . . . . . . . . . . . . . . . . 12-4

Static Hashed Files . . . . . . . . . . . . . . . . . 12-5

Dynamic Hashed Files . . . . . . . . . . . . . . . . 12-6

Dynamic Files and Overflow . . . . . . . . . . . . . 12-7

Dynamic Files, Part Files, and Part Tables. . . . . . . . . 12-9

When Dynamic Files Are Created . . . . . . . . . . . 12-12

Tips and Constraints for Creating a Dynamic File . . . . . . 12-14

When Dynamic Files Expand . . . . . . . . . . . . . 12-15

Management Tools for Dynamic Files . . . . . . . . . . 12-19

Dynamic Files and Disk Space . . . . . . . . . . . . 12-20


File-Handling Commands . . . . . . . . . . . . . . . 12-27

File Corruption . . . . . . . . . . . . . . . . . . . 12-31

What Causes File Corruption? . . . . . . . . . . . . 12-31

Preventing File Corruption . . . . . . . . . . . . . . 12-32

UniData Detection Tools . . . . . . . . . . . . . . . 12-34

guide . . . . . . . . . . . . . . . . . . . . . 12-34

guide_ndx . . . . . . . . . . . . . . . . . . . 12-39

verify2 . . . . . . . . . . . . . . . . . . . . . 12-40

UniData Recovery Tools . . . . . . . . . . . . . . . . 12-43

dumpgroup . . . . . . . . . . . . . . . . . . . 12-43

fixgroup . . . . . . . . . . . . . . . . . . . . 12-45

fixfile . . . . . . . . . . . . . . . . . . . . . 12-46

Detection and Repair Examples . . . . . . . . . . . . . 12-51

How to Use guide . . . . . . . . . . . . . . . . . . 12-53

Error Messages . . . . . . . . . . . . . . . . . . . 12-56

File Access Messages . . . . . . . . . . . . . . . . 12-56

12 -2 Ad

Block Usage Messages . . . . . . . . . . . . . . . 12-56

Group Header Messages. . . . . . . . . . . . . . . 12-57

Header Key Messages . . . . . . . . . . . . . . . 12-57

Other Header Messages . . . . . . . . . . . . . . . 12-57

Free Block Messages . . . . . . . . . . . . . . . . 12-59

Long Record Messages . . . . . . . . . . . . . . . 12-59

Dynamic File Messages . . . . . . . . . . . . . . . 12-60


In a UniData stores your data database in UniData hashed files of several

different types in the database. 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 used to manage them. See Chapter 3, “UniData and the UNIX

File System,” for information about other file types.

12-3

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 header

■ A pointer array

■ Record IDs

■ Data

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

distribution 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.


Static Hashed FilesStatic hashed files are created with a specified block size multiplier and a

specified modulo (number of data groups). The block size and modulo are

stored 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, the overflow blocks are linked to thatspecific group. If overflow blocks are freed (by deleting records, for example) theyremain linked to the original group and are not available to handle overflow from anyother group in the data file. The space used by the blocks is not returned to theoperating system. Level 1 overflow eventually impacts the performance of a statichashed file. Level 2 overflow impacts performance earlier and more severely, so correctsizing to prevent level 2 overflow is critical.

Overflow Type Description

Level 1 overflow The amount of space required for the data in the group islarger than the amount of space available. This happens ifthe length of a data record is too long for the block size, orif the number of records in the group grows so large thatnot all of the data fits. UniData appends overflow blocksto the original file, and the data portions of records arestored in overflow. The pointers and keys remain in theprimary data file; accessing a record can require two reads,one to determine the address and the second to read thedata in overflow.

Level 2 overflow The amount of space required for pointers and keys islarger than the total size of the group. This happens if toomany records are hashed to the group. UniData createsoverflow blocks which contain both data and keys. Recordaccess can require multiple reads to determine the locationand find the data.

Level 1 and Level 2 Overflow

Static Hashed Files 12-5

Dynamic Hashed FilesDynamic hashed files automatically increase modulo (number of groups) to

minimize level 2 overflow. When viewed at the operating system level, the

structure of dynamic files is different from that of static files. A dynamic file

is actually a 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 screen shows the structure of the ORDERS file in the UniData

demo database:

% ls -l...-rw-rw-rw- 1 root sys 2048 May 19 12:04D_MENUFILE-rw-rw-rw- 1 root sys 3072 May 19 12:04 D_ORDERS-rw-rw-rw- 1 root sys 2048 May 19 12:04D_PARAGRAPHS...-rw-rw-rw- 1 root sys 2048 May 19 12:04 MENUFILEdrwxrwxrwx 2 root sys 1024 May 22 14:17 ORDERS-rw-rw-rw- 1 root sys 2048 May 19 12:04PARAGRAPHS

% ls -l ORDERStotal 66-rw-rw-rw- 1 root sys 24576 May 19 12:04 dat001-rw-rw-rw- 1 root sys 9216 May 19 12:04 over001

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


Dynamic Files and Overflow

Dynamic files automatically change size (both physical size and modulo) as

you add data 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.

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, the additional group is added 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 with the

CONFIGURE.FILE command or the memresize command. Use FILE.STAT,

ANALYZE.FILE, or GROUP.STAT to display the split/merge type.

Dynamic Hashed Files 12-7

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%, so 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%, so 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

(/usr/ud60/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, so

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, so 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


Selecting a Split/Merge Type

Use 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 is 0. This hash type

provides a more even distribution of keys in groups in dynamic files. If key

distribution 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.

Dynamic Files, Part Files, and Part Tables

UniData allows a dynamic file to have multiple dat, over, and idx files, so that

a dynamic file does not have the 2 gigabyte (GB) limit as does a static file.

These “part files” can reside in different file systems. Each part file can

approach 2 GB in size. The total number of part files in a dynamic file cannot

exceed 255. Part files are numbered sequentially by type (for instance, dat002,

over002, and idx002).

The UniData configuration parameter MAX_FLENGTH defines the

maximum size, in bytes, for a “part” of a dynamic file. UniData distributes

“part files” across file systems using ASCII files called “part tables.” A part

table:

■ Lists eligible file systems into which dynamic files are allowed to

expand.

■ Specifies the amount of reserved space on each file system. Reserved

space is not available for dynamic file expansion. Defining reserved

space reduces the probability of the disk becoming full.

The default value for MAX_FLENGTH, set when you install UniData, is 1GB

(1073741824 bytes). You can increase MAX_FLENGTH, but the maximum

value is (2 GB – 16 K).


Location of Part Tables

System Default Part Table

The UniData installation procedure creates a system default part table,

udthome/parttbl. The location of the system default part table is identified by

the UniData configuration parameter PART_TBL.

Per-File Part Tables

You can also create individual part tables for dynamic files using vi or any

other UNIX text editor. Assign a part table to a file by using the PARTTBL

keyword with the CREATE.FILE and memresize commands. Supply the full

path of the ASCII file you wish to use as a part table. UniData copies the

ASCII file into the dynamic file directory, where it becomes the part table for

the dynamic file. Specifying individual part tables allows you to balance the

creation of part files across volumes in your system. In the following

example, the PARTTBL keyword assigns a part table to a new dynamic file:

: CREATE.FILE TEST.FILE 3,2 DYNAMIC PARTTBL /disk1/unidata/parttblCreate file D_TEST.FILE, modulo/1,blocksize/1024Hash type = 0Create dynamic file TEST.FILE, modulo/3,blocksize/2048Hash type = 0Split/Merge type = KEYONLYAdded "@ID", the default record for UniData to DICT TEST.FILE.: !ls -l TEST.FILEtotal 22-rw-rw-rw- 1 terric unisrc 8192 Jul 1 14:38 dat001-rw-rw-rw- 1 terric unisrc 2048 Jul 1 14:38 over001-rw-rw-rw- 1 terric unisrc 37 Jul 1 14:38 parttbl

Notice that the dynamic file directory contains the parttbl, which was copied

from /disk1/unidata.

Components of a Part Table

The name of the system default part table (created at installation time) is

udthome/parttbl. The default parttbl looks like:

% more /usr/ud52/parttbl. 1000%


The following table describes the fields in the part table:

Use vi or any other UNIX text editor to create and edit per-file part tables or

to modify the default part table for your system. A sample part table follows:

. 10000000/usr/unidata/partfiles 10000/disk1/unidata/partfiles 10000

Part Table Tips and Constraints

Consider the following points if you are creating or modifying part tables:

■ Do not use a dynamic file directory as an entry in the parttbl. This

causes a number of problems, including difficulty resolving the links

to part files and the creation of part files from one dynamic file in the

directory for another dynamic file. This, in turn, causes failures when

users attempt to execute the CLEAR.FILE or DELETE.FILE

command on one of the two dynamic files.

■ Do not use multiple entries in the parttbl that resolve to the same

device ID. This causes confusion when UniData attempts to check

reserved space against available space.

■ If you move the system default part table, change the value of the

configuration parameter PART_TBL.

Field Description

Path Name of the file system; the “.” in the default tableindicates the file system where a UniData dynamic file iscreated. The “.” may be used as the first entry in the table;all other entries must be the absolute UNIX path (forinstance, /disk6/files).

Reserved Space Amount of free space (in 512-byte blocks) that UniDatashould leave in the file system after creating part filesthere.

Part Table Fields


■ When you create an ASCII file to use as a per-file part table,

remember that UniData places a copy of that file in a dynamic file

directory each time you specify it with the PARTTBL keyword

(CREATE.FILE or memresize). If you wish to add a partition or

otherwise edit the file, you need to edit the copy in each dynamic file

to which it is assigned, as well as at the location where you created

the file.

■ If you execute the memresize command to change the parameters of

a dynamic file, and you specify the PARTTBL keyword for a file that

already has a per-file part table, you will overwrite the existing per-

file part table.

When Dynamic Files Are Created

The 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_FLENGTH

■ minimum 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 Directory

The dynamic file directory is located in the UniData account where

CREATE.FILE was executed.

Locating the Part Files

The part files (or UNIX links to them) are located in the dynamic file

directory. UniData reserves space for part files on the UNIX file system where

the dynamic file directory is located (the resident file system) by making the

following assessments:


■ If the part table (per-file if one exists, or system default otherwise)

has an entry for that file system, use the reserved space defined for

that entry. For instance, if the dynamic file is

/usr/ud60/demo/ORDERS, UniData checks the operating system

file system tables for the UNIX file system, or device id, where

/usr/ud60/demo resides, and then checks the part table for an entry

for that file system. Depending on the configuration of the system,

/usr/ud60/demo might reside in a file system called /usr, or

/usr/ud60, or /usr/ud60/demo.

■ If the part table does not have an entry for that file system, use the

reserved space figure associated with the “.” entry.

UniData checks the resident file system for space as follows:

■ The space available in the file system must be more than the sum of

the estimated file size and the reserved space requirement.

■ If there is sufficient space, dat001 and over001 are created in the

dynamic file directory.

If there is not enough space in the file system, UniData:

■ Checks each file system that has an entry in the part table.

■ Creates dat001 and over001 on the first file system that meets the

space requirement.

■ Creates UNIX links in the original dynamic file directory.

The following screen illustrates creating a dynamic file in the current account

directory:

: CREATE.FILE DYN_TEST 3,1 DYNAMICCreate file D_DYN.TEST, modulo/1,blocksize/1024Hash type = 0Create dynamic file DYN.TEST, modulo/3,blocksize/1024Hash type = 0Split/Merge type = KEYONLYAdded "@ID", the default record for UniData to DICT DYN.TEST.:: !ls -l DYN_TESTtotal 10-rw-rw-rw- 1 terric unisrc 4096 Apr 4 17:43 dat001-rw-rw-rw- 1 terric unisrc 1024 Apr 4 17:43 over001: !printenv MAX_FLENGTH1073741824:


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.”

The following example shows what happens when there is insufficient space

on the resident partition of the dynamic file. The part table used in the

example is one that stipulates a very large reserved space on the current file

system, thereby forcing the part files to another file system:

: CREATE.FILE LARGE.TEST 17,8 DYNAMIC PARTTBL /home/terric/parttblCreate file D_LARGE.TEST, modulo/1,blocksize/1024Hash type = 0Create dynamic file LARGE.TEST, modulo/17,blocksize/8192Hash type = 0Split/Merge type = KEYONLYAdded "@ID", the default record for UniData to DICT LARGE.TEST.: !ls -l LARGE.TESTtotal 6lrwxrwxrwx 1 terric unisrc 42 Jun 8 15:52 dat001 -> /usr/unidata/partfiles/AALARGE.TEST/dat001lrwxrwxrwx 1 terric unisrc 43 Jun 8 15:52 over001-> /usr/unidata/partfiles/AALARGE.TEST/over001-rw-rw-rw- 1 terric unisrc 69 Jun 8 15:52 parttbl

Notice that the dat001 and over001 files were created in a different partition

and are referenced by UNIX links.

Tips and Constraints for Creating a Dynamic File

Choosing the Initial Modulo

If 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 that you choose a block

size that is at least 10 times the average record length. Load factor in a

KEYDATA file is based 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 that 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.

When Dynamic Files Expand

When records are added or updated in a dynamic file, a data part file,

overflow part file, or index part file may expand. Whenever a write operation

requires additional blocks, the following considerations determine whether

a new part file is needed, and if so, where it is located.

Determining Whether a New Part File Is Needed

UniData first checks to see if the part file can expand in its current location.

The part file can expand if the following two conditions are true:

■ The size of the part file is less than MAX_FLENGTH.

■ There is enough space in the file system where the part file resides to

complete the current write without expanding into reserved space.

For instance, if 10 blocks are needed, and the difference between

available and reserved space is more than 10 blocks, the part file can

expand.


Note: To check for space, UniData resolves the directory where the part file resides toits UNIX file system, and then checks the part table for an entry for that file system.For example, if the part file is /usr/ud60/demo/ORDERS/dat001, UniData locatesthe UNIX file system where /usr/ud60/demo/ORDERS resides, and checks the parttable for an entry for that file system. If there is an entry, UniData takes the reservedspace defined for that entry. If not, UniData uses the reserved space defined for the“.” entry.

If both conditions are true, UniData adds blocks to the part file and continues

processing. If either condition is not true, and the part file is an overflow part

file, UniData checks all the existing overflow part files. If one of those part

files meets the conditions, that part file is expanded. If no existing part file can

expand, UniData must create a new overflow part file. If the part file is a data

part file, UniData can expand only the last data part file created. For instance,

if the dynamic file directory contains dat001 and dat002, only dat002 can

expand.

Locating Space For a New Part File

The following table describes how UniData computes an estimated size for

the new part file, depending on its type.

Part File Type Estimated Size

Data part file The smaller of the following:

• The larger of (size of dat001) and (current modulo *block size)

• MAX_FLENGTH

Overflow part file The smaller of the following:

• The larger of (size of over001) and (current modulo *block size)

• MAX_FLENGTH

Index part file The smaller of the following:

• The larger of (size of dat001) and (current modulo *block size)

• MAX_FLENGTH

Estimating Size Requirements for Part Files


UniData searches the partitions listed in the part table for the dynamic file for

a partition that meets the requirement:

available space > (estimated size + reserved space)

UniData searches the part table in the following order:

1. The resident partition of the dynamic file, because locating the part

file in the dynamic file directory saves the overhead required by a

symbolic link.

2. All entries, in order from top to bottom.

Upon finding a partition that meets the space requirement, UniData:

■ Creates an appropriate directory, if needed.

■ Creates the new part file.

■ Creates a UNIX symbolic link in the dynamic file directory, if

needed.

If no partition meets the space requirement, UniData:

■ Checks to see which partition has the largest amount of free

space (available space - reserved space).

■ If the amount of free space is 20% or more of the estimated size,

creates the new part file at that location.

■ If no partition has sufficient free space (20% or more of the

estimated size of the part file), UniData prompts the user to

reclaim space or change the part table.

How Part Files Are Stored

When dynamic files expand into a different file system, UniData creates

directories in the new file system for the part files. To prevent duplicate

directory names, UniData assigns a prefix to each. The prefixes are assigned

based on an index in the target file system called .fil_prefix_tbl (a hidden

ASCII text file maintained by UniData). A sample .fil_prefix_tbl follows:

% more .fil_prefix_tblAA:/home/terric/SAMPLEAB:/home/terric/NEWACCTAC:/home/terric/NEWACCT/MULTI1


Each entry in .fil_prefix_tbl relates a prefix (AA, AB, and so on) to the path of

a parent directory for dynamic files. The parent directory can be a UniData

account directory or a UniData multilevel file directory. Using the sample

table, this creates the following directories:

■ If a dynamic file originated in the account directory named

/home/terric/SAMPLE, the directory created when the file expands

is called AAfilename.

■ If a dynamic file originated in the account directory named

/home/terric/NEWACCT, the directory created when that file

expands is called ABfilename.

■ If a dynamic file is a subfile of the multilevel file

/home/terric/NEWACCT/MULTI1, the directory created when

that file expands is called ACfilename.

The following screen shows a directory listing that corresponds to the prefix

table from the previous example:

% pwd/usr/unidata/partfiles% ls -al|moretotal 16drwxrwxrwx 7 root sys 1024 Jun 6 14:16 .drwxrwxrwx 3 root sys 1024 Jun 6 11:40 ..-rw-rw-rw- 1 terric unisrc 78 Jun 6 14:15.fil_prefix_tbldrwxrwxrwx 2 terric unisrc 1024 Jun 6 11:43AASAMPLE_FILE3drwxrwxrwx 2 terric unisrc 1024 Jun 6 11:46AATESTINVdrwxrwxrwx 2 terric unisrc 1024 Jun 6 14:13ABFAMILY_FILE1drwxrwxrwx 2 terric unisrc 1024 Jun 6 14:15 ACSUB1drwxrwxrwx 2 terric unisrc 1024 Jun 6 14:16 ACSUB2

Warning: Do not edit or remove .fil_prefix_tbl. You will encounter unexpectedresults creating, updating, and deleting dynamic files. If .fil_prefix_tbl isinadvertently removed from a target directory, you can execute the system-level fixtblcommand in each of your UniData accounts to rebuild it.


Management Tools for Dynamic Files

UniData supplies three tools for system administrators to manage dynamic

files. The tools identify and resolve some of the inconsistencies that result if

users manipulate part files at the operating system level or inadvertently

modify or delete the prefix table in a target partition.

auditor

The system-level auditor tool reports inconsistencies between the symbolic

links and the hidden files which should be resolved to prevent apparent data

loss. The tool also reports an error if a part file is not found in the correct

destination. Execute auditor from the UNIX prompt or use ! to execute

auditor from the ECL command prompt. Your current working directory

must be a UniData account. auditor checks all the dynamic files that have

pointers in the VOC file of the current account.

fixtbl

The system-level fixtbl command detects the following error conditions:

■ .fil_prefix_tbl is missing. If a dynamic file directory contains links to

another partition, but there is no .fil_prefix_tbl at that location, fixtbl

can create a new one.

■ A prefix in .fil_prefix_tbl references a different directory than the

symbolic links from a dynamic file in the current account. fixtbl can

select a new prefix, then move and relink the part files for

consistency.

■ There are symbolic links from a dynamic file to another partition, but

there is no entry in the .fil_prefix_tbl that matches the links.

Assuming the prefix in the links is not used by another directory,

fixtbl can create an entry in .fil_prefix_tbl that is consistent with the

links from dynamic files in the current account directory.

Note: You must stop the UniData daemons (with stopud) before executing fixtbl.


mvpart

The system-level mvpart command moves one or more part files of a

dynamic file to a different location. mvpart sets or resets symbolic links, if

needed, and creates or updates a prefix table (.fil_prefix_tbl) at the

destination location, if needed. Using mvpart ensures that the links, file

locations, and prefix tables remain synchronized.

Note: You must stop the UniData daemons (with stopud) before executing mvpart.

Dynamic Files and Disk Space

While it is possible for a dynamic file to shrink with respect to modulo, the

disk space “freed” by merging is not necessarily made available for other use.

When a group splits, the extra group added to the dynamic file is assigned to

the existing group that split. When a merge occurs, the “freed” group

remains allocated to the dynamic file, for use if the original group splits

again.

When 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.

Refer to 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

UNIX. 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 screens show splitting and merging in a dynamic file. The first

screen 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: !ls -l SIZE.TESTtotal 20-rw-rw-rw- 1 terric unisrc 8192 Jun 4 17:23 dat001-rw-rw-rw- 1 terric unisrc 2048 Jun 4 17:23 over001

Notice the following points:

■ Because the file was created with a block size multiplier of two, the

size of each block is 2,048 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 screen shows what happens when the dynamic file is populated

with records:

: 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 4 groups in level one overflow.Number of records = 537Total number of bytes = 19858...File has 1 over files, 1 prime files

: !ls -l SIZE.TESTtotal 92-rw-rw-rw- 1 terric unisrc 26624 Jun 4 17:25 dat001-rw-rw-rw- 1 terric unisrc 20480 Jun 4 17:25 over001


■ 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 screen shows the results of deleting all records with a select

list:

: SELECT SIZE.TEST

537 records selected to list 0.

>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...: !ls -l SIZE.TESTtotal 92-rw-rw-rw- 1 terric unisrc 26624 Jun 4 17:28 dat001-rw-rw-rw- 1 terric unisrc 20480 Jun 4 17:28 over001


■ Merging has reduced the modulo to 10.

■ The file size as measured by the UNIX ls command 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 screen 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

: !ls -l SIZE.TESTtotal 20-rw-rw-rw- 1 terric unisrc 8192 Jun 4 17:30 dat001-rw-rw-rw- 1 terric unisrc 2048 Jun 4 17:30 over001

The ECL CLEAR.FILE command returns the file to its original modulo and

size.

Sequentially Hashed Files

A sequentially hashed file has the same structure as a dynamic file, but all

records are stored 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 a 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.


A sequentially hashed file is used for files where the majority of access is

based on the primary key.

The dat001 File


sequentially 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 File

As 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 over002 file resides in a different file system than the over001 file,

UniData creates a link to over002 in the original sequentially hashed file.

If the sequentially hashed file has level 2 overflow, the file should be rebuilt

using the shfbuild command.

The gmekey File

Each sequentially hashed file contains a static, read-only file called the

gmekey file. This file is read 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 blocksize multiplier] [-i infile] outfile


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


: AE VOC SEQUENTIALTop of New "SEQUENTIAL" in "VOC".*--: I001= F002= SEQUENTIAL003= D_SEQUENTIAL*--: FIFiled "SEQUENTIAL" in file "VOC".


File-Handling CommandsUniData includes a variety of commands for you to create and delete

UniData files, as well as to obtain status information, change file parameters,

and diagnose and repair damaged hashed files.

Note: Refer to Chapter 3, “UniData and the UNIX File System,” for additionalinformation about index files and index log 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 dynamichashed files, dictionary files, DIR files, multilevel filesand multilevel directories.

DELETE.FILE Deletes a UniData file; works for static, dynamic, andsequentially 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 multilevelsubdirectories.

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 multilevelsubdirectories or dictionary files.

SETFILE Sets a pointer to a UniData file; works for static, dynamic,and sequentially files, DIR files, multilevel files, andmultilevel directories. Does not work for dictionary filesor for multilevel subfiles or subdirectories.

RECORD Identifies group where a primary key is hashed, anddisplays a list of keys hashed to that group. Works forstatic, dynamic, and sequentially hashed files and formultilevel subfiles. Does not work for dictionaries,directory files, multilevel directories, or multilevelsubdirectories.

ECL File Commands

File-Handling Commands 12-27

See the UniData Commands Reference for detailed information about the

syntax of file-handling commands.

FILE.STAT Displays statistics about a hashed file, including modulo,block size, hash type, and record statistics. Works forstatic, dynamic, and sequentially hashed files, or static ordynamic multilevel subfiles. Does not work fordictionaries, directory or multilevel directory files, ormultilevel subdirectories.

GROUP.STAT Displays record distribution in a UniData hashed file.Works for static, dynamic, or sequentially hashed files, orstatic or dynamic multilevel subfiles. Does not work fordictionaries, directory or multilevel directory files, ormultilevel subdirectories.

RESIZE Changes the modulo, block size, or hash type of aUniData static hashed file. Works on static hashed filesand static hashed multilevel subfiles. Does not work ondirectories, multilevel directories or subdirectories,dictionaries, or any dynamic hashed file or subfile.

ANALYZE.FILE Displays statistics, including current and minimummodulo, hash type, block size, split/merge type, splitload, merge load, and record distribution for a dynamicfile. Works on dynamic and sequentially hashed files anddynamic hashed multilevel subfiles only.

CONFIGURE.FILE Changes split/merge type, split load, merge load, parttable, or minimum modulo for a dynamic file. Works ondynamic hashed files and dynamic hashed multilevelsubfiles only.

REBUILD.FILE Reconstructs a dynamic file using current settings forsplit load, merge load, and minimum modulo. Used afterCONFIGURE.FILE. Works on dynamic hashed files anddynamic hashed multilevel subfiles only.

CHECKOVER Checks UniData hashed files for level 2 overflow. Workson all UniData hashed files and subfiles. Used to check allfiles in a UniData account directory.

Command Description

ECL File Commands (continued)


The next table describes UniData system-level file-handling commands.

Command Description

auditor Checks all dynamic files in a UniData account to reportinconsistencies between symbolic links, part file locations,and file prefix tables.

checkover Checks UniData hashed files for level 2 overflow. Workson all UniData hashed files and subfiles. Checks all files ina UniData account directory. You can execute the system-level version with UniData shut down or with UniDatarunning.

dumpgroup Unloads the contents of a damaged group in a hashed file;you can execute with UniData shut down or with UniDatarunning.

fixfile Repairs damaged groups in a file; you can execute withUniData shut down or with UniData running.

fixgroup Repairs a damaged group; you can execute with UniDatashut down or with UniData running.

fixtbl Resolves inconsistencies between symbolic links and fileprefix tables for all dynamic files in a UniData account.You must execute with UniData shut down.

guide Identifies damaged hashed files or dictionary files. Youcannot execute if UniData is shut down.

guide_ndx Identifies corruption in an index file.

memresize Changes the modulo, block size, or hash type of a UniDatahashed file. Works on static or dynamic hashed files andmultilevel subfiles. Does not work on sequentially hashedfiles, directories, multilevel directories or subdirectories,or dictionaries. This command uses shared memory anddisk storage, rather than disk storage alone, as workingstorage. Although you execute this command from aUNIX prompt, you cannot execute it if UniData is shutdown. memresize also converts static files to dynamicfiles, dynamic files to static files, and changes thesplit/merge type and part table for dynamic files.

UniData System-Level File Commands

File-Handling Commands 12-29

mvpart Moves a part file from one location to another, keepinglinks, location, and file prefix tables consistent. You mustexecute with UniData shut down.

shfbuild Converts a static or dynamic file to a sequentially hashedfile.

verify2 Identifies damaged hashed files or dictionary files; youcannot execute if UniData is running.

Command Description

UniData System-Level File Commands (continued)


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 information 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 allow 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, killing a UniData

process using a UNIX kill -9 command.

■ Incomplete writes; for example, a disk runs out of space before a

write is complete. This is a rare condition, since UniData prompts the

user to reclaim space when this occurs.

Note: Overflowed files are more likely to become corrupted, since multiple I/Ooperations 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 andcorresponding overflow blocks are out of synch. The increased chance of corruption isparticularly significant for files in level 2 overflow.

File Corruption 12-31

Preventing File Corruption

You 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

that 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


There are other operations that can corrupt UniData files. The following list

contains some examples:

■ Using UNIX file manipulation commands (for example, rm, mv, cp,

and ln) on UniData hashed files while UniData is running can

damage files. You should always shut UniData down before

performing any UNIX-level manipulations on UniData files.

■ Attempting to view/edit a UniData file with a UNIX 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 with a UNIX command (tar,

dd, cpio) 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 filebeing restored.

Command Risk Factor

deleteuser This UniData command first tries to execute a UNIX kill-15. If the kill -15 is unsuccessful after 5 seconds,deleteuser executes a UNIX kill -9 command.

stopud -f This syntax of the stopud command does not allow writesto complete before logging users off.

UniData Commands That Can Corrupt a File


■ Using system-level maintenance tools (for example, online file

checking, which is supported under some UNIX versions) can

damage a file, although this is not a common cause of corruption.

File Corruption 12-33

UniData Detection ToolsUniData supplies the following tools for detecting damaged files:

■ guide — Use the guide command to detect file damage when

UniData is running.

■ verify2 — Use the verify2 command to detect file damage when

UniData is not running.

guide

Syntax:

guide [file1, file2,...][-options]

Note: You may supply guide with the name of a single UniData file or a series of filenames separated by commas or spaces. If you do not specify any files, guide processesall files in the current UniData account directory.

Description

guide is a system-level utility that provides detailed statistics and

suggestions for optimizing file size and ensuring data integrity.


Options

The following table lists the options available for the guide command.

Option Description

-a |-A [filename]

-na | -NA

(no advice)

Controls whether UniData includes management advicein the output. The default filename for the adviceinformation is GUIDE_ADVICE.LIS. You cannot combinethe -a and -o options, because UniData assumes the -aoption when the -o (output) option is present. You mayuse 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 abrief summary of statistical information. The default filename is GUIDE_BRIEF.LIS.

-d1 | -D1 Includes minimum statistics about the file. Does not workwith the -ns option.

-d2 | -D2 Includes statistical information helpful in estimatingcorrect file sizing. This is the default. Does not work withthe -ns option.

-d3 | -D3 Includes all information reported with -d2, plusadditional 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 structuralerrors in the selected files. The default error list file nameis GUIDE_ERRORS.LIS. The -e option is assumed whenthe -o (output) option is present, and may not be specifiedat that time. You may, however, use the -ne option incombination with the -o option.

-f | -F [filename] Specifies the file that should receive a list of damagedgroups. The default file name, if none is specified, isGUIDE_FIXUP.DAT. UniData creates this file only if itdetects errors.

-ha | -HA Evaluates all hash algorithms (default). Note: the -hoption has no effect if specified for a dynamic file.

guide Command Options

UniData Detection Tools 12-35

-h0 | -H0 Evaluates algorithm 0. Note: the -h option has no effect ifspecified for a dynamic file.

-h1 | -H1 Evaluates algorithm 1. Note: the -h option has no effect ifspecified for a dynamic file.

-i | -I [filename] Directs the guide utility to evaluate all of the files in the filenamed filename. GUIDE_INPUT.DAT is the default. Thefile should be composed of one file name per line. UniDatatreats blank lines and lines that begin with an exclamationpoint as comments.

-l | -L [count] If you specify the -d3 option, the guide utility displays thekeys for the largest records. The key appears in quotesand, if truncated, is followed by an asterisk (*). The -loption controls the number of records that display. Thedefault value is three. Specifying a large number ofrecords results in a significantly slower analysis.

-m | -M

new_modulo

Directs the utility to evaluate the effects of a differentmodulo upon the specified file. You must use this optionin conjunction with the -h (hash test) option. This optionhas no effect when specified for a dynamic file.

-o | -O [filename] Controls whether output is combined or directed toseparate files. If -o is specified, UniData directs all outputto the file specified by filename. If you do not specify a filename, UniData directs the output from guide to “standardout” (usually, your terminal).

-Z num_child_processes Defines the number of concurrent processes to use whenanalyzing the file. The default is 4. If the file guide isanalyzing has less than 100 groups, guide only uses oneprocess.

Option Description

guide Command Options (continued)


-p | -P page_length

-np | -NP

(no pagination)

Controls the display of guide output when you specify the-o option and directs output to the terminal. Specify -np toscroll the output past with no pause. Specify -p page-lengthto pause after displaying each page and prompt with thefollowing message: “Press RETURN to continue...” Thefollowing 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 screendisplay. The default value is 24.

-r | -R [filename] Specifies whether to produce a reporting file. The filenamemust be the UNIX file specification of a UniData databasefile, previously created by the CREATE.FILE command.Use this option to generate file statistics reports usingUniQuery. Copy a dictionary for the report file fromudthome/sys/D_UDT_GUIDE.

-s | -S count If you specify the -d3 option, the guide utility displays thekeys for the smallest records. UniData displays the key inquotes. If the key is truncated, it is followed by an asterisk(*). The “-s count” option controls the number of records toappear in sorted order. The default value is three. Largevalues result in a significantly slower analysis.

-s | -S [filename]

-ns | -NS

(no statistics)

Controls whether UniData includes statistical informationabout the file in the output file. If you do not specify afilename, UniData uses GUIDE_STATS.LIS. (UniDataassumes the -s (statistics) option when the -o (output)option is present, and may not be specified at that time.)You may use the -ne (no errors) option in combinationwith the -o option.

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.

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 six-digit 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 will need to be purged periodically.

guide Report File

You can use the -r option of guide to create a UniData file containing

statistical information about your database. To use the option, complete the

following steps:

1. Create a UniData file in the account where 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.

File Description

GUIDE_ADVICE.LIS Displays management advice about files that are poorlysized 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 Produces a list of damaged groups that can be used asinput for fixfile. You can also use this list to input filenames/group numbers for dumpgroup/fixgroup.

guide Output Files


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 offsetof 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. Although guide works againstrecoverable files, guide itself is not recoverable. You must reapply file updates andfixes performed by guide during recovery from a system or media failure.

guide_ndx

Syntax:

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 run time 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 ALLcommand. Using the ALL option deletes all alternate key indexes and the index fileitself.

verify2

Syntax:

verify2 [-Y | -y] [-H | -h block address] [-O | -o block address]

Description

The verify2 command, like guide, detects file corruption. Although verify2

does not produce as much information as guide, and does not produce the

damaged group list for repair, verify2 runs much more quickly, runs with

UniData down, and can be used for a rapid scan of files.


Parameters

The following table describes the parameters for verify2.


[-Y | -y] Writes the file name and @ID of damaged records to a filecalled /tmp/vrfy2.pid, where pid is the UNIX process IDof the process that executed verify2.

[-H | -h block address] Bypasses checking the block whose hexadecimal addressis block address. This option enables you to bypass a singledamaged block, if you know its address, and examine therest of the file.

[-O | -o block address] Same as -h option, but -o allows you to bypass a block inthe overflow portion of a dynamic file.

verify2 Parameters


The following screen shows typical output from verify2 on files that are not

damaged:

# verify2 ORDERSStatic File Name --------------> ORDERSFile Size ---------------------> 104448 (102 blocks)Modulo ------------------------> 101Hash Type ---------------------> 0Block Size --------------------> 1024Number of groups checked: 101file is in good status.

# verify2 DYN.TESTDynamic File Name -------------> DYN.TESTPrimary File Number -----------> 1Overflow File Number ----------> 1Modulo ------------------------> 3Minimal Modulo ----------------> 3Hash Type ---------------------> 0Block Size --------------------> 1024Number of groups checked: 3file is in good status.The following screen shows output from verify2 on a damaged file:# verify2 TEST.FILEStatic File Name --------------> TEST.FILEFile Size ---------------------> 104448 (102 blocks)Modulo ------------------------> 101Hash Type ---------------------> 0Block Size --------------------> 1024the 0th[10053] off_lens error,offset=7ff,len=110.group 1 errors in header(2048).Number of groups checked: 1011 key(s) are damaged.file has something damaged.

Notice that group 1 is damaged.

Note: It is possible to write a shell script to invoke verify2 and direct the output to afile. Bear in mind that the verify2 command directs its output to the standard errorchannel (stderr), not the standard output channel (stdout).


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.

Note: Although dumpgroup, fixgroup, and fixfile work against UniData recoverablefiles, their actions are not recoverable. If you are recovering from a system crash ormedia failure, any file repairs that took place since your last backup are not includedin logs or archives. You should check your files after recovery (using guide or verify2)and perform any needed repairs before users access them.

dumpgroup

Syntax:

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 12-43

Parameters

The following table describes each parameter of the dumpgroup syntax.

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 UNIX 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 aname that does not already exist in your account name. If you specify a duplicatename, the preexisting file may be overwritten.


filename Specifies the name of the file containing groups to bedumped.

group.no Specifies the number of the group to be dumped. Theoutput from either guide or verify2 identifies groups thatare damaged. Use this information to select groups toprocess.

[-doutputfile] Specifies the name of a file that contains the readablerecords from the dumped group, in an uneditable form. Ifyou do not specify the -d parameter with an outputfile,the output prints to screen. To load outputfile back into thefile, use fixgroup. Note: No space is allowed between -dand outputfile.

[-p] Converts nonprinting field markers to printablecharacters in editable output file. This option is only validif -d is used.

dumpgroup Parameters


fixgroup

Syntax:

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.

The following table describes each parameter of the syntax.


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. Ifyou do not specify an input file argument, fixgroup simplyclears the specified group, without reloading it.

Note : No space is allowed between -i and inputfile.

[-k] Allows fixgroup to reload the damaged records frominputfile without zeroing the group first. This option maybe useful if the group was updated since dumpgroup wasexecuted. However, for best results, do not allow access toa file while it is being repaired, and clear the damagedgroups rather than using the -k option.

fixgroup Parameters


Warning: If you execute fixgroup without an input file argument, UniData clearsthe damaged group. Be sure that you save the readable records with dumpgroupbefore clearing the group. If you clear the damaged group and you have not saved thereadable records, the data in that group is lost. The syntax for clearing a groupwithout reloading it is:

fixgroup filename group.no

UniData displays a warning message before clearing the group, as


%fixgroup INVENTORY 5Fixgroup INVENTORY 5 will make group 5 empty,

do you wish to do it ? [y/n]

fixfile

Syntax:

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} Directs all output to the terminal only. Each readablerecord is described in a new line that includes the recordkey and the record length. All attributes in the recordappear on separate lines, each line indented by twospaces. Special and nonprintable characters are translatedas follows:

Attribute Mark — New line

Value Mark — “ } ”

Subvalue Mark — “ | ”

Text Mark — “ { ”

Non-printables — “ . ”

The -t and -d parameters are mutually exclusive andcannot be used together.

{-dfilename} A file specification is required. For static files, thereadable records are dumped to this file in uneditableformat. For dynamic files, this file is created, but theactual records are dumped to a file in /tmp.

With the -d option, UniData also writes the records, inreadable format, to a directory in your current UniDataaccount. This directory contains an ASCII file for eachreadable record in the group. The records are in a formatsuitable 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, thedamaged groups are not cleared. This has the effect ofdumping the readable records for examination, butleaving the file corrupt. If you specify the -d and -f optionalong with the -k option, UniData repairs the file andreturns the readable records to the group. Anyunreadable records that were not dumped remain in thefile as well.

fixfile 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. The group is not

cleared or repaired. 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:

{-p} If you specify the -p option with the -d option, allnonprinting characters and characters with specialmeaning to UniData are translated. This translationapplies to the editable ASCII files created by the -doption. If you do not specify the -p option, only attributemarks are translated.

{-f} If you specify the -f option with the -d option, UniDataclears the damaged group and restores the records thatwere dumped back into the group, creating a fixed filewith all readable data restored. You must specify the -doption with the -f option.

[-mfilename] UniData writes all error messages and statistics to the fileyou specify, instead of the terminal.

[-wdirectory] UniData creates the work files that are generated in thedirectory you specify.

{-ifilename} UniData uses this file as the source of the names ofdamaged files and groups to be repaired. If you do notuse this option or the {filename group.no} option, UniDatauses the GUIDE_FIXUP.DAT file under the currentdirectory. This option is mutually exclusive with {filenamegroup.no}.

{filename group.no} The file name and group number that contains thecorruption. If you do not use this option or the {-ifilename}option, UniData uses the GUIDE_FIXUP.DAT file underthe current directory. This option is mutually exclusivewith the {-ifilename} option.


fixfile Parameters (continued)


■ A UNIX 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 or verify2) 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. UniData uses this

file 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 therecords when it creates the “editable” files. Otherwise, only attribute marks aretranslated 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 andthe 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:

■ A UNIX directory for each file-group combination being repaired.

The directories are named FILE_GROUP, where FILE is a damaged

file (from GUIDE_FIXUP.DAT or verify2) 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 name is the key

for the corresponding 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 /tmp (or in the directory identified by the TMP

environment variable) and is named ud_dp_pid, where pid is the

UNIX process id of the process that executed fixfile.

Note: If you specify the -p option, fixfile translates nonprinting characters in therecords when it creates the editable files. Otherwise, UniData only translatesattribute 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 thesecond 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 dynamicfiles, running fixfile with -dfilename and not -f does not delete the readable data fromthe groups you specify when it creates output.) To repair the file, run fixfile with boththe -d and -f options. If you specify the same filename with -d in both the review andrepair steps, UniData will prompt whether or not to clear the damaged groups.


Detection and Repair ExamplesThe following example shows typical output from running verify2 against a

damaged file:

# verify2 TEST.FILEDynamic File Name -------------> TEST.FILEPrimary File Number -----------> 36Overflow File Number ----------> 52Modulo ------------------------> 1088Minimal Modulo ----------------> 17Hash Type ---------------------> 0Block Size --------------------> 20482th key[3249] offset(1327) not right.group 4 errors in header(4096).Number of groups checked: 1088Number of free blocks: 4971 key(s) are damaged.file has something damaged.

The output displays statistics and then reports which groups are damaged.

In this case, group 4 is damaged.

The next example shows the output from dumping the records from the

damaged group with dumpgroup:

# dumpgroup TEST.FILE 4 -dhold_groupThe records can be found under directory /tmp//TEST.FILE_4Check them before fixing the file#

At this point, you can review the directory TEST.FILE_4, located in /tmp,

containing a file for each record that was dumped from group 4. You should

verify that the data in each record is valid. The following example shows the

output from rebuilding the damaged group with fixgroup:

# fixgroup TEST.FILE 4 -ihold_group

4 blocks(including the group header) of group 4 were made empty1 record written to file TEST.FILE.#

Detection and Repair Examples 12-51

The following example shows a file called TEST.FILE being repaired using

guide and fixfile:

# guide TEST.FILE -na -ns# more GUIDE_ERRORS.LISTEST.FILE File Integrity: Group 4, block 5 bytes left 842 is wrong. Group 4, block 5, record number 0 = "10055" record length of 58 is wrong. Group 4, block 5 bytes used 58 and bytes left 842 areinconsistent

Files processed: 1Errors encountered: 3

# more GUIDE_FIXUP.DATTEST.FILE 4## fixfile -dhold -f1:grpno error in U_blkread for file '/users/claireg/TEST.FILE',key '', number=31:U_blkread error in U_catch_tuple for file'/users/claireg/TEST.FILE', key '10055', number=3the 0th record may be damaged,key='10055',length=0.**** Record Key='10055', Record length=11 record dumped for group 4 of /users/claireg/TEST.FILE.1 block (including the group header) in group 4 of /users/claireg/TEST.FILE made empty.1 record written to group 4 of file /users/claireg/TEST.FILE.#


How to Use guideComplete the following steps to effectively using the guide utility

1. Monitor File Integrity with guide

You 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 nonrecoverable static hashed files at any time, and schedule guide to

run on dynamic files and recoverable files at a time when the system is idle

or only lightly loaded.

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 12-53

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 Files

Complete 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—Once you run guide, 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 you not use the -k option with fixfile or withfixgroup. The -k option lets you reload the readable records withoutclearing the group. However, you may encounter additional errors if you donot clear the group. Use fixfile or fixgroup without -k; this procedureautomatically clears the group before reloading the readable records.

Warning: Be sure no users are accessing your files before repairing damagedgroups. The dumpgroup command does not obtain exclusive access, andfixfile/fixgroup only lock the file when the records are being written back toa 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 Files

Back up any files you have just completed repairing.


5. Continue Processing

If you shut UniData down to repair files, start it again before allowing users

to log in.

How to Use guide 12-55

Error MessagesThis section lists error messages you may see, and provides information

about the meaning of them. UniData generates some of the messages from

the guide command, and others from the verify2 command.

File Access Messages

File 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 or verify2 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 Messages

Block 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 otherlinks.

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 or verify2 encounters a

corrupt block, and is therefore unable to check blocks linked through the

corrupted one.


Group Header Messages

Group 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 Messages

Header 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 Messages

There are a number of types of other header messages, as shown in the

following example:

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 12-57

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 dataposition 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 lengthGroup 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 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 areinconsistent

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 Messages

Free block messages are similar to the following example:

Group xx, free block count in group header (y) error, shouldbe 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 long records look 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 and verify2 report messages like the preceding ones.

Error Messages 12-59

Dynamic File Messages

Dynamic file messages look similar to the following example:

Overflow file number too largePrimary file number too large

The 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.


13Chapter

Managing UniData Locks

The Global Lock Manager . . . . . . . . . . . . . . . 13-4

How GLM Works . . . . . . . . . . . . . . . . . 13-4

Locking in UniBasic . . . . . . . . . . . . . . . . . 13-6

How Locks Work . . . . . . . . . . . . . . . . . 13-6

Locking Commands . . . . . . . . . . . . . . . . 13-7

Resource Locks . . . . . . . . . . . . . . . . . . . 13-9

Listing Locks . . . . . . . . . . . . . . . . . . . 13-10

LIST.READU . . . . . . . . . . . . . . . . . . 13-10

Parameters . . . . . . . . . . . . . . . . . . . 13-10

LIST.LOCKS . . . . . . . . . . . . . . . . . . . 13-12

LIST.QUEUE . . . . . . . . . . . . . . . . . . 13-13

LIST.QUEUE Display. . . . . . . . . . . . . . . . 13-14

Commands for Clearing Locks . . . . . . . . . . . . . 13-18

SUPERCLEAR.LOCKS Command . . . . . . . . . . . 13-18

SUPERRELEASE Command . . . . . . . . . . . . . . 13-20

Procedure for Clearing Locks . . . . . . . . . . . . . . 13-21

13 -2 Ad

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.

13-3

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 toUniData

5.1, logical records locks were managed by the lock control process (lcp)

daemon.

How GLM Works

GLM 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, it writes the filename, 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 the local lock table for that

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), you should increase this

setting from the default of 23. The setting should be the closest prime number

to the maximum number of locks per transaction.

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, you should increase this value 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.

The Global Lock Manager 13-5

Locking in UniBasicA series of UniBasic commands allow you to set read-only and exclusive

locks on UniData files and their contents.

How Locks Work

UniBasic locks are advisory rather than physical, so 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 Deleting

WRITE 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, you should precede all

WRITE and DELETE commands by a lock-setting command like READU.


Locking Commands

The following table lists UniBasic commands for setting and releasing locks.

Command Description

FILELOCK Locks the data or dictionary portion of a UniData fileagainst access by commands that check locks.

FILEUNLOCK Unlocks a file previously locked with the FILELOCKcommand.

MATREADL Assigns the values found in successive attributes of arecord to corresponding elements of a matrix, and sets aread-only lock on the record.

MATREADU Assigns the values found in successive attributes of arecord to corresponding elements of a matrix, and sets anexclusive lock on the record.

MATWRITE Writes successive elements of a matrix to thecorresponding attributes of a record and releases lockspreviously set on the record.

MATWRITEU Writes successive elements of a matrix to thecorresponding attributes of a record without releasinglocks previously set on the record.

READBCKL Retrieves one record from a B+ tree based alternate keyindex and places a read-only lock on the record. Eachsubsequent READBCKU retrieves the previous record inthe index.

READBCKU Retrieves one record from a B+ tree based alternate keyindex and places an exclusive lock on the record. Eachsubsequent READBCKU retrieves the previous record inthe index.

READFWDL Retrieves one record from a B+ tree based alternate keyindex and places a read-only lock on the record. Eachsubsequent READBCKU retrieves the next record in theindex.

UniBasic Commands for Locking Files and Records

Locking in UniBasic 13-7

READFWDU Retrieves one record from a B+ tree based alternate keyindex and places an exclusive lock on the record. Eachsubsequent READBCKU retrieves the next record in theindex.

READL Reads a specified record from a file, assigning the recordcontents to a dynamic array and setting a read-only lockon the record.

READU Reads a specified record from a file, assigning the recordcontents to a dynamic array and setting an exclusive lockon the record.

READVL Reads a specified attribute of a specified record, assigningthe attribute value to a variable and setting a read-onlylock on the record.

READVU Reads a specified attribute of a specified record, assigningthe attribute value to a variable and setting an exclusivelock on the record.

RECORDLOCKL Sets a read-only lock on a specified record in a specifiedfile.

RECORDLOCKU Sets a read-only lock on a specified record in a specifiedfile.

RELEASE Releases record locks without updating records.

WRITE Writes an expression to a record, releasing lockspreviously set by READU, READL, READVU, andMATREADU.

WRITEU Writes an expression to a record without releasing anyprevious locks on the record.

WRITEV Writes an expression to an attribute of a record, releasingprevious update locks.

WRITEVU Writes an expression to an attribute of a record withoutreleasing previous locks on the record.

Command Description

UniBasic Commands for Locking Files and Records (continued)


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, andLINE.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 allow you to set and releasesemaphore locks, UniData does not (necessarily) use UNIX system-level semaphoresto control access to system resources. The output from LIST.LOCKS and ipcstat maynot appear to be consistent, but UniData is functioning correctly.

Command Description

UNLOCK Releases system resources reserved by the LOCKcommand. (These resources are not automatically releasedwhen a program terminates.) This command is not neededto release file and record locks.

LOCK

(ECL and UniBasic)

Reserves a system resource for exclusive use.

Locking System Resources

Resource Locks 13-9

Listing LocksUniData offers three commands for listing record and file locks, semaphore

locks on system resources, and processes waiting to get locks.

LIST.READU

The ECL LIST.READU command allows 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 | USER-

NAME user_name] [DETAIL]

Parameters

The following table describes the parameters of the LIST.READU command.


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 filename youspecify. If the filename does not reside in the currentaccount, nothing is displayed.

USERNAMEuser_name

Displays all active locks associated with the user nameyou specify.

DETAIL Displays detailed information.

LIST.READU Parameters


The following example illustrates the output from the LIST.READU

command when you do not specify any options:

: LIST.READUUNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIMEDATE4 6739 0 root ttyp5 INVENTOR 24193 10738 11000 X 16:22:13 Aug 045 6758 1172 clair pts/3 INVENTOR 24193 10738 10060 X 16:21:53 Aug 04:

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 6739UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIMEDATE4 6739 0 root ttyp5 INVENTOR 24193 10738 11000 X 16:25:44 Aug 04:

The next example illustrates output from the LIST.READU command when

you specify a user name:

: LIST.READU USERNAME clairegUNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIMEDATE5 6758 1172 clair pts/3 INVENTOR 24193 10738 11060 X 16:28:14 Aug 04:

The final example illustrates output from the LIST.READU command when

you specify a file name:

: LIST.READU FILENAME INVENTORYUNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIMEDATE4 6739 0 root ttyp5 INVENTOR 24193 10738 11000 X 16:28:24 Aug 045 6758 1172 clair pts/3 INVENTOR 24193 10738 11060 X 16:28:14 Aug 04:

Listing Locks 13-11

LIST.READU Display

The following table describes the output from the LIST.READU command.

LIST.LOCKS

Use 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 screen shows the LIST.LOCKS command and its output:

Column Heading Description

UNO The sequential number UniData assigns to the udt processthat 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.

FILENAME The file name in which the record is locked.

INBR The i-node of the locked file.

DNBR Used in conjunction with INBR to define the file at theoperating system level.

RECORD_ID The record ID of the locked record.

M The type of lock. X indicates an exclusive lock. S indicatesa shared lock.

TIME The time the lock was set.

DATE The date the lock was set.

LIST.READU Display


: LIST.LOCKSUNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME

DATE 1 15290 1172ump01 tyv1 semaphor -1 0 65 X 15:14:01Jun 03:

Note: If you need to clear a semaphore lock that has been left set, you need to note theUNBR and the lock number for the lock. In the example, the lock number is 65 for thelock displayed.

LIST.QUEUE

The 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.

LIST.QUEUE displays the internal table managed by GLM.

Syntax:

LIST.QUEUE [USERNAME user_name | FILENAME filename |

user_number][DETAIL]

Parameters

The following table describes the parameters of the LIST.QUEUE command.

The following example illustrates the output from the LIST.QUEUE

command when you do not specify any parameters.


USERNAMEuser_name

Lists all locks the user is waiting for. user_name is theoperating system login name.

FILENAME filename Lists all users waiting for locks for the filename youspecify.

user_number Lists all locks for which the user_number is waiting. Theuser number can be found in the UNBR column of theLIST.READU and LIST.QUEUE output.

DETAIL Displays a detailed listing.

LIST.QUEUE Parameters

Listing Locks 13-13

: LIST.QUEUEFILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6031 2 pts/2 11:05:44 Aug 04--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6130 4 ttyp1 11:05:54 Aug 04INVENTORY 11060 X clair 6188 1 ttyp3 11:06:04 Aug 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 Aug 04

--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X root 6259 5 ttyp2 11:35:56 Aug 04:

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 Aug 04--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6188 1 ttyp3 11:38:36 Aug 04INVENTORY 11060 X clair 6031 2 pts/2 11:38:46 Aug 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 Aug 04--------------------------------------------------------------------------FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATEINVENTORY 11060 X clair 6763 6 ttyp1 14:16:46 Aug 04:

LIST.QUEUE Display

The LIST.QUEUE display in the previous examples use the default display.

Information 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.

The next table describes the LIST.QUEUE display for the processes waiting

for locks.


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 processfor the owner of the lock.

TTY The terminal device of the user owning the lock.



LIST.QUEUE Owner 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 requested. X is an exclusive lock, S is ashared 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 processwaiting for a lock.

LIST.QUEUE Waiting Display

Listing Locks 13-15

The following example illustrates the LIST.QUEUE display when you specify

the DETAIL option:

: LIST.QUEUE DETAILFILENAME RECORD_ID M INBR DNBR OWNER UNBR UNO TTY TIME DATEINVENTORY 10060 X 241938 1073807361 clair 13798 3 pts/0 14:48:47 Nov 19--------------------------------------------------------------------------FILENAME RECORD_ID M INBR DNBR WAITING UNBR UNO TTY TIME DATEINVENTORY 10060 X 241938 1073807361 root 13763 1 ttyp2 14:48:57 Nov 19

The following table describes the owner information the LIST.QUEUE

command displays when you specify the DETAIL option.

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.


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 sharedlock.

INBR The i-node of the file holding the lock.

DNBR Used in conjunction with the INBR to define the fileholding 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 processholding a lock.

TTY The terminal device of the user holding a lock.



LIST.QUEUE Detail Display


LIST.QUEUE Waiting Display (continued)


The next table describes the output for the LIST.QUEUE command with the

DETAIL option for processes waiting for locks.


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 sharedlock.

INBR The i-node of the file for which a lock is requested.

DNBR Used in conjunction with the INBR to define the file forwhich 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 udtprocess 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

Listing Locks 13-17

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 in. 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 allow an administrator with root

access to release locks held by other users.

SUPERCLEAR.LOCKS Command

SUPERCLEAR.LOCKS enables you to release semaphore locks on system

resources (such as tape drives).

Syntax:

SUPERCLEAR.LOCKS usrnbr [locknum]



The following example shows the effects of SUPERCLEAR.LOCKS:

: LIST.LOCKSUNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME

DATE 1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01Jun 03 3 15692 1172ump01 tyv4 semaphor -1 0 66 X 16:27:01Jun 03:: SUPERCLEAR.LOCKS 15692 -1: LIST.LOCKS

UNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIMEDATE 1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01Jun 03:


usrnbr The UNIX process ID (pid) that holds the lock. Thisnumber is UNBR in the LIST.LOCKS display.

[locknum] The number of the locked system resource. If you do notspecify locknum the command clears all locks set byusrnbr.

SUPERCLEAR.LOCKS Parameters

Commands for Clearing Locks 13-19

SUPERRELEASE CommandThe SUPERRELEASE command enables you to release locks you have set on

records.

Syntax:

SUPERRELEASE usrnbr [inbr devnum] [record.id]

The following table describes each parameter of the syntax:

Note: If you execute SUPERRELEASE and specify only usrnbr, you release allrecord locks held by the process ID corresponding to usrnbr.

The following example shows the effect of SUPERRELEASE:

: LIST.READUUNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIMEDATE1 4178 1172 clair ttyp2 INVENTOR 24193 10738 10060 X 13:28:40 Sep242 4180 1172 clair ttyp1 INVENTOR 24193 10738 10055 X 13:30:20 Sep24: SUPERRELEASE 4180: LIST.READUUNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIMEDATE1 4178 1172 clair ttyp2 INVENTOR 24193 10738 10060 X 13:28:40 Sep24


usrnbr The UNIX process ID (pid) that holds the lock. Thisnumber is UNBR in the LIST.LOCKS display.

[locknum] The number of the locked system resource. If you do notspecify locknum the command clears all locks set by usrnbr.

SUPERRELEASE Parameters


Procedure for Clearing LocksComplete the following steps to identify and clear unneeded locks:

1. Check for Unneeded Locks

Use 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 (shown

by comparing the lists with the UniData LISTUSER command or the

UNIX who or ps commands).

2. Note Information for Clearing

For record locks, note UNBR, 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 Locks

Login as root 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.


Warning: Some situations that retain locks can also cause file corruption (forexample, a udt process is inadvertently killed). Consider checking the file with guideto make certain it has not been corrupted.

Procedure for Clearing Locks 13-21

4. Clear Semaphore Locks

Log in as root and clear semaphore locks with the SUPERCLEAR.LOCKS

command.

5. Check for Message Queue Congestion

Some conditions that cause locks to remain set also cause message queue

congestion when other processes attempt to access the locked item. Refer to

Chapter 18, “Managing ipc Facilities,” for step-by-step instructions for

identifying and clearing congested message queues.


14Chapter

Managing UniData Users

Adding Users . . . . . . . . . . . . . . . . . . . 14-4

Every User Needs a Login . . . . . . . . . . . . . . 14-4

Create Logins at the UNIX Level . . . . . . . . . . . . 14-4

Assign Users to Groups . . . . . . . . . . . . . . . 14-5

Monitoring User Processes . . . . . . . . . . . . . . . 14-6

UniData Commands . . . . . . . . . . . . . . . . 14-6

Removing User Processes . . . . . . . . . . . . . . . 14-8

Using TIMEOUT . . . . . . . . . . . . . . . . . 14-9

14 -2 Ad

This chapter outlines considerations for adding users to your system and

assigning users to groups, and describes how to use UniData and UNIX

commands to view user processes for troubleshooting, and to remove user

processes when needed.

14-3

Adding Users

Every User Needs a Login

To access UniData on your system, you need a valid UNIX account, including

a UNIX login and password. In Pick® systems, where each login account

must be a Pick® account, shared logins and passwords are common. In

contrast, UniData allows multiple relationships between user logins 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

UNIX logins. Therefore, IBM strongly recommends you set up a separate

UNIX account for each user. IBM recommends separate logins for the

following reasons:

■ Since most operating systems impose limits on the number of

processes that can be associated with one user, using separate logins

allows your system to run more processes at one time.

■ It is easier to identify processes and locks belonging to an individual

user, which facilitates troubleshooting.

■ Using separate logins allows you to define your users’

responsibilities for protecting their passwords and your application

data.

Create Logins at the UNIX Level

There are no UniData commands or procedures for setting up UNIX user

accounts. Although the basic process for creating a UNIX account is similar

across UNIX versions, different system configurations may use different

utilities or third-party interfaces for the actual mechanics. Refer to your host

operating system and vendor documentation to determine the correct

procedure at your site.

Consider the following factors when setting up UNIX logins:

■ Each user should have a defined home directory. UNIX home

directories do not need to be unique; many users can share one if this

seems desirable on your system.


■ Home directories do not need to be UniData accounts, although they

may be.

■ Saved ECL command stacks are stored in the user’s home directory.

Note: IBM recommends that if some or all of your users require access to the UNIXshell prompt, or if they will be doing development or maintenance programming,their home directory should not be a UniData account that contains production dataor programs.

Warning: In some configurations, proprietary utilities are in use to automate manyof the steps for adding or deleting a user. Make sure that your utilities are clearlydocumented and understood. If you have a utility that deletes a user’s home directorywhen that user’s account is removed, for example, you could suffer data loss if youuse shared home directories.

Assign Users to Groups

UNIX allows you to define each user as a member of one or more UNIX

system groups. File permissions allow differentiation of access between

members of a group owner and users who are not members of that group.

Refer to Chapter 2, “ UniData and UNIX Security,” and Chapter 11, “

Managing UniData Security,” for more information about groups.

Note: The UNIX commands finger and groups display information about users.Refer to your host operating system documentation for information about thesecommands.

Adding Users 14-5

Monitoring User ProcessesFor troubleshooting purposes, it is often necessary to identify and monitor

processes owned by a particular UniData user.

UniData Commands

UniData includes a group of commands to display a list of current UniData

sessions, to display a list of users currently logged in to the system, and to

display detailed information about process activity for a specific user, or for

all users. The following table summarizes these UniData commands.

Note: You do not need to be logged in as root to execute these commands.

The following screen shows the system response to the WHO, LISTUSER,

and listuser commands.

: WHOclaireg ttyp1 Sep 24 10:04claireg ttyp2 Sep 24 11:55claireg pts/0 Sep 24 14:34

: LISTUSER

Licensed/Effective # of Users Udt Sql Total


WHO ECL command; similar to the UNIX who command;displays a list of users currently logged into 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 UNIX prompt;displays the same information as the ECL LISTUSERcommand.

udstat UniData system-level command; displays detailedactivity statistics about a single UniData process or aboutall UniData processes.

MYSELF ECL command; similar to the UNIX whoami command.

UniData Commands for Monitoring User Processes


32 / 32 2 0 2


1 4192 1172 claireg udt ttyp2 14:34:33 Sep 2419982 4211 1172 claireg udt pts/0 14:35:11 Sep 241998

:% $UDTBIN/listuserLicensed/Effective # of Users Udt Sql Total

32 / 32 2 0 2


1 4192 1172 claireg udt ttyp2 14:34:33 Sep 2419982 4211 1172 claireg udt pts/0 14:35:11 Sep 241998

:

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 identifications: UDTNO (UniData user number), USRNBR (the UNIX pid),

UID (the user’s UNIX uid number), and USRNAME. Displaying further

information about a UniData process typically requires the UNIX pid

(USRNBR).

Monitoring User Processes 14-7

Removing 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

in. The following table summarizes these commands.

The UNIX kill command enables you to stop a process with a variety of

options. Use this command with caution, since it can cause data

inconsistency and file corruption. Refer to your host operating system

documentation for information about the kill command.

You can log yourself out using the stopudt command, but you must be

logged in as root to log out other users using stopudt. You must be logged in

as root to execute deleteuser.

Warning: Both of these commands can disrupt the consistency of your database, anddeleteuser can also corrupt data. These commands should not be used as a substitutefor normal user logout.

Tip: You can use the UniData system-level command udstat to check the activity ofa UniData process. If the process shows activity, stopping or deleting it could damagedata. See the UniData Commands Reference for examples of the udstat command.Communicate directly with the owner, if possible, before stopping a udt process,because even if the process seems to be idle, the terminal may be waiting for input andfiles may be open.


stopudt Logs a user out of UniData; a current write is allowed tocomplete, but subsequent operations for that udt do nottake place. stopudt uses the UNIX kill -15 command.

deleteuser First attempts to execute the UNIX kill -15 command. Ifthe command is not successful in five seconds, force logsa user out of UniData with the UNIX kill -9 command;may interrupt a write in progress, potentially causing filecorruption.

UniData Commands for Removing User Processes


Using TIMEOUT

You 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.

Warning: Be careful with TIMEOUT. Because this command can cause a UniBasicprogram to terminate at an INPUT statement rather than concluding normally,using TIMEOUT can cause inconsistent data in your database.

Removing User Processes 14-9

15Chapter

Managing Printers in UniData

UniData and UNIX Spoolers . . . . . . . . . . . . . . 15-4

Configuring the Spooler . . . . . . . . . . . . . . . 15-4

SETOSPRINTER Command . . . . . . . . . . . . . 15-7

Spooling from UniData . . . . . . . . . . . . . . . 15-8

UniData Printing Commands . . . . . . . . . . . . . . 15-9

Configuring and Troubleshooting a Printer . . . . . . . . . 15-11

Physical Connection . . . . . . . . . . . . . . . . 15-11

Spooler Definition . . . . . . . . . . . . . . . . . 15-11

Definition in UniData . . . . . . . . . . . . . . . 15-12

SETPTR . . . . . . . . . . . . . . . . . . . . . 15-13

Environment Variables . . . . . . . . . . . . . . . . 15-17

Disabling Printer Validation . . . . . . . . . . . . . 15-17

Defining an Alternate Search Path . . . . . . . . . . . 15-17

Examples . . . . . . . . . . . . . . . . . . . . . 15-18

Redefining the Default UniData Print Unit . . . . . . . . 15-18

Submitting Concurrent Print Jobs . . . . . . . . . . . 15-18

Printing to a UNIX Device . . . . . . . . . . . . . . 15-19

Passing Spooler Options to UNIX . . . . . . . . . . . 15-20

Decoding a UniData Print Statement . . . . . . . . . . . 15-21

15 -2 Ad

This chapter explains how UniData interacts with UNIX spooler software

and describes how to configure and access printers from within UniData.

15-3

UniData and UNIX SpoolersAll printing from within UniData is actually performed by your UNIX

system spooler. UniData does not include its own spooler; the UniData

printing commands form an interface to UNIX spooler commands.

Different versions of UNIX include different spooling systems. There are two

major types: the BSD spooling system, which includes the lpd, lpc, and lpr

commands, and the ATT spooling system, which includes the lp command.

The spooling system for any UNIX is likely to be derived from one or the

other of these types, although each UNIX version may include platform-

specific features. Also, some UNIX versions include the user interfaces from

both spooling system types, although underlying processing is accomplished

by one or the other type. Refer to your host operating system documentation

for information about the spooler on your UNIX system.

Users can specify any UNIX spooler command supported on their system by

using the ECL command SETOSPRINTER, and defining the spooler

configuration file.

Configuring the Spooler

UniData includes a spooler configuration file, UDTSPOOL.CONFIG, located

in udthome/sys. This file contains information for the interface between the

UniData SETPTR command and the UNIX-level print commands. The

UDTSPOOL.CONFIG file contains interface information for the lp command

on each system. For some systems, UDTSPOOL.CONFIG also contains

information for the lpr command.


The following example illustrates the UDTSPOOL.CONFIG file:

% pg UDTSPOOL.CONFIG* Default $UDTHOME/sys/UDTSPOOL.CONFIG

* Beginning of the configuration file

* Beginning of entry for lp command.

lp DEFAULT * Default print command BANNER: -t DEST: -d COPIES: -n FORM: -f NHEAD: -o nobanner NOMESSAGE: -s DEFAULT: -c

* End of entry for lp command.

* Beginning of entry for lpr command.

lpr BANNER: -J DEST: -P COPIES: -# FORM: -P NHEAD: -h NOMESSAGE: * not available DEFAULT: * not available

* End of entry for lpr command.

* End of the configuration file(EOF):

Notice the following points about the UDTSPOOL.CONFIG file:

■ The file contains two entries, one for lp and one for lpr. Each entry

lists the spooler command options that correspond to typical

SETPTR options. Within each entry, the “DEFAULT” line indicates

options that the spooler should always include.

■ In the first entry for lp, the lp command is identified as DEFAULT.

This identification directs UniData to use lp as the spooler command

unless you specify another command.

You can modify the UDTSPOOL.CONFIG file using any UNIX text editor.

You can add spooler commands, modify the existing entries, and change the

command identified as the DEFAULT.

UniData and UNIX Spoolers 15-5

If a particular option is not available with your spooler command, and you

do not want UniData to display an error message each time you invoke your

spooler command, you can specify U_IGNORE next to the unsupported

option. In the following example, the NHEAD option in the lp command has

a value of U_IGNORE. Therefore, UniData ignores the NHEAD option, even

if you specify it with the SETPTR or SP.ASSIGN commands:

%pg UDTSPOOL.CONFIG* $UDTHOME/sys/UDTSPOOL.CONFIG for AIX 4.1.1



lp DEFAULT * Default print command BANNER: -t DEST: -d COPIES: -n FORM: -d NHEAD: U_IGNORE NOMESSAGE: * not available DEFAULT: -c


* Beginning of entry for lpr command.

lpr BANNER: -J DEST: -P COPIES: -# FORM: -P NHEAD: -h NOMESSAGE: * not available DEFAULT: * not available

* End of entry for lpr command.

* End of the configuration file


Enabling and Disabling Printers

The PTRENABLE and PTRDISABLE commands issue platform-dependent

UNIX commands to enable and disable a printer, respectively. You may add

the appropriate UNIX commands to the UDTSPOOL.CONFIG file for your

platform, as shown in the following example:

# pg UDTSPOOL.CONFIG* $UDTHOME/sys/UDTSPOOL.CONFIG for HPUX10



lp DEFAULT * Default print command BANNER: -t DEST: -d COPIES: -n FORM: -d NHEAD: -o nb NOMESSAGE: -s DEFAULT: -c PTRENABLE: enable PTRDISABLE: disable -c


* End of the configuration file

If you do not specify the PTRENABLE and PTRDISABLE commands in the

UDTSPOOL.CONFIG file, the defaults of enable and disable are used.

SETOSPRINTER Command

The ECL SETOSPRINTER command enables you to select a UNIX spooler

command.

Syntax:

SETOSPRINTER “spooler_command”

The spooler_command must have an entry in your UDTSPOOL.CONFIG file.

The following example illustrates the SETOSPRINTER command:

: SETOSPRINTER "lp": SETOSPRINTER "lpr"

UniData and UNIX Spoolers 15-7

If you select a printer that does not have any entry in the

UDTSPOOL.CONFIG file, SETOSPRINTER displays an error message

similar to the following example:

: SETOSPRINTER "my_printer"Can't find my_printer in /disk1/ud60/sys/UDTSPOOL.CONFIG.

Spooling from UniData

Print requests from within UniData are generated by UniBasic commands

(PRINT, PRINT ON) 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. This temporary

file is created by default in the /tmp directory. If you define the

UniData configuration parameter TMP, UniData creates the print file

in the location specified by TMP. You can override this setting by

setting the environment variable TMP at the UNIX prompt before

entering UniData.

Note: If you execute SETPTR and set the printer mode to 3 or 6, UniData createsthe print file in the _HOLD_ directory of your current UniData account.

■ UniData uses the name of the temporary file and information from

the printer setup (SETPTR for the logical printer to receive the

output) to create a UNIX spooler command.

■ The UNIX spooler command accepts the temporary file as input.

(Notice that the printed output may not reflect changes made to your

database after the print request was issued.)

■ After the output is printed, UniData deletes the temporary file.


UniData Printing CommandsNote: UniData includes a number of commands that enable you to customize outputfrom UniBasic programs and UniQuery reports. See the UDT.OPTIONSCommands Reference for a complete listing of all available options.

The following table describes ECL commands related to printing.

Command Description

LIMIT Displays the current spooler setting used for printing.

SETOSPRINTER Selects a UNIX spooler command.

SETPTR Defines logical printer units within a UniData session anddisplays the current spooler setting.

SPOOL Prints the contents of a record to the printer.

PTRDISABLE,STOPPTR, orSP.STOPLPTR

Disables a UNIX printer or queue. These commands areequivalent to your spooling system’s disable command.You must supply a printer or queue ID that is defined toyour spooler. Do not supply a UniData logical print unitnumber.

PTRENABLE,STARTPTR, orSP.STARTLPTR

Enables a UNIX printer or queue. The commands areequivalent to your spooling system’s enable command.You must supply a printer or queue ID that is defined toyour spooler. Do not supply a UniData logical print unitnumber.

SP.CLOSE Closes a print file.

SP.ASSIGN Defines logical printer units within a UniData session(Pick® compatible syntax).

SP.EDIT Manipulates print files in the _HOLD_ directory.

SP.KILL Cancels a job. This command is equivalent to UNIX cancelnnn, where nnn is the job number.

SP.OPEN Opens a continuous print job. This command is equivalentto the UniData SETPTR ,,,,,,OPEN command.

UniData Printing Commands

UniData Printing Commands 15-9

Note: See the UniData Commands Reference for the syntax of these ECL commands.

SP.STATUS Provides printer and queue information. This command isequivalent to UNIX lpstat -t.

LISTPTR Prints the names of printers and paths of devicesassociated with them. This command is equivalent toUNIX lpstat -v.

LISTPEQS orSP.LISTQ

Prints the status of the output request. These commandsare equivalent to UNIX lpstat -o.

Command Description

UniData Printing Commands (continued)


Configuring and Troubleshooting a PrinterIn order for any user to print to a printer from UniData, all the following

conditions must be true. Use these conditions as a guideline for setting up a

printer and for troubleshooting printer problems.

Physical Connection

The printer must be physically connected to your computer.

Troubleshooting

■ Check cables and connections.

■ Check power to the printer and check the printer for error

conditions.

■ Use the UNIX cat command to write a text file to the printer in serial

mode; verify that all contents of the file print successfully. For

example, assume you have a file called textfile and a printer attached

to /dev/tty01; enter cat textfile > /dev/tty01 at the UNIX prompt to

test the connection.

Refer to your host operating system documentation and your printer

documentation for information about connecting and troubleshooting a

printer.

Spooler Definition

You must define the printer to your UNIX spooler. Depending on your

spooling system, a printer can be a discrete destination or a member of a

device class.

Troubleshooting

■ Use the UNIX lpstat command to determine if the printer is defined.

Check your documentation to learn which option of lpstat to use.

Configuring and Troubleshooting a Printer 15-11

■ Attempt to spool a text file to the printer using the default print

command (for example, lp -c -dqueuename textfile). Remember that if

you added the printer as a member of a device class, spooling to the

device class sends the job to the first available member of that class,

which may not be the desired printer.

Note: Refer to your host operating system documentation for information about yourspooling system. Because different UNIX versions include different spoolingsystems, procedures for defining a printer to a spooler vary.

Definition in UniData

In order to access a specific printer (or queue) from a UniData session, you

need to link the printer, or queue, to an internal print unit in UniData. Use the

ECL SETPTR command for this. See “SETPTR” in this chapter.

Note: If you do not define a specific printer or queue with SETPTR, UniData directsoutput from UniBasic PRINT statements (following PRINTER ON statements), orfrom UniQuery statements with the LPTR option, to the default printer or queue onyour system.


SETPTRThe SETPTR command enables you to define “logical printer units” within a

UniData session. A logical printer unit is a combination of a printer

destination, a form type, page dimensions, and additional options. By

varying form type and options, you can define more than one logical printer

unit for a single physical printer.

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 you can

define only 31 in a single user session.

Syntax:

SETPTR unit [width,length,topmargin,bottommargin] [mode]

[“spooleroptions”] [options]

The following table lists the parameters of the SETPTR syntax.


unit Logical printer unit number; internal to UniData; you canmap this to a UNIX printer or queue with the DEST andFORM options. Must range from 0 through 254; default is0.

[width] Number of characters per line; must be within the range0-256; default is 132.

[length] Number of lines per page; must be within the range1-32,767 lines; default is 60.

[topmargin] The number of lines to leave blank at the top of each page;must be within the range 0-25; default is 3.

[bottommargin] The number of lines to leave blank at the bottom of eachpage; must be within the range 0-25; default is 3.

SETPTR Parameters

SETPTR 15-13

Note: Users familiar with Pick® conventions should be aware that printer unitnumbers set with SETPTR are not the same as Pick® printer numbers. SETPTRenables you to define logical printer units, which may be linked to specific printers.UniData printer unit numbers are used with the PRINT ON statement in UniBasicto allow multiple concurrent jobs. Pick® printers (forms) are specified with the DESToption of SP.ASSIGN.

The next table describes modes for SETPTR.

[mode] Enables additional flexibility to direct output; default is 1;see separate table.

[“spooleroptions”] Enables you to specify desired spooler options as a quotedstring, which UniData then passes directly to the UNIXspooler.

[options] Enables you to specify printing options that UniData theninterprets and passes to the UNIX spooler. See separatetable.

Mode Description

1 Directs output to a line printer only.

2 Must be used with DEVICE option; directs output to the serial devicespecified by the DEVICE option.

3 Directs output to a _HOLD_ file only.

6 Directs output to both a _HOLD_ file and a line printer.

9 Directs output to a line printer; suppresses display of the _HOLD_ entryname.

SETPTR Modes


SETPTR Parameters (continued)


The next table describes options for the SETPTR command.

Option Description

BANNER [string] Modifies the default banner line (which is the UNIX userID). Depends on MODE setting; also modifies _HOLD_entry name.

BANNER UNIQUE[string]

Modifies the default banner line, and automatically usesattribute 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 uponexecution of SETPTR.

COPIES n Prints n copies of the print job.

DEFER [time] Delays printing until the specified time. Refer to your hostoperating system documentation for the correct syntaxfor specifying time. You need the documentation for theUNIX at command.

DEST unit (or AT unit) Directs output to a specific printer or queue. The unitmust be a valid destination at your site. Refer to yourspooler documentation and use the UNIX lpstatcommand for information about valid destinations.

DEVICE filename Used with mode 2 only. Directs output to the UNIXdevice whose special file is filename.

EJECT Ejects a blank page at the end of each print job.

NOEJECT Suppresses the form feed at the end of each print job.

FORM form Assigns a specified form to each print job. The form mustbe defined to your spooler before you use this option.

LNUM Prints line numbers in the left margin of each print job.

NFMT or NOFMT Suspends all UniData print formatting.

SETPTR Options

SETPTR 15-15

NHEAD or NOHEAD Suppresses the banner for each print job.

NOMESSAGE Suppresses all messages from your UNIX spooler.

OPEN Opens a print file and directs output to this file until thefile is closed by the SP.CLOSE command.

Option Description

SETPTR Options (continued)


Environment VariablesUniData provides two environment variables that affect printing.

Disabling Printer Validation

You can bypass validation of DEST and FORM in SETPTR against the UNIX

spooler’s list of logical printers by setting the NOCHKLPREQ environment

variable. (UniData concatenates DEST and FORM prior to validation, since

many logical printers can access a single physical printer or queue.) On

systems with hundreds of print units defined in the UNIX spooler, the

UniData validation can take so much time that it is a processing bottleneck.

In such cases, setting NOCHKLPREQ removes the bottleneck. Use the

following commands to set NOCHKLPREQ:

Bourne or Korn Shell:

NOCHKLPREQ=1;export NOCHKLPREQ

C shell:

setenv NOCHKLPREQ 1

Consider setting this variable in each user’s .login or .profile.

Warning: If you disable validation, you may encounter unexpected results,including lost print jobs, by specifying invalid DEST/FORM combinations. It issafest to disable checking if you execute your SETPTR commands in a paragraph ora UniBasic program rather than manually, and if you test all options beforeimplementing them in production.

Defining an Alternate Search Path

The LPREQ environment variable enables you to provide an alternate search

path for DEST/FORM validation. UniData automatically searches the

default directory for your UNIX environment (for instance, on an HP-UX

system, the directory /usr/spool/lp/request). If you wish to use a different

directory, use LPREQ.

Environment Variables 15-17

ExamplesThe following section describes a number of ways you can use SETPTR.

Redefining the Default UniData Print Unit

To 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 redefines the default print unit for different reports:

: CT VOC OUTPUTVOC:

OUTPUT:PASETPTR 0,80,60,,,1,BRIEF,DEST laserRUN BP REPORT_PRINTSETPTR 0,80,40,,,1,BRIEF,DEST laser,FORM invoiceRUN BP INVOICE_PRINT:


■ Both “laser” and “laserinvoice” must be valid destinations defined to

your UNIX spooler. If you have defined NOCHKLPREQ, invalid

destinations cause print jobs to fail. If you did not define

NOCHKLPREQ, invalid destinations cause the SETPTR command

in the paragraph to fail.

■ If “laser” is a single printer rather than a queue, the two SETPTR

commands both access a single physical printer. This type of

definition is acceptable.

Submitting Concurrent Print Jobs

With 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).


■ 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.

Printing to a UNIX Device

Use mode 2 of the SETPTR syntax to direct output to a UNIX device. The

following sample command shows the correct syntax for this option:

SETPTR 0,,,,,2,DEVICE /dev/tty9

When you use mode 2, UniData sets the following options by default:

■ NOEJECT

■ NOFMT

■ NOHEAD

■ NOMESSAGE

■ OPEN

When you use mode 2, UniData disables the following options:

■ BANNER

■ BANNER UNIQUE

■ BRIEF

■ COPIES

■ DEFER

■ EJECT

You must use the DEVICE option with mode 2, and you must specify the

output device. The device can be a terminal, a serial printer, a tape drive, or

a disk file. You must specify the device special file if writing to an actual

device. If you want to spool to a disk file, you must specify the full path of the

file.

Examples 15-19

Passing Spooler Options to UNIX

The SETPTR command enables you to use any option accepted by your

default UNIX spooler command, by specifying the options as a quoted string

on the SETPTR command line. The following sample command uses the

spooler options for banner title (-t) and for copies (-c) directly, rather than the

UniData options:

SETPTR 0,,,,,1,"-tACCOUNTS,-c2",DEST laser

Using a quoted string is helpful when you receive unexpected results from

UniData SETPTR options, or if your default spooler supports more options

than UniData accepts.

Tip: Use the ECL LIMIT command or the SETPTR command to display the defaultspooler command in your UniData release, and then refer to your host operatingsystem documentation for supported options for that command.


Decoding a UniData Print StatementTo research printing problems within UniData, it is sometimes helpful to

determine what arguments UniData is passing to your UNIX spooler. If your

system has a C compiler, you can code and compile a C program that

functions as a “dummy” spooler. This program interprets UniData

commands and reports arguments, but does not actually perform any

spooling. By executing the dummy program instead of your default spooler

command, you can test UniBasic PRINT statements or UniQuery reports to

determine how UniData interprets your printing configuration. Complete

the following steps to set up the test:

1. Determine Your Default Spooler Command

Use the ECL LIMIT command or the SETPTR command to determine the

current spooler command, as shown in the following example:

: LIMIT...U_MAXBREAK: Number of BREAK.ON+BREAK.SUP in LIST = 15.U_MAXLIST: Number of attribute names in LIST = 999.U_LINESZ: Page width in printing = 272.U_PARASIZE: Paragraph name and its parameter size = 256.U_LPCMD: System spooler name = lp -c .U_MAXPROMPT: Number of prompts allowed in paragraph = 60....: SETPTRUnit 0Width 132Length 60Top margin 3Bot margin 3Mode 1

Options are:

Spooler & options: lp -c:

In the output for the LIMIT command, look for “U_LPCMD, System spooler

name.” In this example, the current command is lp -c. In the output for the

SETPTR command, “Spooler & options” appears at the bottom of the screen.

Decoding a UniData Print Statement 15-21

2. Create the C Program

The following C program, called prtarg.c, captures the arguments that a

UniData or UniBasic printing command sends to your UNIX spooler. Use vi

or any UNIX text editor to create the program in a work directory of your

choice.

int argc;char *argv[ ];{int i;for (i = 0; i<argc; i++)printf("Argument number %u is ->s\n",i,argv[i]);return(0);}Save the file as prtarg.c.

3. Compile the C Program

When you compile the prtarg.c program, you want to produce an executable

whose name matches your default spooler command. In the previous

example, the spooler command was lp. For some UNIX versions, the

command may be different. Use the cc -o command to compile the program,

as shown in the next example:

# cc -o /usr/ud60/work/lp prtarg.c# cd /usr/ud60/work# ls -l lp-rwxrwxrwx 1 root sys 16384 Jun 4 10:56 lp#

4. Redefine Your Path

To execute the dummy spooler instead of the UNIX spooler, you need to

redefine your execution path so that UNIX locates the dummy version beforethe real version. The work directory where the dummy version resides must

appear at the beginning of your execution path.

The following sample commands show how to redefine the path:

C shell:

set path=(/users/test/work $path)


Bourne or Korn shell:

PATH=/users/test/work:$PATH;export PATH

Once the path is redefined, your dummy spooler executes in place of the

default version.

5. Test UniData Printing

With your execution path redefined, log in to a UniData account and test

printing commands. The following screen shows sample output from the

dummy spooler for a UniQuery report statement that includes the LPTR

keyword, and from a UniBasic PRINT statement:

: SETPTR 0Unit 0Width 80Length 60Top margin 3Bot margin 3Mode 1

Options are:Destination laser

Spooler & options: lp -c -dlaser: LIST VOC WITH F1 = PA LPTRArgument number 0 is ->lpArgument number 1 is ->-cArgument number 2 is ->-dlaserArgument number 3 is ->/tmp/PRT2a18917:: CT BP PRINTONBP:

PRINTONPRINTER ONPRINT “HELLO WORLD”END: RUN BP PRINTONArgument number 0 is ->lpArgument number 1 is ->-cArgument number 2 is ->-dlaserArgument number 3 is ->/tmp/PRT4a18917:

Decoding a UniData Print Statement 15-23

6. Reset Your Execution Path

When you have completed a testing session, make sure you reset your

execution path so that the actual spooler command executes rather than the

dummy spooler program.


16Chapter

Accessing UNIX Devices

UniData Tape Handling Commands . . . . . . . . . . . 16-4

SETTAPE . . . . . . . . . . . . . . . . . . . . . 16-6

Steps for Tape Device Use . . . . . . . . . . . . . . . 16-7

UniData LINE Commands . . . . . . . . . . . . . . . 16-10

Communicating with GET and SEND . . . . . . . . . . . 16-11

Dual-Terminal Debugging in UniBasic . . . . . . . . . . . 16-13

Setting Up Dual-Terminal Debugging . . . . . . . . . . . 16-14

16 -2 Ad

This chapter describes UniData commands for identifying and accessing

UNIX tape devices. This chapter also describes commands for reading and

writing to other UNIX devices, which you can use for transferring data and

also for debugging UniBasic applications.

16-3

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 following table summarizes these

ECL commands.

Note: See the UniData Commands Reference for information about ECL commands.

Command Description

SETTAPE Defines a logical tape unit in UniData; requires rootaccess; must precede all other tape commands.

T.ATT Links a logical tape unit to a UniData process; mustprecede any reads/writes involving the tape.

T.BAK Moves a tape backward a specified number of files.

T.CHK or T.CHECK Reads a tape created by T.DUMP and check for damage.

T.DET Releases a logical tape unit when a UniData process isfinished with it.

T.DUMP Copies the contents of a file or active select list to tape.

T.EOD Moves a tape to end of file.

T.FWD Moves a tape 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 labelon a tape created with T.DUMP.

T.READ Reads and displays the next record from tape.

T.REW Rewinds a tape.

T.SPACE Moves a tape forward a specified number of files.

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 UniBasiccommands.

Command Description

READT Reads the next available record from tape.

RESIZET Changes the block size used by the WRITET statement.

REWIND Rewinds a tape.

WEOF Writes an end-of-file mark to a tape.

WRITET Writes the value of a specified expression as a record on atape.

UniBasic Tape Handling Commands

UniData Tape Handling Commands 16-5

SETTAPEThe ECL SETTAPE command enables you to define logical tape units in your

UniData environment. This command establishes a link between a UniData

internal tape unit number and a UNIX file. You can use SETTAPE to relate

unit numbers to tape devices or UNIX disk files.

Any user can execute SETTAPE unit.no to display the current settings for a

tape unit. However, you must log in as root to define a tape unit or modify

settings.

Once you define a tape unit using SETTAPE, users can access it in any

UniData account on your system. The tape unit definition remains the same

unless it is changed by root.

Syntax:

SETTAPE unit.no [dn.path.nr][dn.path.r][blocksize]

The following table describes the parameters of the SETTAPE syntax.


unit.no Internal UniData tape unit number. Must be within therange 0-9.

[dn.path.nr] Full path for the no rewind device driver for unit.no.

[dn.path.r] Full path for the rewind device driver for unit.no.

[blocksize] Tape block size in bytes; must be a multiple of 512. Thedefault value is 4096.

SETTAPE Parameters


Steps for Tape Device UseFollow these steps to use tape devices from UniData:

1. Define Tape Units

Log in as root and execute the SETTAPE command to define up to 10 tape

units for the UniData environment.

Remember that the tape unit number must be within the range 0-9. These are

logical tape unit numbers within UniData; the SETTAPE command maps

these to UNIX files.

Note: When defining tape units, be sure to define unit 0. Some of the UniData tapehandling 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 ASCII text file udthome/sys/tapeinfo.

2. Attach a Tape Device

You need to 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

example shows some typical output from T.ATT:

: T.ATT 7No information for unit 7 yet, ask your system administrator forhelp.T.ATT failed.: T.ATT 1tape unit 1 blocksize = 4096.: T.ATT 1 BLKSIZE 16384 TAPELEN 2tape unit 1 blocksize = 16384 length = 2MB: T.ATT 1unit 1 is attached by another processIt is lock number 65 in LIST.LOCKS.Try again later, T.ATT failed.

Notice the following points about T.ATT:

■ You cannot attach a tape unit with T.ATT unless the unit was

previously defined with SETTAPE.

Steps for Tape Device Use 16-7

■ You can execute T.ATT repeatedly to change the tape block size and

tape length. If you do not specify BLKSIZE, T.ATT uses the default

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 to find out which ones are attached and which are available.

The following example shows sample output from T.STATUS:

: T.STATUS

UNIT STATUS UDTNO USER CHANNEL ASSIGNED NUMBER NAME NAME BLOCKSIZE

1 ASSIGNED 1 ump01 /dev/rmt/0mn 4096 2 AVAILABLE 3 ASSIGNED 3 ump01 /dev/rmt/0mn 8192 5 AVAILABLE

3. Read From or Write To the Tape Device

When a tape unit is attached, you can access it from ECL or within a UniBasic

program. The following example shows some typical output when a process

with tape unit 4 attached executes the ECL T.DUMP command:

: T.DUMP DICT INVENTORY MU 0416 record(s) dumped to tape: SELECT VOC WITH F1 = PA

9 records selected to list 0.

>T.DUMP VOC9 record(s) dumped to tape: T.DUMP INVENTORY MU 01Unit 1 not attached yet.

: T.DUMP INVENTORY MU 09Unit 9 is not initialized yet.: T.STATUS

UNIT STATUS UDTNO USER CHANNEL ASSIGNED NUMBER NAME NAME BLOCKSIZE

1 AVAILABLE 2 AVAILABLE 3 AVAILABLE 5 AVAILABLE 8 AVAILABLE 4 AVAILABLE 0 AVAILABLE:


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 need to 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.

Note: When you access a tape device, the operation fails if the device is not properlyconnected or if no tape is mounted. The UniData T.ATT and SETTAPE commandsdo not detect device configuration problems, so you may be able to define and attacha device, but be unable to complete your access to it.

Tip: Due to the differences in Pick® operating systems and manufactured tapes, IBMsuggests you use the HDR.SUPP keyword when using the T.DUMP command, andwhen using the Pick® T-LOAD command, to avoid inconsistencies in tape labels.

4. Release the Tape Device

When you no longer need to access a tape device, use the T.DET command to

release it so another process can use it. If you have attached more than one

device, you need to release each one separately. If you have attached only

one, the T.DET command releases it. You can execute T.DET from ECL or

from within a UniBasic program.

Steps for Tape Device Use 16-9

UniData LINE CommandsUniData includes a group of commands that enable you to read from and

write to UNIX tty-type devices. These commands are used to define and

attach line devices for use by the UniBasic GET and SEND commands. GET

and SEND allow UniBasic programs to read data from or write data to serial

devices such as scales or bar code readers.

Note: You can use GET and SEND and the LINE commands to communicate witha printer or terminal.

The following table describes the UniData commands.

Note: See the UniData Commands Reference for detailed information about theUniData LINE commands.

Command Description

SETLINE Defines a UNIX tty device within UniData; requires rootaccess; must precede all other line commands.

LINE.ATT Links a defined device to a UniData process; must precedeall reads/writes involving the line.

PROTOCOL Displays or modifys data line transmission characteristicsof an attached line.

LINE.DET Releases a device.

LINE.STATUS Displays current line device assignments.

UNSETLINE Removes a UNIX device definition set with SETLINE.Requires root access.

UniData LINE Commands


Communicating with GET and SENDYou must follow these steps to use to use the UniBasic GET and SEND

commands:

1. Define a tty Device in UniData.

Use the SETLINE command to create a pointer in UniData to any valid UNIX

tty device. Use LINE.STATUS to verify pointers and determine which lines

may be attached to processes. You must log in as root to create or modify a

pointer. The following example shows an example of SETLINE and

LINE.STATUS:

: SETLINE 4 /dev/pty/ttyv5: LINE.STATUS

LINE# STATUS UDT# USER-NAME DEVICE-NAME

0 Available N/A N/A /dev/pty/ttyv41 Available N/A N/A /dev/pty/ttyv42 Available N/A N/A /dev/pty/ttyv43 Available N/A N/A /dev/pty/ttyv44 Available N/A N/A /dev/pty/ttyv5

Line number(s) are attached by the current udt process:

None

Note: To access a tty device from UniBasic, the device must be assigned a tty number.

When you execute SETLINE to create or modify a pointer, or UNSETLINE to

delete a pointer to a device, you update a file in udthome/sys called lineinfo.

Communicating with GET and SEND 16-11

2. Attach the Line To Your Process

Use the LINE.ATT command, either before executing your UniBasic program

or within your UniBasic program, to reserve a line for your process. Again,

you can use LINE.STATUS to verify the line, as shown below:

: LINE.ATT 3LINE 3 ATTACHED: LINE.STATUS

LINE# STATUS UDT# USER-NAME DEVICE-NAME

0 Available N/A N/A /dev/pty/ttyv41 Available N/A N/A /dev/pty/ttyv42 Available N/A N/A /dev/pty/ttyv43 In-Use 3 root /dev/pty/ttyv44 Available N/A N/A /dev/pty/ttyv5

Line number(s) are attached by the current udt process:

3

Note: Once you attach the line, you can execute the ECL PROTOCOL command todefine its transmission characteristics. When you modify these characteristics, beaware that the values you specify remain in effect until modified again by anotherPROTOCOL command. You may wish to execute PROTOCOL after everyLINE.ATT, to ensure that the transmission characteristics are correct for yourapplication.

3. Access the Line

In your UniBasic application, use the GET command to retrieve data from

your tty device and the SEND command to direct data to the device.

See the UniBasic Commands Reference for detailed information about GET and

SEND.

4. Release the Line

Use the ECL LINE.DET command from the ECL prompt or within your

UniBasic application to release the tty device.


Dual-Terminal Debugging in UniBasicIf you are debugging a UniBasic application that performs terminal I/O, it is

often more efficient to display debugger messages on a separate screen from

the application. The following table summarizes ECL commands for dual-

terminal debugging.

You do not need to log in as root to execute these commands.

Note: Refer the UniData Commands Reference for detailed information about theECL commands for dual-terminal debugging, and see Using the UniBasic Debuggerfor information about the UniBasic debugger.

Command Description

SETDEBUGLINE Sets a pointer to the terminal or window where you wantdebugger messages to display.

DEBUGLINE.ATT Connects to the terminal or window you specify withSETDEBUGLINE.

DEBUGLINE.DET Detaches from the terminal or window to which you areconnected.

UNSETDEBUGLINE Removes the pointer you set with SETDEBUGLINE.

ECL Commands for Dual-Terminal Debugging

Dual-Terminal Debugging in UniBasic 16-13

Setting Up Dual-Terminal DebuggingComplete the following steps to set up a dual-terminal debugging session.

1. Log In to Two Terminals (or Windows)

■ You need to log into two terminals or windows.

■ You do not need to log into UniData on the terminal where you will

display your debugger messages.

■ You need to know the full path of the terminal device special file.

2. Set a Pointer to the Display Terminal

Use the ECL SETDEBUGLINE command to set a pointer from the terminal

where your application is running to the terminal where you want messages

to display. The following screen shows an example:

: SETDEBUGLINE /dev/pty/ttyv4:

Notice that you must specify the full path for the device special file for your

display terminal.

3. Connect to the Display Terminal

Use the DEBUGLINE.ATT command to connect to the terminal you just

defined.

4. Conduct the Debugging Session

The following two screens show dual-terminal debugging. On the first

screen, a UniBasic program is executed with the -D option:

: DEBUGLINE.ATT: RUN BP EXAMPLE -D


On the second screen, the messages from the UniBasic debugger appear:

: MYSELFump01 pty/ttyv0 Jun 4 11:34:***DEBUGGER called at line 1 of program BP/_EXAMPLE!

5. Detach From the Display Terminal

Use the ECL DEBUGLINE.DET command to return debugger messages to

the application terminal. You can reconnect using DEBUGLINE.ATT, as long

as your debug line is still set.

6. Release the Display Terminal

At the end of your debugging session, execute the ECL UNSETDEBUGLINE

command to remove the pointer to the display terminal.

Setting Up Dual-Terminal Debugging 16-15

17Chapter

Managing Memory

UniData Monitoring/Configuring Tools . . . . . . . . . . 17-4

udtconf Main Display . . . . . . . . . . . . . . . 17-4

Calculating udtconfig Parameters . . . . . . . . . . . 17-5

Checking Configuration Parameters . . . . . . . . . . 17-6

Saving Configuration Parameters . . . . . . . . . . . 17-6

Recalculating the Size of the CTL . . . . . . . . . . . 17-7

Viewing Current and Suggested Settings . . . . . . . . . 17-7

Exiting udtconf . . . . . . . . . . . . . . . . . . 17-8

Setting Shared Memory Parameters . . . . . . . . . . . . 17-9

shmconf: Main Display . . . . . . . . . . . . . . . 17-9

shmconf: Viewing Current and Suggested Settings . . . . . 17-10

shmconf: Recalculating the Size of CTL . . . . . . . . . 17-11

shmconf: Recalculating Other Parameters . . . . . . . . 17-11

Shared Memory and the Recoverable File System . . . . . . 17-12

Analyzing UniData Configuration Parameters . . . . . . . 17-12

Checking and Changing UniData Configuration Parameters . . 17-14

Checking Kernel Parameters . . . . . . . . . . . . . 17-16

sms . . . . . . . . . . . . . . . . . . . . . . 17-16

Learning about Global Pages . . . . . . . . . . . . . 17-20

Learning about Local Control Tables . . . . . . . . . . 17-21

UNIX Monitoring Tools . . . . . . . . . . . . . . . . 17-23

UniData Configuration Parameters . . . . . . . . . . . . 17-24

UNIX Kernel Parameters . . . . . . . . . . . . . . 17-24

UniData Error Messages for smm . . . . . . . . . . . . 17-25

17 -2 Ad

This chapter describes UniData commands and utilities for configuring,

monitoring, and troubleshooting shared memory. The chapter also lists

UniData error messages related to shared memory, and presents suggestions

for resolving the errors.

The following commands and utilities enable you to monitor the use of

shared memory on your system and provide suggestions for configuration

and tuning.

17-3

UniData Monitoring/Configuring ToolsThe udtconf utility enables you to automatically set all udtconfig parameters,

including those for shared memory. Although shared memory requirements

are highly application and platform dependent, udtconf can provide

suggestions for udtconfig parameters and provide information about the

actual state of your system.

Syntax:

udtconf

You do not have to log in as root to run udtconf, but the utility reads

information from the udtconfig file, located in /usr/ud60/include, and from

the UNIX kernel. If you do not log in as root, you may not have sufficient

access to the kernel, and the results will be unreliable.

You should run udtconf with UniData users logged off and UniData shut

down. The one exception is to assess the impact of the Recoverable File

System (RFS) system buffer. In this case, run udtconf from a UNIX prompt

while UniData is running.

udtconf Main Display

The following example shows the main screen of the udtconf utility:


To advance to a field displayed on the screen, press TAB. To page down, enter

CTRL-D. To page up, enter CTRL-U.

The udtconf utility displays warning messages if some of the kernel

parameters are not adequate to support the values udtconf calculates. Make

sure that the kernel parameter for semaphore undo structures, usually

semmnu, is adequate to support the number of authorized users prior to

running udtconf.

Settings for the udtconfig parameters NUSERS, SHM_GNTBLS,

N_GLM_GLOBAL_BUCKET, GLM_MEM_SEGSZ, N_TMQ, and N_PGQ are

based on the number of authorized users. Although udtconf displays

warning messages if kernel parameters are not adequate to support these

settings, the udtconfig file is updated with these values. In this case, UniData

may not start.

Calculating udtconfig Parameters

If you change a value in the udtconf screen, udtconf can automatically

calculate values for udtconfig parameters which are dependent upon the

value you change. To calculate parameters, enter CTRL-A.

UniData Monitoring/Configuring Tools 17-5

Checking Configuration Parameters

Press CTRL-K to check the UniData configuration parameters against the

kernel parameters. If a UniData configuration parameter cannot be

supported by a kernel parameter setting, UniData displays a warning

message at the bottom of the screen for each conflicting parameter, as shown

in the following example:

When all configuration parameters have been checked, UniData displays the

message “Shared memory related configuration values are OK!”

Saving Configuration Parameters

Press CTRL-V to save the configuration parameters to the udtconfig file,

located in /usr/ud60/include. If you do not save the parameters, no changes

are made to the udtconfig file.


Recalculating the Size of the CTL

Press CTRL-L from any udtconf screen to recalculate the size of your global

control table, CTL. This table changes size if you change shared memory

parameters such as SHM_GNTBLS, SHM_GNPAGESZ, and so forth. If the

table size is greater than the kernel parameter shmmax (and the udtconfig

parameter SHM_MAX_SIZE), UniData will not start.

Viewing Current and Suggested Settings

To view current and suggested UNIX kernel settings, press CTRL-P. The

following example shows sample output:

udtconf suggests values assuming that UniData is the only software product

on your system. If that is true, as long as the current kernel settings for

semaphore undo structures, shared memory segments, and so forth, are at

least equal to the suggested values, it should not be necessary to rebuild your

kernel. If you have additional applications running, you need to consider the

combined effect of UniData and all other applications when evaluating your

kernel settings.

UniData Monitoring/Configuring Tools 17-7

Exiting udtconf

To exit the udtconf utility, enter CTRL-E. If you have made changes to

configuration parameters, make sure to save the changes by using CTRL-V

before exiting the program.


Setting Shared Memory ParametersThe shmconf utility enables you to set udtconfig parameters for shared

memory automatically. Unlike udtconf, you cannot set udtconfig parameters

that do not apply to shared memory through shmconf. Although its usability

for this purpose is platform-dependent and application-dependent, the

utility provides configuration suggestions and information about the actual

state of your system.

Syntax:

shmconf

You do not need to log in as root to execute shmconf, but the utility reads

information from udtconfig parameters and from the UNIX kernel. If you do

not log in as root, you may not have sufficient access to the kernel, and the

results will be unreliable.

In general, you should run shmconf with UniData users logged off and

UniData shut down. The one exception is to assess the impact of the RFS

system buffer. In this case, run shmconf from the UNIX prompt while

UniData is running.

Note: Only one user at a time may run shmconf.

shmconf: Main Display

The following screen shows a sample of the first output screen from shmconf:

Setting Shared Memory Parameters 17-9

Note: Most of the figures displayed are current values read from UniDataconfiguration parameters. The value of SHMMAX, however, is empiricallydetermined by the shmconf program, which tests to determine the largest sharedmemory segment actually available on the system.

Tip: If the value of SHMMAX on this screen is significantly smaller than your kernelconfiguration (see next example), other applications may be reserving sharedmemory, or you may have insufficient swap space.

shmconf: Viewing Current and Suggested Settings

To view current and suggested UNIX kernel settings, press CTRL-P. The

following screen shows sample output:


Note: shmconf suggests values assuming that UniData is the only software producton your system. If that is true, as long as the current kernel settings for semaphoreundo structures, shared memory segments, and so forth, are at least equal to thesuggested values, it should not be necessary to rebuild your kernel. If you haveadditional applications running, you need to consider the combined effect of UniDataand all other applications when evaluating your kernel settings.

shmconf: Recalculating the Size of CTL

Press CTRL-L from any shmconf screen to recalculate the size of your global

control table, CTL. This table changes size if you change shared memory

parameters such as SHM_GNTBLS, SHM_GPAGESZ, and so on. If the table

size is greater than the kernel parameter shmmax (and the UniData

configuration parameter SHM_MAX_SIZE), UniData will not start.

shmconf: Recalculating Other Parameters

shmconf also enables you to recalculate parameters related to shared

memory. Press CTRL-A from any screen to do so.


Note: shmconf recalculates parameters, but does not update the udtconfig file unlessyou specify CTRL-V (saVe).

Shared Memory and the Recoverable File System

If you are using the Recoverable File System (RFS), UniData reserves the

amount of shared memory required for the system buffer. UniData reserves

this memory during startup, and it is not available to the smm or sbcs

daemons. If your system was running close to its limits in terms of memory

resources without RFS, allocating the system buffer can have a significant

impact. For instance, you may see an increase in error messages indicating

smm could not create or attach a shared memory segment.

Analyzing UniData Configuration Parameters

The system-level systest command checks all parameters in the udtconfig

file, located in /usr/ud60/include.

Syntax:

systest [-mn] [-sn] [-u] [-f filename] [-v] [c {n|r}]

The following table describes each parameter of the syntax:


[-mn] Changes memory map display by about n MB. Highlyplatform dependent. Do not use this unless advised byIBM.

[-sn] Changes memory map display by about n MB. Highlyplatform dependent. Do not use this unless advised byIBM.

[-u] Creates or updates the UniData the configurationparameters NFILES and/or SHM_ATT_ADD. Use withextreme caution.

systest Command Parameters


Note: The -m and -s options of systest function differently on different platforms andalso function differently depending on machine activity. These options help youassess the effects of redefining memory addresses on your system. However, differentUNIX versions handle memory allocation so differently that these options may notproduce meaningful output. Do not use them unless advised by IBM TechnicalSupport.

You must log in as root to execute systest. Users do not need to log out of

UniData.

[-f filename] Creates a file name you specify containing the UniDataconfiguration parameters systest recommends for thenumber of authorized users and platform.

[-v] Displays detailed (verbose) output.

[-c {n|r}] Checks current kernel parameter settings againstUniData recommendations. Specify the -cr option tocompare against recommendations for the RecoverableFile System. Specify the -cn option if you will not be usingrecoverable files.


systest Command Parameters (continued)


The following example shows sample output from the systest command,

with no options:

# systest Memory Address Layout ---------------------

|----------------|----------------|----------------| MALLOC STACK SHMAT ---> ---> --->

IPC Facilities Test Results ----------------------------

Max # of Shmem Segments: 100# of Shmem Seg. Per Process: 36 Max / Min Shmem Seg. Size: 268435456 (256M) / 1 SHMLBA: 4096 (4K)

Max # of Message Queues: 50 Max # of Bytes On Queue: 32768 (32K) Max Message Size: 32768 (32K)

Max # of Semaphores: 36 Max # of Undo Structures: 150

Shmem Attach Address: 0 Usable Shmem Address Range: unknown#

Note: The information displayed in the “IPC Facilities Test Results” section reflectscurrent settings in your UNIX kernel.

Checking and Changing UniData Configuration Parameters

Complete the following steps to update UniData configuration parameters

with new values systest suggests. You want to do this if, for instance, you

have upgraded your license for more users or you have added physical

memory to your system.

1. Use the -f filename option of systest to create an output file in the

format of the UniData configuration file


2. Execute the UNIX diff command using the file created in step 1 and

the udtconfig file to determine the changes suggested by systest.


3. Save a copy of your udtconfig file, then manually update the

production udtconfig file to reflect those changes you want to make.

Check your work carefully.

4. Make sure users are logged out of UniData.

5. Stop UniData with stopud, and start UniData with startud, to make

the changes effective.

The following screen shows typical output from steps 1 and 2:

# systest -f udtconfig.new# diff /usr/ud60/include/udtconfig udtconfig.new13c13< NUSERS=40---> NUSERS=12534c34< SHM_GNTBLS=40---> SHM_GNTBLS=12536c36< SHM_GPAGESZ=1024---> SHM_GPAGESZ=25696c96< SB_FLAG=1---> SB_FLAG=0120,121c120,121< N_PGQ=10< N_TMQ=10---132c132< LOG_OVRFLO=/disk1/ud41/log/log_overflow_dir---> LOG_OVRFLO=

Notice that one of the parameters systest recommends changing is

SHM_GNPAGES. If you want to make this change, make sure your UNIX

kernel is configured appropriately. SHM_GNPAGES * SHM_GPAGESZ * 512

must not exceed the kernel parameter shmmax.

Note: If you run systest -u, the recommended changes in the above example are notmade. systest -u changes only the udtconfig parameters NFILES andSHM_ATT_ADD, if necessary.


Checking Kernel Parameters

The -c argument for systest checks kernel settings against UniData

recommendations. Use the -n option if you are not running RFS. Use the -r

option are running RFS, as shown below:

# systest -cr**** WARNING ***There are 2 kernel parameters that are set lowerthan what Unidata recommends. The kernel parametersare listed in the table below with their recommended values:

Parameter Recommended Value Current Value--------- ----------------- -------------SHMSEG 50 36MSGMNI 100 50

Note: The recommended values returned by systest are generic UNIX suggestionsand may not be appropriate for your operating system. Kernel configuration variesamong UNIX versions. Refer to your host operating system documentation fordetailed information about your UNIX kernel.

sms

The sms command displays information about use of global and local pages

by smm.

Syntax:

sms [-h | -g[n] | -G[n] | -L[n] | -l | -Sn | -d]

You do not need to log in as root to run sms. See the UniData CommandsReference for detailed information about the parameters of the sms command

syntax.


sms -h displays the current settings of shared memory-related configuration

parameters, as shown in the following example:

# sms -hShmid of CTL: 30901-------------------------------- IDs ---------------------------------smm_pid smm_trace PtoM_msgqid MtoP_msgqid ct_semid(values)24075 0 2650 2651 1692(1,1,1)

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

NUSERS = 50 (max 50 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 = 1

SHM_FIL_CNT = 2048JRNL_BUFSZ = 53248


The following example shows a sample output from the sms command with

no options:

# sms-------------------- GCTs (50) ---------------------11502 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1

-------------------- LCTs (50) ---------------------24230 24244 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1

The following table interprets the example.

Field Description

GCTs (50) The number of shared memory segments the system isconfigured to support. Read from the configurationparameter SHM_GNTBLS.

LCTs (50) The combined number of udt processes the system isconfigured to support at one time. Read from theconfiguration parameter NUSERS.

sms Command Output


Tip: Use the sms display along with the output from gstt and lstt to monitor resourceavailability. Consider increasing SHM_GNTBLS or NUSERS and rebuilding thekernel if needed, when these utilities indicate your system is consistently runningnear the limits of resources.

Use the -G option of the sms syntax to display information about the segment

controlled by a particular GCT. This option enables you to determine which

udt process is using each global page in the segment. The following screen

shows an example:

# sms -G 11502GCT-1 is in use----------------------- HEADER -----------------------shmid freed_npages11502 30

-------------------- PAGE MAP (32) -------------------24230 24230 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1 -1 -1 -1-1 -1

11502 The shared memory segment id for a segment that hasbeen created. This number also appears in the ipcstatdisplay. Note: The “GCT number” is read from left toright, top to bottom. In the example, only GCT number 1is in use.

-1 Indicates a resource that is not currently in use.

24230, 24244 UNIX process IDs (pid) for the udt processes currentlyactive.

Field Description

sms Command Output (continued)


The following table interprets the results of the example.

Learning about Global Pages

The gstt command displays information about the use of global pages in

shared memory by the smm daemon.

Syntax:

gstt

Field Description

shmid (11502) The shared memory segment ID.

freed_npages (30) The difference between the number of global pages in thesegment and the number of global pages in use. UniDatareads the number of pages in the segment (32) from theudtconfig parameter SHM_GNPAGES.

24230,24230 The UNIX process ID of the udt process that is using eachglobal page.

-1 Indicates a resource not currently in use.

smsCommand: GCT Output


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 useof shared memory segments. Informix recommends increasing the number of GCTs(SHM_GNTBLS) if the value of GCTs used is consistently higher than 80%.

Learning about Local Control Tables

The lstt command displays information about local control tables in shared

memory. Each local control table tracks resource use for a udt (or sql) process.

Syntax:

lstt [-l n | -L pid]


The following example shows the output from lstt 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 useof local control tables. Informix 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 increasingSHM_GPAGESZ or optimizing your application to minimize use of self-createdsegments.

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.


UNIX Monitoring ToolsThe UNIX sar, vmstat, swap, and swapinfo commands provide useful

information for memory and swap space management. The availability and

syntax of these commands is platform-dependent. Refer to your host

operating system documentation for information about these commands.

UNIX Monitoring Tools 17-23

UniData Configuration ParametersChapter 5, “UniData and Memory,” lists the UniData configuration

parameters that control how smm creates and assigns memory structures.

These parameters are also listed in Appendix A, “UniData Configuration

Parameters.”

When designing your configuration for smm, account for sbcs, the system

buffer (if you are using RFS), and other applications on your system.

UNIX Kernel Parameters

Chapter 5, “UniData and Memory,” describes UNIX kernel parameters that

control creation and allocation of shared memory structures. An exhaustive

list of such parameters is beyond the scope of this manual, since the

parameters, their names, and the processes for adjusting them vary for

different UNIX versions. Refer to your host operating system and vendor

documentation for information specific to your system.

Note: Depending on the UNIX version, some kernel parameters can be defined eitheras fixed values or by internal calculations performed by the system. In some versions,you can tune the kernel while the system is running, while others require you toreboot to make the changes effective. Some UNIX versions (AIX, for example) handlekernel configuration dynamically and do not offer the capability to change theparameters directly.


UniData Error Messages for smmThis section lists error messages that are received when smm is unable to

respond to a request for memory resources. These messages are seen by the

requesting process, so there is no central location for them. They may appear

when you start UniData or at run time.

Consider the following guidelines when troubleshooting error messages:

■ Always note the full text of the error message, any error numbers

associated with the text, and when the error occurred.

■ Check the error logs (smm.errlog and sbcs.errlog) for additional

information.

■ When a message includes an error number (errno), check for the

corresponding UNIX message in /usr/include/sys/errno.h or the

UniData message in your UniData account’s ENGLISH.MSG file.

The message text is often necessary for distinguishing among

possible problems.

■ Consider the context in which the message appears.

■ If you are configuring UniData for the first time, the error

messages provide information you may need to reset

configuration parameters or rebuild the kernel.

■ If you have installed new application software (including C

routines for CALLC or CallBasic), and you begin to see error

messages, review the new additions before reconfiguring

UniData or rebuilding the UNIX kernel. Programming errors or

coding structure errors may masquerade as shared memory

errors; these should be corrected by correcting the software

rather than reconfiguring your system.

■ If your system has been running smoothly with no recent

changes, and you begin to see error messages, identify and

resolve external causes (such as swap space occupied by

temporary files) before reconfiguring UniData or rebuilding the

UNIX kernel.

■ Consider the resource needs of other applications running on your

system. Your system resources must support UniData and all other

applications.

UniData Error Messages for smm 17-25

The following table lists error messages, describes their meaning, and offers

suggestions for resolving them.

Error Message Description

Error on attachingCTL (errno=xxx)

A process cannot attach CTL (Control Table List). This is afatal error. You may need to stop UniData and attempt torestart it. Be sure to save all logs and error logs.

Error on attachingshm (xxx, xxx, xxx),errno=xxx

A process cannot attach a shared memory segment. Theprocess has asked for a segment larger than the systemmaximum or has exceeded the per-process limit for sharedmemory segments. Increase UNIX kernel parameters(shmmax, shmmni, and shmseg) and/or increase theUniData configuration parameter SHM_GNTBLS.

Error on creating CTL(errno=xxx)

UniData cannot create the CTL. This happens when thesize of CTL is larger than the maximum size of a sharedmemory segment. You can increase the maximum size of ashared memory segment (shmmax in the UNIX kernel andthe configuration parameter SHM_MAX_SIZE), ordecrease the size of CTL by decreasing the configurationparameters SHM_GNTBLS and NUSERS.

Error on creating ashared memorysegment (size=xxx),errno=xxx

A shared memory segment of the requested size cannot becreated. Typically the requested size is larger than themaximum size on the system. Adjust the UNIX kernelshmmax and the UniData configuration parameterSHM_MAX_SIZE to increase the maximum size of ashared memory segment.

Error on formingshared memory key(errno=xxx)

Some shared memory segments are created usinginformation in files in the directory /usr/ud60/include.Check to be sure /usr/ud60/include exists; checkpermissions; restore the path from backup if it has beenremoved.

No more GCTs You are out of GCTs (Global Control Tables), which meansyou already have as many segments (self-createdsegments and smm segments) as your system currentlysupports. Consider increasing shmmni in the UNIXkernel, or increasing the UniData configuration parameterSHM_GNTBLS.

Error Messages Associated with smm


No more LCTs You are out of LCTs (Local Control Tables). Considerincreasing the UniData configuration parameter NUSERS.Make sure the kernel parameter semmnu is larger thanNUSERS.

No more core You are out of main memory. Check your swap space;check recent software changes for inappropriate memoryhandling; increase swap space or add more physicalmemory to your system.

No more entries in CItable in LCT-xxx

The CI table in the specified LCT is full. A process has usedits limit of local sections. A local section is a local page orseveral contiguous local pages. Consider increasing theUniData configuration parameter SHM_LCINENTS.

No more entries in MItable in LCT-xxx

The MI table in the specified LCT is full. A process hasused its limit of global pages. Consider increasing the sizeof a global page (SHM_GPAGESZ) or the number ofglobal pages per process (SHM_LMINENTS).

No more entries in PItable in LCT-xxx

The PI table in the specified LCT is full. Your applicationhas too many forked processes. Your application may notbe structured in the correct manner. Consider increasingthe UniData configuration parameter SHM_LPINENTS.

No more sharedmemory ids

You are out of shared memory ids. Adjust the UNIX kernelparameter shmmni to increase the limit.

smm can’t get the firstGSM errno = 22

smm cannot acquire the first shared memory segment tobuild the necessary control tables because shmmax is notlarge enough. Increase the kernel parameter shmmax.

Error on malloc aspace (size=xxx),errno=xxx

Memory allocation error. The requested size is too large.Install more physical memory or increase swap space.

Error Message Description

Error Messages Associated with smm (continued)

UniData Error Messages for smm 17-27

18Chapter

Managing ipc Facilities

Message Queues, Shared Memory, and Semaphores . . . . . . 18-4

UniData Log Files . . . . . . . . . . . . . . . . . 18-7

Removing ipc Structures . . . . . . . . . . . . . . . 18-8

18 -2 Ad

This chapter describes commands and procedures that monitor the use of

message queues and semaphores, and describes how to clear message

queues and remove queues when necessary to correct problems. This chapter

includes some instructions for monitoring shared memory use; however,

shared memory is described more fully in Chapter 17, “Managing Memory.”

18-3

Message Queues, Shared Memory, and SemaphoresThe UniData system-level ipcstat command displays a list of message

queues, shared memory segments, and UNIX system semaphores currently

in use on your system. Output from ipcstat resembles that from the UNIX

ipcs command, but the ipcstat display also identifies the facilities in use by

UniData.

Syntax:

ipcstat [-s | -m | -q]


Entering ipcstat with no options displays information about queues,

semaphores, and shared memory segments.

Note: The output from ipcstat provides queue numbers, semaphore numbers, andsegment numbers. You need these to research ipc problems. For example, you need thequeue numbers to identify and clear congested message queues.

Tip: The ipcstat output is also useful for troubleshooting situations where UniDatahas crashed and restart fails because one or more message queues are left. Use ipcstatto identify these and remove them with the udipcrm command before restartingUniData.

You do not need to log in as root to run ipcstat.


[-q] Displays information about message queues only.

[-m] Displays information about shared memory segmentsonly.

[-s] Displays information about UNIX system semaphoresonly.

ipcstat Parameters


The following example shows sample output from the ipcstat command:

# ipcstatIPC status from /dev/kmem as of Tue Jul 23 16:05:15 2002T ID KEY MODE OWNER GROUPMessage Queues:q 0 0x3c1c0619 -Rrw--w--w- root root -> unknownq 1 0x3e1c0619 --rw-r--r-- root root -> unknownq 2 0xacea0207 -Rrw-rw-rw- root 7721280 -> unknownq 53 0x00000000 -Rrw-rw-rw- root sys -> unknownq 54 0x00000000 --rw-rw-rw- root sys -> unknownq 55 0x00000000 -Rrw-rw-rw- root sys -> unknownq 56 0x00000000 --rw-rw-rw- root sys -> unknownq 57 0x00000000 --rw-rw-rw- root sys -> unknownq 258 0x00000000 -Rrw-rw-rw- root sys -> cm R6.0q 259 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 260 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 261 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 262 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 263 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 264 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 215 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 216 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 217 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 218 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 219 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 220 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 221 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 222 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 223 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 224 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 225 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 226 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 227 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 228 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 229 0x00000000 -Rrw-rw-rw- root sys -> smm R6.0(request)q 230 0x00000000 --rw-rw-rw- root sys -> smm R6.0(reply)q 231 0x00000000 -Rrw-rw-rw- root sys -> sbcs R6.0(tosbcs)q 232 0x00000000 --rw-rw-rw- root sys -> sbcs R6.0(fromsbcs)q 233 0x00000000 --rw-rw-rw- root sys -> sbcs R6.0(newversion)q 484 0x00000000 --rw-rw-rw- root sys -> sm R6.0Shared Memory:m 0 0x2f100002 --rw------- root sys -> unknownm 1 0x411c02e0 --rw-rw-rw- root root -> unknownm 2 0x4e0c0002 --rw-rw-rw- root root -> unknownm 3 0x4120082d --rw-rw-rw- root root -> unknownm 4 0xaceca000 --rw-rw-rw- root root -> unknownm 1205 0x451c415e --rw-rw-rw- root sys -> unknownm 206 0x00000000 --rw-rw-rw- root sys -> unknown

Message Queues, Shared Memory, and Semaphores 18-5

m 207 0x00000000 --rw-rw-rw- root sys -> unknownm 208 0x00000000 --rw-r--r-- root sys -> unknownm 5009 0x451c3e09 --rw-rw-rw- root sys -> smm R5.2(ctl)m 2010 0x00000000 --rw-rw-rw- root sys -> smm R6.0(glm)m 1011 0x00000000 --rw-rw-rw- root sys -> smm R6.0(shmbuf)m 1012 0x00000000 --rw-r--r-- root sys -> sbcs R6.0m 1013 0x651c3e09 --rw-rw-rw- root sys -> sm R5.2(ctl)m 814 0x00000000 --rw-rw-rw- root sys -> sm R6.0(sysbuf)Semaphores:s 0 0x2f100002 --ra-ra-ra- root sys -> unknowns 1 0x411c02e0 --ra-ra-ra- root root -> unknowns 2 0x4e0c0002 --ra-ra-ra- root root -> unknowns 3 0x4120082d --ra-ra-ra- root root -> unknowns 4 0x00446f6e --ra-r--r-- root root -> unknowns 5 0x00446f6d --ra-r--r-- root root -> unknowns 6 0x01090522 --ra-r--r-- root root -> unknowns 71 0x00000000 --ra-ra-ra- root sys -> unknowns 72 0x00000000 --ra-ra-ra- root sys -> unknowns 73 0x00000000 --ra-ra-ra- root sys -> unknowns 74 0x00000000 --ra-ra-ra- root sys -> unknowns 75 0x00000000 --ra-ra-ra- root sys -> unknowns 76 0x00000000 --ra-ra-ra- root sys -> unknowns 77 0x00000000 --ra-ra-ra- root sys -> unknowns 78 0x00000000 --ra-ra-ra- root sys -> unknowns 335 0x00000000 --ra-ra-ra- root sys -> smm R6.0(latch)s 336 0x00000000 --ra-ra-ra- root sys -> smm R6.0(latch)s 337 0x00000000 --ra-ra-ra- root sys -> smm R6.0(latch)s 338 0x00000000 --ra-ra-ra- root sys -> smm R6.0(latch)s 339 0x00000000 --ra-ra-ra- root sys -> smm R6.0(latch)s 340 0x00000000 --ra-ra-ra- root sys -> smm R6.0(ctl)s 341 0x00000000 --ra-ra-ra- root sys -> smm R6.0(journal)s 342 0x00000000 --ra-ra-ra- root sys -> smm R6.0(smm/sm sync)s 279 0x00000000 --ra-ra-ra- root sys -> smm R6.0(super-rls)s 24 0x00000000 --ra-ra-ra- root sys -> unknowns 25 0x00000000 --ra-ra-ra- root sys -> unknown#

Note: Resources identified as “unknown” do not indicate a problem. These resourcesare in use by the operating system or by other applications rather than byUniData daemons.


Notice that, because no options were specified, ipcstat displays information

about queues, semaphores, and memory segments.

UniData Log Files

When you start UniData, the smm and sbcs daemons record in their logs

(smm.log and sbcs.log) information about the ipc facilities they are using. See

Chapter 9, “Starting, Stopping, and Pausing UniData,” for examples of these

log files.

Note: Occasionally, UniData problems result from another process inadvertentlyremoving one of the UniData message queues. You can compare the log files withipcstat output to find out if this is the cause of a hang or crash. If a queue is removed,the initial list from the appropriate log includes the queue, but ipcstat does notinclude the queue.

Message Queues, Shared Memory, and Semaphores 18-7

Removing ipc StructuresCertain types of system failures cause ipc facilities associated with UniData

to be left after UniData has been shut down. This can occur if the system

crashes or if one of the daemons is inadvertently killed. In such cases,

restarting UniData fails because of the remaining ipc structures. You may see

symptoms like the following:

■ The startud command fails.

■ A message displays in the startud window indicating smm is still

running.

■ Executing showud indicates smm is not running.

If you encounter these symptoms, complete the following steps:

1. Check for Remaining Facilities

Enter the UniData ipcstat command at the UNIX prompt. If the output shows

structures associated with UniData processes, execute showud to see if any

UniData daemons are running.

■ If there are daemons running, proceed to step 2.

■ If there are ipc facilities, but no daemons, proceed to step 3.

■ If there are no UniData daemons running and no ipc facilities,

research other causes for the startup failure.

Tip: Occasionally icpstat fails to complete. You can obtain the information you needby executing the UNIX ipcs command and comparing the output with smm.log andsbcs.log to identify UniData structures.

2. Stop UniData

If showud indicates that none of the UniData daemons is running, proceed to

step 3. Otherwise, execute the stopud command. This command stops the

daemons appropriately. Then proceed to step 3.


3. Decide How to Proceed

Use the UniData udipcrm command (step 4) or the UNIX ipcrm command

(step 5).

4. Remove ipc Facilities with udipcrm

Log in as root, and enter the udipcrm command at a UNIX prompt. This

command removes all ipc facilities associated with UniData processes. The

following screen shows the output from udipcrm:

# $UDTBIN/udipcrmipcrm: msqid(1106): not foundipcrm: msqid(1107): not foundipcrm: msqid(1108): not foundipcrm: msqid(1109): not found...ipcrm: shmid(4308): not foundipcrm: shmid(2709): not foundipcrm: shmid(513): not foundipcrm: shmid(414): not foundipcrm: semid(708): not found#

The “not found” messages appear because resources forced out by udipcrm

try to send messages to ones that are already gone.

After successfully completing udipcrm, you should be able to restart

UniData. Proceed to step 6; you do not need to complete step 5.

5. Remove ipc Facilities with UNIX ipcrm

The UNIX ipcrm command removes specific ipc facilities by specifying their

identifiers. For this reason, ipcrm is easy to use if you are removing only a few

facilities.

Refer to your host operating system documentation for detailed information

about the ipcrm command. You must log in as root to execute it. You need the

output from ipcstat to identify the resources to remove. Note the type

(column 1 of ipcstat output; must be m, q, or s) and the ID (column 2 of ipcstat

output).

Removing ipc Structures 18-9

The following screen shows an example of ipcstat - q output:

# $UDTBIN/ipcstat -qIPC status from /dev/kmem as of Wed Jul 24 09:54:34 2002T ID KEY MODE OWNER GROUPMessage Queues:q 0 0x3c1c0619 -Rrw--w--w- root root -> unknownq 1 0x3e1c0619 --rw-r--r-- root root -> unknownq 2 0xacea0207 -Rrw-rw-rw- root 7730112 -> unknownq 53 0x00000000 -Rrw-rw-rw- root sys -> unknownq 54 0x00000000 --rw-rw-rw- root sys -> unknownq 55 0x00000000 -Rrw-rw-rw- root sys -> unknownq 56 0x00000000 --rw-rw-rw- root sys -> unknownq 57 0x00000000 --rw-rw-rw- root sys -> unknownq 258 0x00000000 -Rrw-rw-rw- root sys -> cm R6.0q 259 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 260 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 261 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 262 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 263 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 264 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 215 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 216 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 217 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 218 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 219 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 220 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 221 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 222 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 223 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 224 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 225 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 226 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 227 0x00000000 --rw-rw-rw- root sys -> udt R6.0q 228 0x00000000 --rw-rw-rw- root sys -> tm R6.0q 229 0x00000000 -Rrw-rw-rw- root sys -> smm R6.0 (request)q 230 0x00000000 --rw-rw-rw- root sys -> smm R6.0 (reply)q 231 0x00000000 -Rrw-rw-rw- root sys -> sbcs R6.0 (tosbcs)q 232 0x00000000 --rw-rw-rw- root sys -> sbcs R6.0(fromsbcs)q 233 0x00000000 --rw-rw-rw- root sys -> sbcs R6.0(newversion)q 484 0x00000000 --rw-rw-rw- root sys -> sm R6.0#

Warning: Exercise extreme caution when removing ipc resources. Removing thewrong ones will cause problems elsewhere on the system.

6. Restart UniData

Once you remove the ipc facilities that were left over, you should be able to

restart UniData with the startud command. UniData should restart normally.


Note: If UniData will not start, repeat steps 1 through 6. If UniData still will notstart, the problem is unrelated to ipc facilities. Examine the error logs in udtbin(smm.errlog and sbcs.errlog) and resolve all indicated error conditions.

Removing ipc Structures 18-11

19Chapter

Managing Cataloged Programs

UniBasic Source and Compiled Programs. . . . . . . . . . 19-4

UniBasic Compiled Programs . . . . . . . . . . . . . 19-4

Cataloging UniBasic Programs . . . . . . . . . . . . . 19-5

Direct Cataloging . . . . . . . . . . . . . . . . . 19-5

Local Cataloging . . . . . . . . . . . . . . . . . 19-5

Global Cataloging . . . . . . . . . . . . . . . . . 19-6

Managing Global Catalogs . . . . . . . . . . . . . . . 19-8

Contents of a Global Catalog . . . . . . . . . . . . . 19-8

Verifying a Program Version . . . . . . . . . . . . . 19-10

Listing Programs in Use . . . . . . . . . . . . . . . . 19-16

Creating an Alternate Global Catalog Space . . . . . . . . . 19-17

Files and Directories Created by newhome . . . . . . . . 19-17

Procedure for Creating an Alternate Global Catalog Space . . . 19-17

19 -2 Ad

This chapter describes the behavior of global, direct, and local cataloging for

UniBasic programs. It also describes how to create an alternate global catalog

space using the newhome command.

19-3

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, like BP, each “record” is a UNIX file.

Each UniData account may contain numerous DIR files for UniBasic source.

UniBasic Compiled Programs

When 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.

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.

Tip: Use the ECL RUN command to execute a compiled program. Refer to theUniData Commands Reference and Developing UniBasic Applications forinformation about the RUN command.


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 UniBasicApplications for information about cataloging and the CATALOG command.

Compiled UniBasic programs can be cataloged directly, locally, or globally.

Direct Cataloging

Points 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 a user executes a directly cataloged program, UniData loads a

copy of the program into the address space of the user.

Local Cataloging

Points 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.

Cataloging UniBasic Programs 19-5

■ Developers must recatalog a program after recompiling to place a

new copy of the compiled code into the CTLG.

■ When a user executes a locally cataloged program, UniData loads a

copy of the program into the address space of the user.

Global Cataloging

Points 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. Theenvironment variable UDTHOME determines which global catalog space aparticular UniData session accesses. See “Creating an Alternate Global CatalogSpace” in this chapter for more information about creating multiple global catalogspaces.

■ A systemwide global catalog is a DIR-type file, with 26

subdirectories named a through z. Compiled code is located in the

subdirectory corresponding 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 the compiled code is placed in subdirectories according to name, you may havean unbalanced situation if a large number of your program names begin with thesame 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 the user to execute.

■ The sbcs daemon handles any object file located in the

udthome/sys/CTLG file system, regardless of how the program is

accessed.

■ The sbcs daemon can manage up to 20 shared memory segments for

globally cataloged programs. The size of each segment is determined

by the SBCS_SHM_SIZE parameter in the UniData configuration file

(/usr/ud60/include/udtconfig). The default value for

SBCS_SHM_SIZE is 1,048,576 bytes (1 MB), which is set when you

install UniData. Users encounter run-time 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.

■ For operating systems which impose limits on the number of shared

memory segments (such as AIX, which allows only 10), users should

increase SBCS_SHM_SIZE. Typical values on AIX systems range

from 4 MB to 8 MB.

Tip: Refer to Appendix A, “UniData Configuration Parameters,” for additionalinformation about SBCS_SHM_SIZE and SHM_MAX_SIZE.

Cataloging UniBasic Programs 19-7

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 space

■ Verify consistency between UniBasic source and a globally cataloged

program

■ Activate newly cataloged programs and subroutines

■ Display use of globally cataloged programs

Contents of a Global Catalog

UniData 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 2002 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...


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 16:22:53 Oct 13 1999 1NAME............ TYPE ARG ORIGINATOR.......... WHO.... OBJ... DATE.... LASTREF

508E S 41 @UDTHOME/SYS_BP 508E root 184 10/13/9810/10/98COUNT.MSG S 31 @UDTHOME/DENAT_BP CO root 582 10/13/9810/10/98 UNT.MSGSORT_AE S 11 @UDTHOME/AE_BP SORT_ root 1650 10/13/9810/10/98 AE7201 S 41 @UDTHOME/SYS_BP 7201 root 180 10/13/9810/10/98NFA.EXECSEL.U S 31 @UDTHOME/SYS_BP NFA. root 154 10/13/9810/10/98 EXECSEL.US_VALID_FILE_CHE S 61 @UDTHOME/SYS_BP S_VA root 1712 10/13/9810/10/98CK LID_FILE_CHECKERRMSG.COMMON M 0 @UDTHOME/DENAT_BP ER root 92 10/13/9810/10/98 RMSG.COMMONRPROG_AE S 11 @UDTHOME/AE_BP RPROG root 4710 10/13/9810/10/98 _AE11A2 S 81 @UDTHOME/SYS_BP 11A2 root 850 10/13/9810/10/98SCHEMA_OBJECT_TY S 41 @UDTHOME/SYS_BP SCHE root 1914 10/13/9810/10/98PE MA_OBJECT_TYPES_VALID_NAME_CHE S 31 @UDTHOME/SYS_BP S_VA root 2184 10/13/9810/10/98CK LID_NAME_CHECKSCHEMA_REMOVE_SC S 31 @UDTHOME/SYS_BP SCHE root 1364 10/13/9710/10/98...

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 displayrecords in these files with standard ECL and UniQuery commands to determine ifparticular programs are in the global catalog.

Managing Global Catalogs 19-9

Verifying a Program Version

The 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.

Syntax:

VCATALOG filename catalog.name program.name


Note: If catalog.name and program.name are the same, you need only supply thename once.

The following example shows output from VCATALOG:

: VCATALOG BP TESTProgram 'TEST' does not verify.: CATALOG BP TEST/usr/ud60/sys/CTLG/t/TEST has been cataloged, do you want tooverwrite?(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/usr/ud60/sys/CTLG/t/TEST has been cataloged, do you want tooverwrite?(Y/N) Y: VCATALOG BP TESTProgram 'TEST' verifies.:


filename Name of the file containing the program (BP, forinstance).

catalog.name Name given to the program when you executedCATALOG. For example, the command CATALOG BPTRIAL TEST creates a global catalog entry named TRIALfrom a program called TEST. So catalog.name is TRIAL.

program.name Name of the program source file. In the example in theprevious row of this table, program.name is TEST.

VCATALOG Parameters


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.

Refer to the UniData Commands Reference for additional information about the

VCATALOG command.

Activating Newly Cataloged Programs and Subroutines

This section describes how to activate 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 itcompletes.

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 administrator 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 enables a user

logged in as root 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, then

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 canproduce 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/usr/ud60/sys/CTLG/s/SUBR has been cataloged, do you want tooverwrite?(Y/N) Y:

newversion System-Level Command

The UniData system-level command newversion enables a user logged in as

root 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...



path Absolute path of the cataloged subroutine.

userno... UNIX process ID (pid) for a user who should access thenew subroutine dynamically. You can specify more thanone userno; separate the numbers with spaces.

newversion Parameters


The following screen shows an example of the newversion command:

: LISTUSER

Licensed/Effective # of Users Udt Sql Total~~~~~~~~~~~~~~~~~~~ ~~~ ~~~ ~~~~~ 32 / 32 3 0 3


1 10747 0 root udt pty/ttyv1 11:04:46 Jun 102000

2 10763 1283 user01 udt pty/ttyv0 11:06:16 Jun 102000

3 10846 1172 user02 udt pty/ttyv3 11:16:56 Jun 102000

: CATALOG BP SUBR/usr/ud60/sys/CTLG/s/SUBR has been cataloged, do you want tooverwrite?(Y/N) Y:: !$UDTBIN/newversion /usr/ud60/sys/CTLG/s/SUBR 10846

In the example, the newly cataloged subroutine is dynamically available to

user02, the owner of pid 10846. If user02 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 user02, 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 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 /usr/ud60/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 FIcommand equates to the NEWPCODE command. For example, FIBCFN compiles aprogram and catalogs it (locally) with NEWPCODE. You need to use F (force) inconjunction with the N option. Refer to the online help for the AE editor orDeveloping UniBasic Applications for more information.

Note: The NEWPCODE command is effective only in the udt session where it isexecuted. Although NEWPCODE is an ECL command, a user cannot affect adifferent user or even a different window with NEWPCODE.


Listing Programs in UseThe UniData system-level sbcsprogs command enables any user with access

to a UNIX shell prompt to display a list of globally cataloged programs that

are currently in use, with counters for the number of processes currently

accessing each one. The following screen shows typical output from

sbcsprogs:

# sbcsprogs

Program Name Reference Count

/usr/ud60/sys/CTLG/a/AE 2/usr/ud60/sys/CTLG/a/AE_ICOM1 1/usr/ud60/sys/CTLG/a/AE_AE 2/usr/ud60/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 learnwhich programs are used most heavily. This information is useful if you aretroubleshooting 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 inaccuratelyhigh, causing excess memory to remain held. Stopping and restarting UniData resetsthe 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.

Files and Directories Created by newhome

UniData creates or overlays the directory indicated by path. This directory

contains only the subdirectory sys, which contains the following files and

directories:

# ls@README DENAT_BP D_HELP.FILE MULTIBYTE.CONFIG@README-IMPORTANT DICT.DICT D_JAPANESE.MSG SAVEDLISTS@VERSIONS D_AE_BP D_MSG.DEFAULTS SYS_BPAE_BP D_AE_COMS D_SAVEDLISTS UDTSPOOL.CONFIGAE_COMS D_AE_COMS_DEMO D_SYS_BP VOCAE_COMS_DEMO D_AE_DOC D_UDT_GUIDE X_HELP.FILEAE_DOC D_AE_XCOMS D_VOC _MAP_AE_SECURITY D_BP D__MAP_ _PH_AE_SYSTOOLS D_COLLATIONS D__PH_ coreAE_UPCHARS D_CTLG ENGLISH.MSG install.logAE_XCOMS D_CTLGTB ENGLISH_G2.MSG makefileBP D_DENAT_BP FRENCH.MSG set_sys.shCOLLATIONS D_ENGLISH.MSG HELP.FILE udtpathCTLG D_ENGLISH_G2.MSG JAPANESE.MSG uniapi.msgCTLGTB D_FRENCH.MSG LANGGRP vocupgrade

The following directories make up the program catalog spaces:

■ D_CTLGTB

■ CTLGTB

■ D_CTLG

■ CTLG, 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 Space

Follow the steps below to create an alternate global catalog space:

Creating an Alternate Global Catalog Space 19-17

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 in the following example:

# cd /home/claireg

2. Execute newhome

Execute the newhome command, indicating the path to the new account. In

this example, a new UNIX directory, testenv, will be created under

/home/claireg. (If the udtbin directory is in your path, you do not have to

precede the command with udtbin.)

Notice that the newhome command is executed from the ECL prompt, and

therefore is preceded by the ! ECL command:

: !$UDTBIN/newhome testenv

Creating new udt home /home/claireg/demo/testenv ...

The new UDTHOME is established, now only the sys directoryis there and it contains all the UniData system catalogedprograms, such as AE editor, NFA sever, etc.. To make it beeffective, the environment variable UDTHOME needs to be setto point to the new UDTHOME.

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. Refer to Chapter 3,

“UniData and the UNIX File System,” for information about setting soft

pointers in VOC entries.

: 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 in as root 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

defined during a particular UniData session determines the global catalog

space a user accesses.

Note: Even if the VOC file of an account is set up to point to the alternate globalcatalog (CTLGTB), a user whose UDTHOME is set to the default value accesses thedefault global catalog space.

You can modify the UDTHOME variable in a user’s .login or .profile. Simply

use vi or any UNIX text editor to change the variable setting. The user must

then log out and log back in to make the change effective.

Users with access to a UNIX shell prompt can reset the UDTHOME

environment variable with the setenv command. The value set at the UNIX

prompt overrides the .login or .profile:

% printenv UDTHOME/disk1/ud60% setenv UDTHOME /home/carolw/demo/testenv% udtUniData Release 6.0 Build: (4088)Copyright (C) IBM Corporation 2002All rights reserved.

Current UniData home is /home/carolw/demo/testenv/.Current working directory is /home/carolw/demo.

Creating an Alternate Global Catalog Space 19-19

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, UniData places the recataloged

programs in the new space.

You can also use the following series of UNIX commands to copy all globally

cataloged programs to the new catalog space. Be sure to replace

original_udthome and new_udthome with the paths to your old and new

catalog spaces:

%cd original_udthome /sys/CTLGfind * -type f -print | cpio -pm new_udthome /sys/CTLG

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/home/carolw/demo/testenv/sys/CTLG/a/AE/home/carolw/demo/testenv/sys/CTLG/a/AE_UPS 1/disk1/ud60/sys/CTLG/a/AE 1/disk1/ud60/sys/CTLG/a/AE_ICOM1 1/disk1/ud60/sys/CTLG/a/AE_UPS 1...%

Notice that AE is running twice, but that the two copies are cataloged in

different global catalog spaces.


20Chapter

CallBasic, CALLC, and makeudt

Linking C Routines into UniData . . . . . . . . . . . . 20-4

Overview . . . . . . . . . . . . . . . . . . . . 20-4

Requirements . . . . . . . . . . . . . . . . . . 20-4

Rebuilding for Troubleshooting . . . . . . . . . . . . 20-5

makeudt . . . . . . . . . . . . . . . . . . . . . 20-6

File Examples . . . . . . . . . . . . . . . . . . 20-7

Creating cfuncdef_user . . . . . . . . . . . . . . . 20-10

Steps for Linking in C Functions . . . . . . . . . . . . . 20-11

Steps for Setting Up a Development Environment . . . . . . . 20-15

Accessing UniData from a C Program . . . . . . . . . . . 20-20

Requirements . . . . . . . . . . . . . . . . . . 20-20

How CallBasic Works . . . . . . . . . . . . . . . 20-20

C Program Example . . . . . . . . . . . . . . . . . 20-22

UniBasic Subroutine Example . . . . . . . . . . . . . . 20-25

Steps for CallBasic . . . . . . . . . . . . . . . . . . 20-26

20 -2 Ad

UniData provides the makeudt tool and the UniBasic CALLC command for

linking C routines into UniData, and the CallBasic tool for linking UniData

into C programs. This chapter describes commands and procedures for using

these tools.

Note: See the UniBasic Commands Reference and Developing UniBasicApplications for information about the syntax and use of the CALLC command.

20-3

Linking C Routines into UniData

Overview

Many applications use C functions for purposes like environment definition,

security, or low-level data transfers (similar to the UniBasic GET and SEND

functions). UniData allows you to build a customized version of the UniData

“kernel” (the udt executable, located in udtbin) that includes C functions

developed at your site. Once you build the customized udt, you can access

the C functions from within a UniBasic application using CALLC commands.

You can also create a UniData executable with links to C programs so that

they are accessible through InterCall, UniObjects, or UniObjects for Java.

Note: When you use CALLC, your C functions are executed by a udt process. Theyare not visible to the end user at all.

Requirements

The components required to take advantage of this functionality are:

■ Development environment—Your system should have a full

software development kit. (A base compiler is not sufficient). You

need network libraries if you are using NFA.

■ C functions—You need to code and compile the C functions you are

linking into UniData.

■ Function definitions and make files—When you install UniData,

the files base.mk and cfuncdef are installed into the directory

udthome/work. You create a file called cfuncdef_user that contains

definitions for your site-specific C functions, and you may need to

customize the make file.

■ UniData commands—You use the UniData system-level commands

gencdef, genfunc, genefs, and makeudt, and makeudapi to build

your new UniData executable. If you execute the makeudt or

makeudapi commands, these commands are automatically

executed. If you use the make utility, you need to execute them

manually.


Note: Refer to your host operating system documentation and your hardware vendorif you have questions about your C development environment.

Rebuilding for Troubleshooting

You may consider rebuilding the UniData executable, even if you are not

linking in custom routines, to troubleshoot UniData problems on your

system. The udt executable shipped with your product is “stripped” for

maximum efficiency, which means that symbol tables used by system

debuggers have been removed. You can run makeudt to generate a

nonstripped binary to facilitate debugging.

Tip: Rebuilding udt is often unnecessary for researching problems. Do not undertakethis step unless you are advised to do so by IBM.

Rebuilding for Application Testing

Although the default behavior of makeudt overwrites the production version

of the udt executable, you can configure your system and use the make files

to create executables in a testing area separate from production. In this way,

you can conduct tests without disrupting user activity, and replace the

production udt only when you are satisfied with the functionality.

Linking C Routines into UniData 20-5

makeudtSyntax:

makeudt [-n nfa]

makeudt is a UniData system-level command that builds a new UniData

executable (udt). The command builds the executable using the following:

■ base.mk—This make file is located in udthome/work. This file is a

template that UniData uses to create a second make file called

new.mk. Then UniData uses new.mk to create the new udt

executable.

■ cfuncdef—This function definition file is also located in

udthome/work. It contains definitions for any C functions that

UniData has incorporated into your released udt. Do not modify this

file.

■ cfuncdef_user—This file contains definitions for site-specific C

functions that you want to link into UniData. You need to create this

file.

■ UniData Libraries—When you install UniData, you are prompted

for the path where you want to locate these.

The following table describes the option of the makeudt syntax.

Note: It is best to log in as root to execute makeudt. UniData may be up and running,and users may be logged in. If users are logged in, the makeudt command may or maynot allow you to overwrite the production udt, depending on your UNIX version.Some versions display an error message and exit, while others prompt whether youwish to overwrite the production udt.

Option Description

-n nfa Use this option only if you are not using UniDataOFS/NFA. This option allows makeudt to use “dummy”libraries rather than network libraries NFA requires.Software development environments may or may notinclude the network libraries; if yours does not includethese, and you do not use the -n nfa option, makeudt fails.

makeudt Options


File Examples

The base.mk file and the cfuncdef file are platform-specific.

base.mk Example

Warning: Do not copy the sample makefile onto your system. If you do, makeudt willlikely fail. Always start with the base.mk file released with your UniData release.

makeudt 20-7

The following example shows a base.mk file for UniData on an HP system:

# pg base.mk# pg base.mk## The Porting Date : Jul. 15, 02# The System to Be Ported : HPUX11#

CC = ccCFLAGS = -Ae -q -z +ESsfc -wLDFLAGS =OPTFLAGS = -O +OvolatileDBFLAGS =libpath = -L/liz1/ud60/libaddlib = -lm -lcurses -lsecaddlibpath =odslib = -lodsdummyudlib = -lndbm -lcl -lBSDlicnlib = -llicndclcnlib =nfalib = -lnfaclntdfslib =ODBC_LIBS = -lodbc -lstd -lstream -lCsup -lm -lcl -ldld -Wl,-Bdeferred -Wl,+b /.udlibs

OBJS = funchead.o interfunc.o callcf.o efs_init.o cpprt0_stub.o

cpprt0_stub.o: $(CC) $(CFLAGS) $(OPTFLAGS) $(DBFLAGS) -c cpprt0_stub.s

libs_clt = -lshare -ludsql -ludmach -lbasic -lret1 -lperf -lides -lpipe \ -lfunc -lndx $(dfslib) -lrep -lshm -lmglm -lglm -lulc -lcmn -llicn \ -ludus -lunix -lbci -lunirpc -lssl -lcrypto \ $(ODBC_LIBS) $(nfalib) $(odslib)

libs_svr = -lnfasvr -lshare -ludsql -ludmach -lbasic -lret1 -lperf -lides \ -lpipe -lfunc -lndx $(dfslib) -lrep -lshm -lmglm -lglm -lulc -lcmn \ -llicn -ludus -lunix -lbci -lunirpc -lssl -lcrypto \ $(ODBC_LIBS) $(odslib)

libs_srv = -lushare -lusql -lumach -lbasic -lret1 -lperf -lides -lpipe \ -lushare -lumach -lret1 -lperf -lpipe \ -lfunc -lndx -lrep -lshm -lmglm -lglm -lulc -lcmn -llicn \ -ludus -lunix -lbci -lssl -lcrypto \ $(ODBC_LIBS) -lunirpc $(nfalib) $(odslib)

udt: $(OBJS) $(CC) $(LDFLAGS) $(OBJS) $(NEWOBJS) $(NEWLIBS) \ $(libpath) -lapidummy $(libs_clt) \ $(addlibpath) $(addlib) \ -o $@

udtsvr: $(OBJS) $(CC) $(LDFLAGS) $(OBJS) $(NEWOBJS) $(NEWLIBS) \


$(libpath) -lapidummy $(libs_svr) \ $(addlibpath) $(addlib) \ -o $@

uniapisvr: $(OBJS) $(CC) $(LDFLAGS) $(OBJS) $(NEWOBJS) $(NEWLIBS) \ $(libpath) -lapisvr $(libs_clt) -lmsg \ $(udlib) $(addlibpath) $(addlib) \ -o $@

udapi_slave: $(OBJS) $(CC) $(LDFLAGS) $(OBJS) $(NEWOBJS) $(NEWLIBS) \ $(libpath) -lapidummy -licapi $(libs_clt) -lunirpc \ $(addlibpath) $(addlib) \ -o $@

udsrvd: $(OBJS) $(CC) $(LDFLAGS) $(OBJS) $(NEWOBJS) $(NEWLIBS) \ $(libpath) -lapidummy $(libs_srv) \ $(addlibpath) $(addlib) \ -o $@

.c.o: $(CC) $(CFLAGS) $(IDIR) $(OPTFLAGS) $(DBFLAGS) -c $<

#

cfuncdef Example

Warning: Do not copy the sample cfuncdef file onto your system. If you do, makeudtcan fail. Always start with the cfuncdef file released with your UniData release.

The following sample is a cfuncdef file, also from an HP system. Notice that,

in this instance, there are no C functions specified:

# pg cfuncdef/* this is a test for adding C function to the RUN Machine *//* comment lines come here. *//* C function declaration format:function-name:return-type:number-of-argument:arg1,arg2,...,argn*/$$FUN /* begining of C function */$$OBJ /* *.o come here */$$LIB /* library comes here */

If C functions were specified, there would be entries under $$FUN, and there

might also be entries under $$OBJ and $$LIB.

makeudt 20-9

Cn

Creating cfuncdef_user

Although makeudt recognizes the cfuncdef_user file, UniData does not

include this file at installation. You can create this file from the cfuncdef file

by completing the following steps:

1. Copy the cfuncdef File

In the udthome/work directory, execute the command:

# cp cfuncdef cfuncdef_user

2. Edit cfuncdef_user

Use vi or any UNIX text editor to remove from your new

cfuncdef_user file any lines that appear under the lines beginning

with $$FUN, $$OBJ, and $$LIB. This step gives you a file that has the

format information included for the function definitions, but does

not contain references to any UniData routines.

3. Add Local C Functions to cfuncdef_user

Use vi or any UNIX text editor to add references to site-specific routines you are linking into UniData. Follow the format specified ithe file.


nt

Steps for Linking in C FunctionsComplete the following steps to rebuild your udt executable or to build a

udapi_slave executable.

1. Make Backup Copies of Files

Log in to your system as root; save and verify a copy of your curreudt, your base.mk, and your cfuncdef, as shown below:

# cd $UDTBIN# cp udt udt.save# cmp udt udt.save## cd $UDTHOME/work# cp base.mk base.mk.save# cp cfuncdef cfuncdef.save# diff base.mk base.mk.save# diff cfuncdef cfuncdef.save#

If you are linking in new C functions of your own, make a copy of

your latest version of cfuncdef_user as well.

In the example, the UNIX cmp command verifies the udt executable.

The UNIX diff command verifies the text files base.mk and cfuncdef.

If you are linking in new C functions of your own, proceed to step 2.

If you are simply rebuilding the production udt with no changes,

proceed to step 6.

2. Code and Compile Your C Functions

If you are linking new C functions into the udt or udapi_slave

executables, make sure of the following:

■ The C functions should reside in the work directory, along with

the makefile and the function definition files.

■ The C functions cannot contain the main() function.

■ The C functions must compile cleanly (use cc -c to compile them

producing .o files).

Steps for Linking in C Functions 20-11

3. Edit cfuncdef_user

Add information about your C functions to the cfuncdef_user text

file. Use vi or any other UNIX text editor to add the information.

Make sure the information for the function definitions (lines under

$$FUN) is added using the format described in the text file.

Make sure you define your C functions in cfuncdef_user rather than

cfuncdef.The cfuncdef file contains definitions for only UniData-

developed C functions that may be part of your UniData release.

UniData overwrites the cfuncdef file whenever you install a new

UniData version. If you placed your own function definitions there,

you will lose them with each new install. UniData does not overwrite

the cfuncdef_user file at installation, so your site specific definitions

are preserved.

The naming convention for UniData functions is U_funcname(). To

avoid errors, choose a different naming convention when naming

your C functions.

4. Ask Users to Log Out of UniData

Although you can create a new udt or udapi_slave executable while

users are logged into UniData, the makeudt command may fail

attempting to move this executable from udthome/work into your

udtbin directory. You can move the new udt manually at a later time

if you wish, but if you are ready to update production with makeudt

or makeudapi, users should be logged out of UniData.

If your changes are not fully tested, you may prefer not to overwrite

the production udt. See “Steps for Setting Up a Development Envi-

ronment” in this chapter.


5. Execute makeudt or makeudapi

The following screen shows sample output from the makeudt

command:

# cd $UDTHOME/work# $UDTBIN/makeudtAre you ready to use "cfuncdef" in "/usr/ud60/work"to make a new udt? (y/n) y

Generating new udt. It takes a while.Please wait ...

make -f new.mk udt: cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c funchead.c cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c interfunc.c cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c callcf.c cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c efs_init.c cc -Wl,-a,archive funchead.o interfunc.o callcf.oefs_init.o \ -L${UDTLIB:-/usr/ud60/lib} -lapidummy -lshare -ludsql -ludmach -lbasic -lret1 -lperf -lides -lpipe -lfunc -lndx -lshm-lcmn -llicn -ludus -lnfaclnt -lud \ -lm -Wl,-a,shared -lcurses \ -o udt

The new udt is made successfully.#

The new udt has replaced the previous version in udtbin.

The next screen shows sample output from the makeudapi

command:

# makeudapiAre you ready to use "cfuncdef" in "/disk1/ud60/work"to make a new udapi_slave? (y/n) y

Generating new udapi_slave. It takes a while.Please wait ...

make -f new.mk udapi_slave: cc -q -z +ESsfc -O +Ovolatile -c funchead.c cc -q -z +ESsfc -O +Ovolatile -c interfunc.c cc -q -z +ESsfc -O +Ovolatile -c callcf.c cc -q -z +ESsfc -O +Ovolatile -c efs_init.c cc -Wl,-a,archive funchead.o interfunc.o callcf.oefs_init.o \ -L/disk1/ud60/lib -lapidummy -licapi -lshare -ludsql -ludmach -lbasic -lret1 -lperf -lides -lpipe -lfunc -lndx -lshm -lmglm -lglm -lulc

Steps for Linking in C Functions 20-13

-lcmn -llicn -ludus -lunix -lnfaclnt -lodsdummy -lunirpc\ -lm -Wl,-a,shared -lcurses -lsec \ -o udapi_slave

The new udapi_slave is made successfully.

The new udapi_slave has replaced the previous version in udtbin.

6. Make a Backup Copy of the New udt

If you experience a disk failure between the time you execute

makeudt or makeudapi and your next regularly-scheduled backup,

you need a copy of this new executable to restore your system to its

current state. If you do not make a backup copy, and you restore from

prior backups, you will replace the old version of udt or udapi_slave.

7. Produce a Stripped Executable (Optional)

The makeudt command produces an executable that contains

symbol table information that is helpful if you are using a debugging

tool to research a problem. However, including this information

increases the size of the executable, and may result in noticeably

slowed response for users. Consider using the UNIX strip command

to remove the symbol table information to decrease size and improve

performance. The following screen shows an example:

# ls -l udt-rwxrwxrwx 1 root unisrc 12671908 May 24 18:11 udt# strip udt# ls -l udt-rwxrwxrwx 1 root sys 4415488 Jun 10 15:20 udt

Consult your host operating system documentation for additional

information about stripping executables.

8. Allow Users to Login

All users who log in at this point will access the new version of the

udt or udapi_slave executable.

If you want to execute makeudt or makeudapi and not overwrite the

production udt, modify base.mk, replacing $@ in the very last line

with a new output file name, such as udt.test. Then complete steps 1

through 8. Users can access the new executable by entering that

name (for instance, udt.test) instead of udt.


Steps for Setting Up a Development EnvironmentDuring application development and testing, it may be necessary to rebuild

the UniData kernel numerous times to test changes to C functions. You can

use the make files provided by UniData to build an executable in a working

directory separate from production. Complete the following steps:

1. Establish a New Working Directory

Create a directory called work in a partition where there is space for

development. Then, copy the contents of the default udthome/work

to the new directory. You can use the make files, and so on, as

templates. The following screen shows an example:

# pwd/usr/user01# mkdir work# cd work# cp $UDTHOME/work/* .# lsbase.mk callcf.c efs_init.c funchead.ccallbas.mk cfuncdef efsdef interfunc.c

2. Develop and Compile C Functions

Use the new work directory to develop and compile these functions.

3. Edit the cfuncdef_user File

Edit this file in the new work directory. Do not change the default one

(in udthome/work) until your changes are ready for production.

Steps for Setting Up a Development Environment 20-15

4. Execute gencdef, genfunc, and genefs

If you have made any changes to cfuncdef or to cfuncdef_user, you

need to execute the UniData system-level commands genefs,

gencdef, and genfunc to update working files that the make utility

requires. Use the following steps, but be certain that your current

working directory is the new work space:

# pwd/usr/user01/work# $UDTBIN/genefs# $UDTBIN/gencdef# $UDTBIN/genfunc# ls -tl |pgtotal 26-r--r--r-- 1 root sys 2735 Jun 10 16:08 interfunc.c-r--r--r-- 1 root sys 738 Jun 10 16:08 funchead.c-r--r--r-- 1 root sys 760 Jun 10 16:08 callcf.c-rw-rw-rw- 1 root sys 97 Jun 10 16:08 ndef-rw-rw-rw- 1 root sys 422 Jun 10 16:08 cdef-r--r--r-- 1 root sys 1006 Jun 10 16:08 efs_init.c-r--r--r-- 1 root sys 155 Jun 10 16:04 efsdef-rw-rw-rw- 1 root sys 985 Jun 10 16:04 callbas.mk-r--r--r-- 1 root sys 292 Jun 10 16:04 cfuncdef-rw-rw-rw- 1 root sys 1424 Jun 10 16:04 base.mk

You must log in as root to execute these commands, and you must

execute them in the order shown in the example. If you do not

execute these commands, and you have changed your function

definition files, make can fail.

5. Edit the new.mk File

You can change the name of the output executable to provide clarity.

In the following lines from a sample make file, the executable will be

named new_test:

udt: $(OBJS) $(CC) $(LDFLAGS) $(OBJS) $(NEWOBJS) $(NEWLIBS) \ $(libpath) -lapidummy $(libs_clt) \ $(addlibpath) $(addlib) \ -o new_test


6. Reset UDTHOME or WORKPATH

You need to redefine your environment so that the make utility

creates its output in your new work area. You can set the UDTHOME

or WORKPATH environment variables.

To change UDTHOME, set UDTHOME so that your new work area

is identified as udthome/work. The following example illustrates

this:

# UDTHOME=/usr/user01;export UDTHOME# cd $UDTHOME/work# pwd/usr/user01/work#

If you want to change WORKPATH, set the WORKPATH

environment variable to your new work area, as shown in the

following example:

# WORKPATH=/usr/user01/work;export WORKPATH# cd $WORKPATH# pwd/usr/user01/work#


7. Build the Executable

Use the UNIX make utility rather than makeudt at this point. The

makeudt command overwrites the new.mk file that you updated in

step 5. Also, for development, it is safest not to use makeudt until all

your changes are ready for production. The following screen shows

how to use make:

# make -f new.mk cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c funchead.c cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c interfunc.c cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c callcf.c cc -q -z +ESsfc -DNULL_OK -DSQLTP -DUDTENV -DNEW_INTER -g -c efs_init.c cc -Wl,-a,archive funchead.o interfunc.o callcf.oefs_init.o \ -L${UDTLIB:-/usr/ud60/lib} -lapidummy -lshare -ludsql -ludmach -lbasic -lret1 -lperf -lides -lpipe -lfunc -lndx -lshm-lcmn -llicn -ludus -lnfaclnt -lud \ -lm -Wl,-a,shared -lcurses \ -o new_test # lsbase.mk callcf.o efs_init.c funchead.c interfunc.onew_testcallbas.mk cdef efs_init.o funchead.o ndefcallcf.c cfuncdef efsdef interfunc.c new.mk#

Notice that the executable, named new_test, is created in the

alternate working directory.

Refer to your host operating system documentation for information

about the make utility.


8. Test the Executable

Users can test the executable simply by specifying the full path when

invoking it. The user’s udthome and udtbin should not be changed

from their ordinary settings. The following screen shows an

example:

# cd $UDTHOME/demo# /usr/user01/work/new_testUniData Release 6.0 Build: (4088)Copyright (C) IBM Corporation 2002.All rights reserved.

Current UniData home is /disk1/ud60/.Current working directory is /users/ud_60/demo.:: !ps PID TTY TIME COMMAND 12393 ttyv1 0:00 new_test 10660 ttyv1 0:00 csh 10746 ttyv1 0:00 sh 12398 ttyv1 0:00 sh 12399 ttyv1 0:00 ps 10659 ttyv1 0:03 rlogind

Notice that the UNIX ps command displays the name of the test

executable. You can have several different versions in test at one time

as long as they have different names.


Accessing UniData from a C ProgramThe CallBasic application programming interface (API) allows you to access

a UniData database by calling UniBasic subroutines from a C program. The

CallBasic API is particularly useful for applications 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 C, 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 externalprogram. UniBasic and UniData are invisible to the users of the external program.

Requirements

The components required to use the CallBasic API are:

■ Development environment—Your system should have a full

software development kit. (A base compiler is not sufficient). You

need network libraries if you are using NFA.

Consult your host operating system documentation and your

hardware vendor if you have questions about your C development

environment.

■ C programs—You need to code and compile the C application that

will call UniBasic.

■ Function definitions and make files—When you install UniData,

the file callbas.mk is installed into the directory udthome/work. Use

this makefile as a template to build your application, with UniData

linked into it.

The examples in this section are developed using udthome/work as a

workspace. You can create a separate workspace by creating a new directory

and copying all the files from udthome/work into it. Then complete the steps

in your own workspace.

How CallBasic Works

The CallBasic API includes three functions:


■ udtcallbasic_init( )—This function initializes UniData and

CallBasic. It serves the purpose of opening a “UniData session” for

your C application. Your C program must execute this function once

and only once.

■ U_callbas( )—This function calls a UniBasic subroutine, passing

arguments, and places the results in a pointer to the return value. You

may execute this function numerous times in your C application,

each time 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 C application and UniData. You must execute this function once

in your C application. You must also include this function in any

error exits in your application that may be taken after

udtcallbasic_init().

See Developing UniBasic Applications for a detailed description of the CallBasic

functions and their requirements.

Accessing UniData from a C Program 20-21

C Program ExampleThe following C program, called sample.c, illustrates the components

required for CallBasic:

#include <stdio.h>#include <setjmp.h>#include "/usr/ud60/include/share.h"

main(){ /* Declare variables */ char *rtn; char arg0[BUFSIZ]; char arg1[BUFSIZ]; char *args[2]; int sts;

/* Initialize the UniData environment */

/* Set up an error handler to shut down gracefully */

int jmpret, sat; U_SET_JMP(jmpret, sat); if (!jmpret) { udtcallbasic_done(1); exit(-1); } udtcallbasic_init(0, 0);

/* Assign arguments for the UniBasic routine */ strcopy(arg0, "Plants"); strcopy(arg1, "Animals"); args[0] = arg0; args[1] = arg1;

/* Call the subroutine */ sts = U_callbas(&rtn, "EXAMPLE", 2, args); if (sts == 0){ free(rtn); } printf("status: %d\n", sts); /* Close everything properly */ udtcallbasic_done(sts);}

Notice the following points about sample.c:


Header Files

You must include setjmp.h for the error handler, and you must include the

UniData header file /usr/ud60/include/share.h for linking UniData and your

C program.

Error Handler

Remember that the CallBasic exit routine, udtcallbas_done( ), must be the last

action taken before the C program exits, whether normally or abnormally.

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.

If you initialize CallBasic more than one time, you will encounter errors and

your program may dump core.

Calling a UniBasic Subroutine

In this program, we call the subroutine and assign the return to a variable.

/* Call the subroutine */

sts = U_callbas(&rtn, "EXAMPLE", 2, args);

Remember that 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 Resources

Each U_callbas( ) execution allocates memory; remember to free this after

conclusion of the subroutine:

if (sts == 0){ free(rtn);

C Program Example 20-23

Notice that we free the memory if the function completes successfully;

UniData frees the memory if the function fails.

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.

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 call to the subroutine:

sts = U_callbas(&rtn, "EXAMPLE", 2, args);

And here is the first line of the subroutine:

SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)

Additional Information

You must create, compile, and catalog the UniBasic subroutine 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.

UniBasic Subroutine Example 20-25

Steps for CallBasicComplete the following steps to access UniData from a C program with

CallBasic:

1. Code and Compile the C Program

C compilers differ between UNIX versions. For instance, some C

compilers require ANSI-compliant syntax, and others do not.

Consult the documentation supplied with your C compiler for

specific coding requirements for your system.

The C program should be located in the same directory as the

makefile. By default, this is udthome/work. Use the cc -c command to

compile the C program in your workspace. cc -c produces a .o file in

the same directory. The following example shows how to compile the

sample program sample.c.# ls -l sample*-rw-rw-rw- 1 root sys 745 Jun 11 11:43 sample.c# cc -c sample.c# ls -l sample*-rw-rw-rw- 1 root sys 745 Jun 11 11:43 sample.c-rw-rw-rw- 1 root sys 1624 Jun 11 11:45 sample.o#

See “C Program Example” in this chapter for a listing of sample.c.


2. Code, Compile, and Catalog the UniBasic Subroutine

Remember 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", 6 lines, 128 characters.*--: P001: SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)002: PRINT "THE FIRST ARG IS ":ARG1003: PRINT "THE SECOND ARG IS ":ARG2004: RETNVAL="RETURN"005: RETURN006: ENDBottom.*--: FIBCFiled "EXAMPLE" in file "BP" unchanged.

Compiling Unibasic: BP/EXAMPLE in mode 'u'.compilation finished:

Before proceeding further, be sure that both your C program and

your UniBasic subroutine are thoroughly tested.

3. Make a Copy of the Makefile Template

The template, released by default into udthome/work, is called

callbas.mk. When you copy it, name the copy in a way that relates it

to your C program, as shown below:

# ls callbas*callbas.mk# cp callbas.mk sample.mk#

The template for your makefile is platform and release dependent.

Always use callbas.mk on your system as a starting point; do not

attempt to use the examples in this document.

Steps for CallBasic 20-27

4. Edit Your Makefile

Use vi or any UNIX text editor to edit the copy you created in Step 3.

The purpose is to produce a makefile that will build your C program,

with udt linked into it, forming an executable whose name you

choose. There are additional steps required so that the make is

successful. Follow the sequence below:

a. Correct References for UniData Libraries

Locate a line in your make file that looks like this:

libpath = -L/disk3/srcman/alpha/ud_60_020715_4088/bin/lib

Notice that the path does nt match your production system. It con-

tains a UniData internal naming convention. You need to change this

to reflect the actual location of your UniData libraries. The following

example uses the default location:

libpath = -L/usr/ud60/lib

You also need to remove a redundant line. Look for a line that

resembles:

libpath = -L$$UDTLIB

Delete this line from your make file.

b. Enter the Name of Your Compiled C Routine

Look for a line that resembles:

NEWOBJS = callbas.o

callbas.o is a default object name released with the template. Change

this to match your C routine, as shown below for the sample

program:

NEWOBJS = sample.o

This change allows your C routine to be included in the make.

c. Enter the Name for Your New Executable

The UNIX make utility will build a new executable linking the

UniData kernel (udt) with your compiled C routine. You need to

modify the makefile to name the resulting executable. Look for a line

that resembles:

callbas: $(NEWOBJS) $(OBJS)

callbas is a default name released with the makefile. Substitute the

name you want as shown below:


sample: $(NEWOBJS) $(OBJS)

Note: As shown in the examples, it is simplest to maintain naming consis-tency between your C program, its .o file, and your new executable.

d. Check Your Work

Make certain that you have replaced all occurrences of callbas with

the name of your program.

5. Build Your New Executable

The executable resulting from this step will be significantly larger

than your compiled C program, because this step links in the

UniData kernel. You can estimate the total size by recording the size,

in bytes, of udtbin/udt. Add the size in bytes of your compiled C

program (sample.o in the examples) and then add about 20%

overhead, since the executable will not be stripped. Make sure you

have enough space available in your work area.

Use the UNIX make utility, as shown in the following screen:

# make -f sample.mk

cc -Wl,-a,archive sample.o funchead.o interfunc.o callcf.o

efs_init.o \

-L/usr/ud60/bin/lib -lapidummy -lshare -ludsql -lud-

mach -lbasic -lperf -lret1 -lides -lpipe -lfunc -lndx -lshm -lcmn -

llicn -ludus -lnfaclnt -lud -lndbm -lcl -lBSD \

-lm -Wl,-a,shared -lcurses -o sample

# ls sample*

sample sample.c sample.mk sample.o

#

Notice that UniData creates the executable sample in your working

directory.

Note: You do not need to log in as root to execute the make utility. You doneed to have write permissions at the directory level in your work area. Referto your host operating system documentation for information about themake utility.


6. Produce a Stripped Executable (Optional)

The make utility produces an executable that contains symbol table

information that is helpful if you are using a debugging tool to

research a problem. However, including this information increases

the size of the executable, and may result in a noticeably slower

response for users. Consider using the UNIX strip command to

remove the symbol table information to decrease size and improve

performance. The following screen shows the results of stripping the

sample executable:

# ls -l sample

-rwxrwxrwx 1 root sys 12657828 Jun 12 12:18 sample

# strip sample

# ls -l sample

-rwxrwxrwx 1 root sys 4423680 Jun 12 12:57 sample

#

To save time, do not strip your executable until you finish testing and

debugging it. Consult your host operating system documentation for

information about debugging and symbol tables.


7. Use the New Executable

To 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 UNIX prompt,

and you need to be sure to specify the full path of the executable, or

include its location in your PATH. The following example shows the

results of executing the sample executable from the demo directory

(successful), and from a different UniData account (unsuccessful):

# cd $UDTHOME/demo

# /usr/ud60/work/sample

THE FIRST ARG IS Plants

THE SECOND ARG IS Animals

status: 0

# cd /users/test/TESTACCT

# /usr/ud60/work/sample

'EXAMPLE' is not cataloged.

status: -1

#

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.


21Chapter

General Troubleshooting

Crashes and Restart Problems. . . . . . . . . . . . . . 21-4

UniData Crashes . . . . . . . . . . . . . . . . . 21-4

UniData Cannot Start. . . . . . . . . . . . . . . . 21-5

Response Problems in UniData . . . . . . . . . . . . . 21-6

UniData Consistently Slow. . . . . . . . . . . . . . 21-6

UniData is Hung . . . . . . . . . . . . . . . . . 21-6

Error Messages . . . . . . . . . . . . . . . . . . . 21-7

Common Error Messages . . . . . . . . . . . . . . 21-7

21 -2 Ad

This chapter outlines several problems you may encounter running UniData,

and offers suggestions to research and resolve them. The chapter also

describes a number of UniData system messages, along with explanations of

their causes.

21-3

le

Crashes and Restart ProblemsThis section presents suggestions for handling situations where UniData

stops running entirely, or where you cannot start UniData.

UniData Crashes

Symptoms: System appears to be “hung”; one or more terminals may display

the message Killed or udt dead.

Suggestions:

1. Check to make sure your hardware and operating system is running.

Hardware or power problems may cause UniData to crash. If your

system is up and running, proceed to step 2. Otherwise, identify and

resolve system problems.

2. If you are running UniData on AIX, check swap space. The AIX

operating system kills processes when it runs out of swap space.

3. Check to see if UniData is still running. Execute the showud

command to check the status of the UniData daemons. If the UniData

daemons are still running, proceed to “UniData is Hung.”


4. Check the UniData logs and error logs. These are located in udtbin.Consider printing them in case they are needed to research a crash.

5. Identify and resolve problems revealed in the logs. Chapter 12,

“Managing UniData Files,” Chapter 17, “Managing Memory,” and

Chapter 18, “Managing ipc Facilities” may be useful.

6. When all identified problems have been resolved, log in as root and

execute startud. If UniData does not start, proceed to “UniData

Cannot Start”. Otherwise, resume normal operations.

Note: UNIX system crashes may result in data inconsistencies or ficorruption, depending on the activity at the time of the crash.Examine your data files with verify2 before starting UniData, orwith guide after starting UniData.


er-Sys-

Additional factors must be considered if you are using the Recovable File System (RFS). See Administering the Recoverable Filetem for further information.

UniData Cannot Start

Symptoms: startud does not complete normally. Error messages may or may

not appear in the window where you run startud.

Suggestions:

1. Make sure your UNIX environment is running correctly. Check

UNIX system logs for error and warning conditions. Identify and

resolve external problems.

2. Check the UniData log files in udtbin. Consider printing them in case

they are needed to solve a problem.

3. Check for indications of shared memory problems. (For example, if

smm is unable to create the CTL segment, UniData will not start). If

there are messages in smm.errlog, review Chapter 17, “Managing

Memory,” for suggestions to solve the problem.

4. Check the status of UniData ipc facilities by logging in as root and

running ipcstat. If ipc structures were not properly cleaned up after

a crash, follow the procedures described in Chap[ter 18, “Managing

ipc Facilities,” to clear the structures.

If ipcstat hangs, use the UNIX ipcs command.

5. Log in as root and execute startud to restart UniData.

Additional factors must be considered if you are using RFS. SeeAdministering the Recoverable File Systemfor further information.

Crashes and Restart Problems 21-5

Response Problems in UniData

UniData Consistently Slow

Symptoms: The system is consistently sluggish whenever UniData is

running and users are logged in.

Suggestions: Refer to Chapter 22, “Performance Monitoring and Tuning.”

UniData is Hung

Symptoms: The system has been performing acceptably, but the response

slows. One to all terminals may appear hung.

Suggestions:

1. Execute the UNIX ps command. Look for processes with large and

rapidly growing cpu time. Explore these processes; kill them if

appropriate.

2. Execute showud at a UNIX prompt to make certain all UniData

daemons are running.

3. Check the UniData logs in udtbin for clues about the problem.

4. Check for file or semaphore lock problems with the ECL

LIST.LOCKS, LIST.QUEUE, and LIST.READU commands. See

Chapter 13, “Managing UniData Locks,” for procedures to identify

and clear unneeded locks.

5. Identify and resolve message queue problems using the procedures

described in Chapter 18, “Managing ipc Facilities.”

6. If the response is still slow, or if steps 1 through 3 did not reveal the

problem, check your system to identify and resolve unusual load

conditions. The UniData listuser, sbcsprogs, and udtmon programs,

and the UNIX uptime, vmstat, and ps commands may provide

helpful information.


Error MessagesError messages seen in UniData applications may originate from the

following:

■ the application

■ UniData

■ UniBasic

■ one of the layered products

■ the operating system

■ combined sources

The following table shows some typical formats for error messages.

Common Error Messages

This section describes some common UniData error messages.

Format Source

In/usr/ud60/sys/CTLG/t/TEST at line 20...

UniBasic runtime error. The error identifies the program(TEST) and the line where the error occurred.

...errno=36 UNIX operating system message. Refer to the file/usr/include/sys/errno.h to translate the error number.

Not enough diskspace, resize failed.

UniData error message. Many error messages in UniDatacan be found in the file identified by the VOC pointerENGLISH.MSG, which is a UniData hashed file. Use ECLESEARCH or UniQuery to search for messages in this file.See UniData International for the name of your message fileif you have localized UniData to run in your locallanguage.

msgrcv failed.errno=36

UniData error message that includes the UNIX errornumber. Translate the error number for helpfultroubleshooting information.

Error Messages and Sources

Error Messages 21-7

Syntax error

■ Occurrence—This error appears when a user is attempting to run an

ECL command.

■ Causes—This error may result from the following:

■ Wrong syntax; refer to online help or to the UniData CommandsReference for the correct command syntax.

■ You entered a backspace or other control character; reenter the

command.

■ ECLTYPE is set to P when it should be U or vice versa; try

changing ECLTYPE and reenter the command.

■ BASICTYPE is set to P when it should be U or vice versa; try

changing BASICTYPE and reenter the command.

Not a verb command

■ Occurrence—This error appears when you are attempting to run an

ECL command.

■ Cause—command must be either a VOC entry or a globally cataloged

program.

■ You spelled the command incorrectly; try again.

■ You are in the wrong UniData account; command is not an entry

in the local VOC file; check the VOC file.

■ command is a UniBasic program that is not globally cataloged;

determine how it should be cataloged; make necessary

corrections; instruct users appropriately. See Chapter 19,

“Managing Cataloged Programs,” for further information.

cannot open abcdef

■ Occurrence—This is a UNIX-level error which occurs when a

process is attempting to open a file called abcdef.

■ Causes—This error can be caused by either of the following:

■ The file abcdef does not exist; check the filename and path and

try again.


Note: Some UNIX commands return the message “no such file or directory” for afile that does not exist, while others return “cannot open.”

■ The user receiving the error does not have sufficient permissions

to execute the file. See Chapter 2, “UniData and UNIX Security,”

and Chapter 11, “Managing UniData Security,” for additional

information.

Note: Some UNIX commands return the message cannot open filename:Permission denied and others simply return Permission denied.

[100004]

■ Occurrence—A number of users are logged into UniData. When an

additional user tries logging in, [100004] displays on the terminal.

■ Cause—You are out of semaphore undo structures in the UNIX

kernel. Use the UniData kp command to display kernel settings; the

parameter semmnu should be set to three times the number of users

licensed on your system. You need to rebuild your UNIX kernel.

[100000]

■ Occurrence—A number of users are logged into UniData. When an

additional user tries to log in, [100000] displays on their terminal.

■ Cause—The UniData configuration parameter NUSERS is too small.

This parameter, located in /usr/ud60/include/udtconfig,

determines the number of local control tables UniData uses. Each

local control table tracks information for a single UniData user

process. This parameter cannot exceed the kernel parameter

semmnu. Set NUSERS to the number of authorized UniData users +

number of authorized UniData users / 4.

Virtual field too big

■ Occurrence—This message displays after you execute a UniQuery

statement.

Error Messages 21-9

■ Cause—You have created a formula in a virtual attribute that, when

evaluated by UniQuery, creates a stack of C routines that is bigger

than the default. The limit that is exceeded is not the number of

characters in the formula itself, but an internal limit. Set the

environment variable VFIELDSIZE to a number greater than 300 (the

default) to resolve this problem. Try setting VFIELDSIZE to 400. The

larger VFIELDSIZE is, the more memory your process requires.

Record is too long. Please ask Unidata to extend the U_MAXEXTRA.

■ Occurrence—This message occurs while you are loading records

from tape into a UniData hashed file with T.LOAD. When the

message occurs, T.LOAD quits, leaving a partial restore.

■ Cause—T.LOAD has encountered a record that is too large to

process. You can remake the T.DUMP tape with a larger block size,

or you can load the tape into a DIR-type file rather than a UniData

hashed file. Once you have loaded it into the DIR file, you can use the

ECL COPY command to copy the records into a hashed file. If you

execute T.LOAD to load a file into a directory, make sure your UNIX

file system has enough inodes; you need one inode for every record

in the file you are loading.

Numra is maxed out in installshmid

■ Occurrence—This message displays while someone is trying to run

a globally cataloged UniBasic program.

■ Cause—The sbcs daemon is out of memory to store globally

cataloged programs. sbcs can manage up to 20 shared memory

segments, and the size of each is determined by the UniData

configuration parameter SBCS_SHM_SIZE (1 MB by default).

However, some UNIX versions (AIX, for example) limit the number

of shared memory segments to 10, thereby limiting the memory

available for sbcs. You can resolve this situation by resetting

SBCS_SHM_SIZE. Values from 4 MB to 8 MB are appropriate for AIX

systems.


22Chapter

Performance Monitoring andTuning

UNIX Performance Considerations . . . . . . . . . . . . 22-4

UNIX Performance Monitoring . . . . . . . . . . . . . 22-5

Tools . . . . . . . . . . . . . . . . . . . . . 22-5

Tips . . . . . . . . . . . . . . . . . . . . . . 22-5

UniData Performance Factors . . . . . . . . . . . . . . 22-7

Database Design Considerations . . . . . . . . . . . . 22-7

Using Alternate Key Indexes . . . . . . . . . . . . . 22-7

Sizing Static Hashed Files . . . . . . . . . . . . . . 22-7

Sizing Dynamic Hashed Files . . . . . . . . . . . . . 22-8

UniBasic Coding Tips . . . . . . . . . . . . . . . 22-8

UniBasic Profiling . . . . . . . . . . . . . . . . . . 22-11

1. Compile the Programs with -G . . . . . . . . . . . 22-11

2. Execute the Programs with -G . . . . . . . . . . . . 22-11

3. Review the Profile Output . . . . . . . . . . . . . 22-11

UniData Performance Monitoring: udtmon . . . . . . . . . 22-15

udtmon: UniData User Statistics . . . . . . . . . . . . 22-18

udtmon: File I/O Statistics . . . . . . . . . . . . . . 22-19

udtmon: Program Control Statistics . . . . . . . . . . . 22-21

udtmon: Dynamic Array Statistics . . . . . . . . . . . 22-24

udtmon: Lock Statistics . . . . . . . . . . . . . . . 22-25

udtmon: Data Conversion Statistics . . . . . . . . . . . 22-28

udtmon: Index Statistics . . . . . . . . . . . . . . . 22-29

udtmon: Mglm Performance . . . . . . . . . . . . . 22-31

22 -2 Ad

Performance Monitoring and TuningThis chapter outlines factors that can affect UniData performance on your

UNIX platform, lists generic UNIX tools for monitoring components of your

system, and describes UniData-specific procedures for monitoring

performance.

22-3

UNIX Performance ConsiderationsOptimizing performance for any application on a UNIX platform may

involve tuning and balancing among the four components of a UNIX system:

■ Disk I/O Subsystem—Controls physical input/output to disk

drives.

■ Virtual Memory Subsystem—Manages memory allocation,

swapping, and paging.

■ Process Scheduling Subsystem—Controls how processes use system

resources.

■ Network Subsystem—A collection of computers, terminal servers,

peripherals, and workstations that allows users to share data and

resources.

The following table outlines the significance of these areas for UniData.

Component Relationship to UniData Performance

Disk I/O Subsystem Significant performance factor for UniData as for manydatabase systems. Although UniData includes manyfeatures to increase I/O efficiency, optimizingconfiguration and implementing disk striping (ifavailable) may improve performance.

Virtual MemorySubsystem

Not a performance factor in most cases; UniData processesusually fail if memory is insufficient.

Process SchedulingSubsystem

Not a significant performance factor as long as youconsider elementary scheduling factors.

Network Subsystem May be a significant performance factor due to impacts onI/O performance

UniData Performance and UNIX


UNIX Performance MonitoringMonitor your performance regularly to develop baseline expectations

throughout your application’s 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: Consider setting up a cron job to gather performance statistics at scheduledintervals. Refer to your host operating system documentation for information aboutthe cron command.

Tools

The following table lists UNIX commands useful for performance

monitoring and describes information available from each.

Note: Command names, syntax, and options for performance monitoring tools differamong UNIX versions. Refer to your host operating system documentation forinformation specific to your system.

Tip: Menu-driven performance monitoring toolkits are available from severalvendors.

Tips

The following section lists some suggestions for improving performance.

UNIX Command Description

uptime Displays number of users and average system load(number of processes in the run queue).

iostat Monitors CPU activity and disk I/O activity. Useful foridentifying disk bottlenecks and for balancing disk load.

vmstat Monitors CPU activity and memory usage. Useful foridentifying memory shortages.

ps Displays information about active processes.

UNIX Performance Monitoring Tools

22-5

uptime

If the load average shown by uptime is consistently greater than five, your

system is heavily loaded. Check your memory resources; check disk I/O.

ps, vmstat

Poor system performance associated with processes that are paging or

swapped may indicate memory shortages. Poor performance associated with

processes that are blocked for I/O may indicate disk I/O problems.

iostat

Results that may indicate I/O problems include: CPU in system state more

than 50% consistently; CPU has high idle time despite heavy system load;

CPU is never idle; disk activity is unbalanced.


UniData Performance FactorsWithin UniData applications, the major performance factors are: database

design, file sizing, and program coding efficiency.

Database Design Considerations

■ Structure your database so that records do not exceed a size limit of

4K.

■ When possible, avoid long, multivalued, variable-length records.

■ Locate the most frequently accessed attributes near the beginning of

a record.

■ As much as possible, make record keys numeric and short in length.

Using Alternate Key Indexes

Using alternate key indexes speeds query access in a hashed file, but can slow

file 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 key length allocated is too small

to contain the attributes being indexed. Index overflows can degrade

performance for query as well as update access. The solution is to delete all

of the indexes for a file and rebuild them with a longer maximum length.

Tip: Use the UniData LIST.INDEX command to identify index overflow problems.Consider running LIST.INDEX periodically. See Using UniData for informationabout alternate key indexes.

Sizing Static Hashed Files

Performance suffers if UniData hashed files are allowed to overflow. Level 2

overflow, which occurs when primary keys outgrow the block, has a

particularly serious performance impact. Level 1 overflow, which occurs

when data overflows the block, eventually affects performance as well.

22-7

For information about file sizing commands, refer to Chapter 12, “Managing

UniData Files,” and to the UniData Commands Reference and Using UniData.

Tip: Consider using cron to execute the UniData system-level checkover commandin each of your UniData account directories at regular intervals. Use the output toresize files in level 2 overflow.

Sizing Dynamic Hashed Files

Dynamic 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, refer to Chapter 12,

“Managing UniData Files,” and to the UniData Commands Reference.

UniBasic Coding Tips

The 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 areas to reduce physical file

opens.

Use Efficient Commands

■ Use the EQUATE command when possible.

■ Use CASE statements instead of IF, THEN, ELSE structure whenever

possible. Avoid nested IF, THEN, ELSE statements.

■ 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 data through common areas or an

argument list.

■ Minimize the number of local variables in subroutines.

■ Use inserts, common areas, and argument lists whenever

possible.

■ Use A += B instead of A = A + B.

■ Use LOOP and REMOVE when extracting data sequentially from a

string.

■ Avoid unnecessary shell commands; minimize PERFORM,

EXECUTE, and MDPERFORM statements.

■ Use CALL to run another UniBasic program.

■ Avoid repeated ITYPE( ) function calls.

■ Minimize use of EXECUTE “SELECT.....” by:

■ Using UniBasic SETINDEX, READFWD, READBCK commands.

■ Using the UniBasic SELECT command.

Use Dynamic and Dimensioned Arrays Appropriately

■ Use dynamic arrays when you are accessing small strings and

variables.

■ Use dimensioned arrays when you are handling a large number of

attributes and delimited 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.

22-9

■ 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.

See Developing UniBasic Applications for tips on using UniBasic locks

efficiently.


UniBasic ProfilingUniData enables 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 for UniBasic execution profiles.

1. Compile the Programs with -G

Compile UniBasic programs with the -G option to include information about

internal subroutines in the profile reports.

2. Execute the Programs with -G

To 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 Output

Profile output is stored in the UNIX directory where the UniBasic program

was executed. Output files are called profile.pid and profile.elapse.pid where

pid is the process ID of the user’s UniData process.

The following screen shows a sample profile for a UniBasic program:

%time cumsecs seconds calls name

33.3 0.02 0.02 1 BP/_MAIN_PROG:SUBRA 33.3 0.04 0.02 1 BP/_MAIN_PROG:SUBRB 16.7 0.05 0.01 1 BP/_MAIN_PROG 16.7 0.06 0.01 1 BP/_MAIN_PROG:SUBRC

called/total parentsindex %time self descendents called+self name index called/total children

<spontaneous>[1] 100.0 0.01 0.05 1 BP/_MAIN_PROG [1]

22-11

0.02 0.00 1/1 BP/_MAIN_PROG:SUBRA[2] 0.02 0.00 1/1 BP/_MAIN_PROG:SUBRB[3] 0.01 0.00 1/1 BP/_MAIN_PROG:SUBRC[4]

----------------------------------------------

0.02 0.00 1/1 BP/_MAIN_PROG [1][2] 33.3 0.02 0.00 1 BP/_MAIN_PROG:SUBRA [2]

----------------------------------------------

0.02 0.00 1/1 BP/_MAIN_PROG [1][3] 33.3 0.02 0.00 1 BP/_MAIN_PROG:SUBRB [3]

----------------------------------------------

0.01 0.00 1/1 BP/_MAIN_PROG [1][4] 16.7 0.01 0.00 1 BP/_MAIN_PROG:SUBRC [4]

----------------------------------------------

In this example, the main program is called MAIN_PROG. It has three

internal functions, named SUBRA, SUBRB, and SUBRC.

Note : profile.pid reports execution times as CPU execution time, whileprofile.elapse.pid reports “real” time.

Each profile display includes two sections. The top section presents summary

information, 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.

Field Description

%time Percentage of the total run time used by the program or subroutine.

cumsecs Running sum of seconds for this program or subroutine and allcalled programs and subroutines used within a cycle.

seconds Number of seconds used by the program or subroutine in a cycle.

calls Number of times the program or subroutine was invoked in a cycle.

name Name of the program or subroutine.

UniBasic Profiling: Summary Information


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

index An identifying number assigned by UniData to theprogram or subroutine. UniData assigns the indexes indescending order of execution time. The index in column1 identifies the routine of interest for the group of data (thecurrent index function).

%time Percentage of the total program runtime used by theprogram or subroutine and its descendents.

self Time spent by the program or subroutine either calling, orbeing called by, the program or subroutine identified bythe current index.

descendents Execution time for descendents of this program orsubroutine.

called Line contents differ according to the line of the subsectionyou are reading:

called/total—lines above the index analyze parents; listsnumber of times this index is called by the parent listed inthe name field.

called+self—line containing the index; lists number oftimes the routine is called and the number of times it callsitself.

called/total—lines below the index number analyzechildren and descendents; lists number of times this indexcalls the child listed in the name field.

name Name of the program or subroutine analyzed in this rowof the report subsection.

index Index value assigned to the program or subroutine listedin the name field.

UniBasic Profiling: Detail Information

22-13

The following screen shows one group of data, selected from the sample

UniBasic profile:

called/total parentsindex %time self descendents called+self nameindex called/total children

<spontaneous>0.02 0.00 1/1 BP/_MAIN_PROG

[1][2] 33.3 0.02 0.00 1BP/_MAIN_PROG:SUBRA [2]

----------------------------------------------

This subset of the report contains data relative to the internal SUBRA, which

is identified by index number 2. “Parent” functions, or functions which call

SUBRA, are listed above it; “descendents,” or functions called by SUBRA, are

listed beneath it.

In the example, the report indicates that 33.3% of the execution time for the

entire program is used by SUBRA. The function is called once by the main

program, BP/MAIN_PROG.


UniData Performance Monitoring: udtmonThe UniData Monitor Utility, udtmon, enables you to monitor a variety of

characteristics at the system level. Many of these characteristics can impact

performance. Invoke the UniData Monitor Utility by entering the UniData

system-level command udtmon at a UNIX prompt.

Note: You do not need to log in as root to execute udtmon.

The following screen shows the main UniData Monitoring menu.

Select Display to produce a second menu as shown in the following example.

22-15

You can select either a text display or a graphic display. The following two

screens show the appearance of a graphic display and a text display,

respectively:


Note: In Graphic mode, Display provides a series of lines reflecting the currentnumber of operations covered by the display. You can configure this display using theConfiguration menu. By default, 10 operations per second produces a full-widthdisplay.

Note: In text mode, Display provides five columns of numerical data reflecting thecurrent, average, minimum, maximum, and total number of operations covered bythe display since Monitor/Profile was started. Data is reported in operations persecond. The default display interval is 3 seconds; you can modify the interval usingthe Timer option of the Display menu.

Selecting Display from the Display menu produces a list of characteristics

you can monitor. The screen looks like the following example:

22-17

Note: When you highlight an option on the menu, a brief description displays at thebottom of the screen.

udtmon: UniData User Statistics

When you select UniData User from the Display menu, the following screen

appears:


udtmon: File I/O Statistics

When you select File I/O from the Display menu, the following screen

appears:

22-19

The following table describes the fields in the File I/O display, and indicates

considerations for performance.

Field Description

File Open Number of file opens at the operating system level, fromUniBasic OPEN commands. On UNIX, if the averagevalue in this field is more than 10 (opens per second),performance may suffer. Consider opening files in namedcommon, and using pointers for subsequent access.

File Close Number of file closes at the operating system level, fromUniBasic CLOSE commands.

Temp File Close UniData temporarily closes the least recently accessedopen file when requests for file opens exceed the limit ofopen files per process. If the average value in this field isconsistently more than zero, consider increasing thekernel parameter that defines the number of open files perprocess, and increase the UniData configurationparameter NFILES.

File I/O Fields


udtmon: Program Control Statistics

Selecting Program Control from the Display menu produces a screen similar

to the following example:

Record Read Number of records read by UniData commands (otherthan UniQuery). For most applications, Record Read isgreater than Record Write.

Record Write Number of records written by UniData commands (otherthan UniQuery).

Record Delete Number of records deleted by UniBasic commands (otherthan UniQuery).

Level 1 Overflow Number of operations (reads, writes, and deletes) torecords in level 1 overflow blocks. Compute the totalactivity by adding Record Read, Record Write, and RecordDelete. If you are using only static files and Level 1Overflow is more than 10% of the total activity, use guideto analyze your files and resize them appropriately.

Level 2 Overflow Number of operations (reads, writes, and deletes) torecords in level 2 overflow. If Level 2 Overflow is morethan 2% of total activity, use checkover or guide to identifyfiles in level 2 overflow and resize them appropriately.

Field Description

File I/O Fields (continued)

22-21

The following table describes the fields in the Program Control display, and

indicates performance considerations.

Field Description

Local Call Number of calls to locally cataloged UniBasic programs.Locally cataloged UniBasic programs involve heavy I/Oactivity and increased memory demand, because eachlocal call loads a copy of the executable in memory. In adevelopment environment, using locally catalogedprograms may be normal. In a production environment,if more than 5% of calls are to locally cataloged programs,examine your application and globally catalog programsfor more efficient memory use.

Global Call Number of calls to globally cataloged UniBasic programs.In a production environment, this number should bemuch higher than Local Call. If a program is globallycataloged, users share a single copy of the object code inmemory, which reduces both memory requirements andphysical I/O load.

CALLC Call Number of calls to an external C function, from UniBasicCALLC statements.

CHAIN Call Number of UniBasic CHAIN statements executed.

GOSUB Call Number of UniBasic GOSUB commands executed.

LOOP and GOTO Number of UniBasic LOOP or GOTO commandsexecuted.

EXECUTE Call Number of external UniData command executions (fromUniBasic EXECUTE commands).

PCPERFORM Call Number of PCPERFORM statements, which execute shellor host operating system tasks. If PCPERFORM call ismore than 5% of the total activity, analyze yourapplication and consider replacing PCPERFORM logicwith C routines.

SLEEP Number of UniBasic SLEEP command executions. Asudden increase in this number may indicate that anumber of users are attempting to get a lock on a record.

Program Control Fields

22-23

udtmon: Dynamic Array Statistics

The Dynamic Array menu item displays a screen similar to the following

example:

The fields are counters for executions of UniBasic commands, described in


Field Description

COUNT Number of dynamic array counts, from COUNTcommand.

DELETE Number of dynamic array deletions, from DELcommand.

EXTRACT Number of dynamic array data extractions, fromEXTRACT command.

FIELD Number of dynamic array string extractions, from FIELDcommand.

FIND Number of dynamic array finds, from FIND command.

Dynamic Array Fields


udtmon: Lock Statistics

The following screen displays when you select Lock Statistics:

The following table describes the fields of the Lock Statistics display, and

indicates performance considerations:

INDEX Number of dynamic array substring indexes, fromINDEX command.

INSERT Number of dynamic array inserts, from INS command.

LOCATE Number of dynamic array locations, from LOCATEcommand.

MATCHFIELD Number of dynamic array substring matches, fromMATCHFIELD command.

MATPARSE Number of dynamic array matrix parses, fromMATPARSE command.

REMOVE Number of dynamic array element removals, fromREMOVE command.

REPLACE Number of dynamic array replacements, from REPLACEcommand.

Field Display

Record Lock Number of user-level record locks set by commands suchas READL and READU.

Record Unlock Number of user-level locks released by commands such asRELEASE.

Semaphore Lock Number of user-level resource locks set by commandssuch as LOCK and T.ATT.

Semaphore Unlock Number of user-level resource locks released bycommands such as T.DET or UNLOCK.

Lock Statistics Fields

Field Description

Dynamic Array Fields (continued)

22-25

Note: In some circumstances, this screen may indicate that more records are beingunlocked than are being locked. This is a function of how UniData gathers thestatistics and does not indicate a problem.

Shared Group Lock UniData-level shared lock on an entire group.

Excl. Group Lock UniData-level exclusive lock on an entire group. For mostapplications, the number of shared group locks exceedsthe number of exclusive group locks. If the number ofexclusive group locks is greater than the number of sharedgroup locks, one or more files may be overflowed. Identifythese with guide.

Shared Index Lock UniData-level shared lock on an index.

Excl. Index Lock UniData-level exclusive lock on an index. For mostapplications, the number of shared index locks exceeds thenumber of exclusive index locks. If the number ofexclusive index locks is larger than the number of sharedindex locks, one or more index files may be overflowed.Identify these with LIST.INDEX.

End-of-File Lock UniData-level lock that is required when UniData extendsa file by adding overflow groups or by splitting a dynamicfile. If this number is consistently greater than zero, andthe Dynamic File statistics do not show splitting andmerging, one or more files has overflowed. Identify theseand resize them for improved performance.

Lock Failure Number of times a process attempts to get a user-levellock and fails because the record is already locked. Ifperformance is suffering, analyze your application forimproper lock handling.

GLM Lock Request Number of times a udt process checks the global lockmanager to get a lock.

GLM Lock Failure Number of times a udt process attempts to get a lock fromthe global lock manager and fails because the record isalready locked.

Field Display

Lock Statistics Fields (continued)


udtmon: Sequential I/O StatisticsSelecting Sequential I/O displays statistics for I/O operations on sequential

files. The following screen shows the display.

The following table describes the fields of the Sequential I/O display.

Field Description

OPENSEQ Number of UniBasic OPENSEQ executions.

CLOSESEQ Number of UniBasic CLOSESEQ executions.

READSEQ Number of UniBasic READSEQ executions.

WRITESEQ Number of UniBasic WRITESEQ executions.

OSOPEN Number of UniBasic OSOPEN executions.

OSCLOSE Number of UniBasic OSCLOSE executions.

Sequential I/O Fields

22-27

udtmon: Data Conversion Statistics

Selecting Data Conversion Statistics from the Display menu produces a

screen similar to the following example.

OSREAD Number of UniBasic OSREAD executions.

OSWRITE Number of UniBasic OSWRITE executions.

COMO Write Number of writes to a COMO file.

Field Description

Sequential I/O Fields (continued)


The information on the screen provides an overview of a UniBasic

application in terms of data handling. The following table describes the

actions counted in the Data Conversion Statistics display:

Note: There are no specific performance recommendations for this screen.

udtmon: Index Statistics

Selecting Index Statistics from the Display menu produces a screen similar

to the following example.

Field Description

ASCII Converting strings from EBCDIC to ASCII format.

CHAR Converting characters from numbers to ASCII characters.

EBCDIC Converting strings from ASCII to EBCDIC format.

FMT Formatting strings for output.

ICONV Converting strings from an external format to UniData to internalformat.

OCONV Converting strings from UniData internal format to an externalformat.

SEQ Determining the numeric value of an ASCII character.

Data Conversion Statistics Fields

22-29

The following table describes the fields on the Index Statistics display.

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 hashedfile.

Node Write Number of index node writes.

Node Merge Number of times two nodes merge; this takes place whenentries in one or both nodes decrease.

Node Split Number of times an index node splits; this happens whenentries in the original node increase. An unusual amount ofsplit/merge/reuse activity indicates that one or more indexesare not properly sized. Use the ECL LIST.INDEX command toidentify these, and then execute DELETE.INDEX...ALL, andCREATE and BUILD the indexes with a longer key length.

Node Reuse Number of times a node previously freed by a node merge isused for a node split.

Index Statistics Fields


Note: Notice in the sample Index Statistics display the number of Overflow Readsand Overflow Writes indicates that one or more index may be improperly sized.

udtmon: Mglm Performance

When you select Mglm Performance, the following screen displays.

Log Read Number of reads from an index log file; these occur when anindex which was disabled is reenabled and updated with thecontents of the index log.

Log Write Number of writes to an index log file. These occur while anindex is disabled, as UniData tracks changes by recording themin 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 inan index exceeds a set limit. Reads to and writes from overflownodes slow system performance. If overflow activity (reads andwrites) exceeds 5% of system activity (node reads and nodewrites), use the ECL LIST.INDEX command to identify whichindexes are overflowed. Then execute DELETE.INDEX...ALL,and CREATE and BUILD the indexes with a longer key length.

Overflow Write Number of times UniData writes an overflow node.

Field Description

Index Statistics Fields (continued)

22-31

The following table describes the fields on the Mglm Performance display:

Field Description

Toggle Failure The number of failures for test-n-set instruction in thespecified time interval.

Latch Wait Reserved for future use.

Latch Total Number of toggles used in specified time interval.

Mglm Normal Number of normal locking operations in the specifiedtime interval. This type of locking is the most frequentlyused, and reflects I/O performance.

Mglm Upgrade Number of upgrade locking operation in the specifiedtime interval. If no index related operations occur, thisnumber may be 0.

Mglm Downgrade Number of downgrade locking operations in the specifiedtime interval.

Mglm Release Number of release locking operations in the specified timeinterval.

Mglm Performance Fields


Mglm Wait Number of times Mglm waits for a lock.

Timeout Reserved for future use.

System Calls Number of system calls used by the lock manager in thespecified time interval. This number should be low.

Toggle Rate Toggle Failure / Total Latch. This rate should be low. If thenumber is consistently greater than 5, increase theTOGGLE_NAP_TIME parameter in udtconfig.

Latch Rate Reserved for future use.

Mglm Rate (Mglm Wait) / (Mglm Normal + Mglm Release + MglmUpgrade + Mglm Downgrade). This number is used tocheck I/O performance and should be low.

Field Description

Mglm Performance Fields (continued)

22-33

AAppendix

UniData ConfigurationParameters

This appendix lists the names and descriptions for all UniData

configuration parameters as of Release 6.0. Refer to Chapter 8,

“Configuring Your UniData System,” for additional 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. Thisparameter should not be changed.

SYS_PV Type of P/V operations used for the Recoverable FileSystem (RFS) only. Determined at installation; platformdependent. Don’t change unless instructed by IBM.

udtconfig Parameters That Should Not Be Changed

The following parameters may be changed to suit your environment:


NFILES Number of physical files that can be opened at theoperating system level at one time in a UniDatasession. This limit is for both udt and tmprocesses; the name of the corresponding kernelparameter varies among UNIX versions.

NUSERS Limit for number of UniData user processes (suchas udt and PHANTOM) that can run at the sametime.

WRITE_TO_CONSOLE Switch for turning on and off messaging to yourconsole. Must be greater than zero for messages todisplay at console.

TMP Path of a UNIX directory for storing intermediatework files. Default is \IBM\ud60\temp onUniData for Windows Platforms or /tmp/ onUniData for UNIX. When changing thisparameter on UniData for UNIX, do not forget thetrailing “/.”

NVLMARK Specifies a character to print to represent the nullvalue. The ASCII character that represents thenull value is nonprinting.

FCNTL_ON Used with UniData Physical Lock Manager. If aUNIX platform supports test-n-set instruction,SYS_PV is set to 3 and FCNTL_ON is set to 0. If aUNIX platform does not support test-n-setinstruction, SYS_PV is set to 2 and FCNTL_ON isset to 1. Do not change this parameter unlessinstructed to do so by IBM.

TOGGLE_NAP_TIME If FCNTL_ON is set to 0, the length of time (inmilliseconds) that a process waits to access ashared memory address held by another process.This parameter has no effect if FCNTL_ON is setto 1. Do not change unless instructed to do so byIBM.

udtconfig Parameters That Can Be Changed

A-2 Administering UniData on UNIX

NULL_FLAG Toggles null value handling on and off. If 0, nullvalue handling is off. Must be greater than 0 fornull 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.

N_GLM_GLOBAL_BUCKET The number of hash buckets systemwide, used tohold the lock names in shared memory. Thissetting directly affects performance. Normally,the default value of this parameter should not bechanged. However, if you notice significantdegradation in performance, or your applicationintensively accesses specific files, you can increasethis parameter. The default value is the closestprime number to NUSERS * 3.

N_GLM_SELF_BUCKET The number of hash buckets for the per-processlocking table. This parameter is highlyapplication dependent. If the application requiresa large number of locks in one transaction (morethan 20), you should increase this setting to theclosest prime number to the maximum number oflocks per transaction.

GLM_MEM_SEGSZ The segment size for each shared memorysegment required for the lock manager. Themaximum number of segments is 16. Largeapplication environments require a larger size.Each udt will register the lock names it is lockingin its per-process locking table. This table is alsoorganized as a hashed table.


udtconfig Parameters That Can Be Changed (continued)

A-3

The following parameter is related to internationalization.

The following table describes shared memory related parameters. These

parameters may be changed to suit your environment.


UDT_LANGGRP The language group ID used to distinguish languagegroups that use similar special characters.UDT_LANGGRP is composed of the record mark, escapesequence mark, and the null value mark. The default is255/192/129.

ZERO_CHAR The character you want to use to represent CHAR(0). SeeOSREAD, OSBREAD, READT in the UniBasic CommandsReference for more information.

Internationalization Parameters


SBCS_SHM_SIZE Size, in bytes, of shared memory segments created by sbcsto store globally cataloged programs. sbcs can attach amaximum of 20 segments systemwide. Runtime errorsresult if a user attempts to load a new global program thatexceeds this limit.

SHM_MAX_SIZE Current kernel setting for maximum size (in bytes) of ashared memory segment. This parameter is set atinstallation; if you increase the kernel parameter shmmax,you need to increase SHM_MAX_SIZE to the same valueas well.

SHM_ATT_ADD Starting address for shared memory attachment. Set atinstallation; 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 thatshould be kept attached to a process.

udtconfig Parameters for Shared Memory


SHM_GNTBLS Number of GCTs (global control tables) in CTL. Eachshared memory segment is associated with a GCT. TheGCT registers the use of global pages in its associatedshared memory segment. Cannot exceed the kernelparameter 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 thenumber of processes allowed in a process group. It is set to10 within the system, regardless of the udtconfig setting.

SHM_LMINENTS Number of entries in the MI table of a LCT, which meansthe number of global pages or self-created dynamicsegments that can be attached by a process. Cannot exceed255.

SHM_LCINENTS The number of entries in the CI table of each LCT, which isthe number of local pages that can be attached by aprocess.

SHM_LPAGESZ Size, in 512-byte blocks, of each local page in a global page.A global page is divided into local pages, soSHM_GPAGESZ must be a multiple of SHM_LPAGESZ.

SHM_FREEPCT Percentage of freed global pages in an active global sharedmemory segment that UniData keeps in the global sharedmemory pool. smm checks the current percentage; if thepercentage is less than SHM_FREEPCT, smm creates anew shared segment.

SHM_NFREES The number of inactive shared memory segments thatUniData keeps in the system. smm checks the currentnumber of inactive segments; if the number is larger thanSHM_NFREES, smm returns some inactive global sharedsegments to UNIX.


udtconfig Parameters for Shared Memory (continued)

A-5

The following table describes size limitation parameters.

The following table describes parameters related to dynamic files.


AVG_TUPLE_LEN Number of local pages that matches the averagelength of records in your applications. Specifies thelength of a buffer kept by udt for holding a record.Should not exceed the number of local pages in aglobal 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 bufferis one-quarter to one-half the size of a global page.

MAX_OBJ_SIZE Maximum size, in bytes, of object programs that canbe loaded into shared memory. Object programslarger than this size are loaded into the user’s addressspace instead of shared memory.

MIN_MEMORY_TEMP The minimum number of local pages that should bekept for temporary buffers in a process group.Determined at installation.

udtconfig Parameters for Size Limitation


GRP_FREE_BLK Pertains to dynamic files only; the number of free blockskept in the free block list at the group level. If more blocksare freed, they are kept at the file level.

SHM_FIL_CNT Maximum number of dynamic files that can be openconcurrently, systemwide.

SPLIT_LOAD Default loading factor option (percent) at which a groupin a dynamic file using the KEYONLY option splits.Splitting occurs when the percentage of space in a groupoccupied by keys and pointers reaches the split load. TheECL CONFIGURE.FILE command overrides this forindividual files.

udtconfig Parameters for Dynamic Files


MERGE_LOAD Default loading factor (percent) at which a group pair ina dynamic file using the KEYONLY option merges. Agroup pair is eligible for merging when the sum of thepercentages of space occupied by keys and pointers inboth groups is less than MERGE_LOAD. TheCONFIGURE.FILE command lets users override this forindividual files.

KEYDATA_SPLIT_LOAD

Default loading factor (percent) at which a group in adynamic file using the KEYDATA option splits. Splittingoccurs when the percentage of space in a group occupiedby keys and pointers reaches the split load. The ECLCONFIGURE.FILE command overrides this forindividual files.

KEYDATA_MERGE_LOAD

Default loading factor (percent) at which a group pair ina dynamic file using the KEYDATA option merges. Agroup pair is eligible for merging when the sum of thepercentages of space occupied by keys and pointers inboth groups is less than KEYDATA_MERGE_LOAD. TheCONFIGURE.FILE command overrides this forindividual files.

MAX_FLENGTH Upper size limit, in bytes, of each partition file (dat00x) ofa dynamic file. When a part file reaches this size, UniDatadoes not add further blocks to it, but creates another partfile using the part table. The default value is 1073741824bytes (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 tocreate dynamic file part files.


udtconfig Parameters for Dynamic Files (continued)

A-7

The following parameter is 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 maximumtime to wait for a lock.

TSTIMEOUT Used by the udtts executable to specify themaximum number of seconds to wait for input fromclient about device information. If the information isnot provided, UniData starts without the deviceinformation.

NFA_CONVERT_CHAR If this value is set to 1, UniData converts marks in astream of data to host-specific marks.

udtconfig Parameters for NFA


JRNL_MAX_PROCS Maximum number of journal processes per journal path.

JRNL_MAX_FILES Maximum number of journal files allowed per journalprocess.

udtconfig Parameters for Journaling


MAX_OPEN_FILE Maximum number of hashed files that can be opened byUniBasic OPEN statements, per udt process. Includesrecoverable and nonrecoverable, static, dynamic, andsequentially hashed files; each dynamic file counts as onefile.

UniBasic File-Related udtconfig Parameters


The following table describes parameters related to UniBasic.

MAX_OPEN_SEQF Maximum number of sequential files that can be opened atone time by UniBasic OPENSEQ statements, per udtprocess.

MAX_OPEN_OSF Maximum number of UNIX sequential files that can beopened at one time by UniBasic OSOPEN statements, perudt process.

MAX_DSFILES Maximum number of nonrecoverable dynamic part files(dat00x, over00x) a UniData process can open withUniBasic OPEN statements or ECL commands. Eachdynamic file has at least two part files.


MAX_CAPT_LEVEL Number of levels allowed for nested UniBasicEXECUTE WITH CAPTURING or MDPERFORMWITH CAPTURING clauses. Individual users canset an environment variable that overrides theconfiguration parameter.

udtconfig Parameters for UniBasic


UniBasic File-Related udtconfig Parameters (continued)

A-9

The following parameter is used in semaphore operations.

MAX_RETN_LEVEL Number of levels allowed for nested UniBasicEXECUTE WITH RETURNING or MDPERFORMWITH RETURNING clauses. Individual users canset an environment variable that overrides theconfiguration parameter.

COMPACTOR_POLICY Used to guide BASIC memory compactor to docompaction for BASIC strings.

0 — compact when program is finished

1 — compact when EXECUTE (another BASIC pgm)is completed

2 — compact when EXECUTE (another BASICprogram) or CALL is completed

VARMEM_PCT The percentage of free memory that should be keptin the first global page for UniBasic variables aftercompacting. If the actual percentage is less than thisvalue, UniData keeps one free global page.Otherwise, UniData returns all free global pages toUNIX.


NSEM_PSET Number of semaphores per semaphore set.

udtconfig Parameters for Semaphores


udtconfig Parameters for UniBasic (continued)


The following table describes index-related parameters.

The following parameter is used with the UniData Physical Lock Manager.

The following parameters affect the UniData _HOLD_ file.


SETINDEX_BUFFER_ KEYS Controls whether READFWD and READBCKstatements use a buffering mechanism. Defaultvalue is 0 (buffering off). Individual environmentvariable overrides udtconfig setting;BUFFER.KEYS keyword in the SETINDEXstatement overrides either.

SETINDEX_VALIDATE_KEY Controls whether READFWD and READBCKstatements validate a key value just read. Defaultvalue is 0 (no validation). Individualenvironment variable overrides udtconfigsetting. VALIDATE.KEY keyword in theSETINDEX statement overrides either.

udtconfig Parameters for Indexes


MGLM_BUCKET_SIZE Number of nodes per bucket. If this parameter isinadequate for an application, UniData displays anout of memory message is.

UPL_LOGGING Determines if UPL performs logging. If thisparameter is set to 0, UPL does not perform anylogging. If this value is set to 1, UPL performs logging.

udtconfig Parameters for Physical Lock Manager


MAX_NEXT_HOLD_DIGITS Enables you to specify the number of digits usedfor the next _HOLD_ file number, found in theNEXT.HOLD record of D__HOLD.

CHECK_HOLD_EXIST Determines if UniData checks for the existence ofa _HOLD_ file prior to unconditionally removingit when you specify the BANNER UNIQUEoption with the SETPTR command.

udtconfig Parameters for _HOLD_ File

A-11

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.


SB_FLAG Toggles system buffer on and off. If zero, system buffer isoff. Must be greater than zero for RFS.

Recoverable File System On/Off udtconfig Parameters


BPF_NFILES Per-process logical limit for total number of recoverablefiles that can be opened with UniBasic OPEN statements atone time. If more recoverable files are opened, UniDatacloses files and then reopens them, causing heavyoverhead. This parameter cannot exceed N_AFT.

N_PARTFILE Systemwide total number of recoverable dynamic partfiles that can be open at one time. This limit includes filesopened by ECL and UniBasic. Each dynamic file has atleast two part files, so opening a dynamic file meansopening at least two part files. Even if more than one useropens the same dynamic file, each part file is counted oncetoward the total.

udtconfig Parameters for Recoverable Files


The following parameters are related to the active file table (AFT) used with

the RFS.

The following table describes parameters related to the archiving feature of

RFS.


N_AFT Systemwide limit on the number of recoverable filesand indexes that can be open at one time. This is thenumber of slots in the system buffer AFT. Parameter islike MAX_OPEN_FILES but pertains only torecoverable files. A dynamic file counts as one file. Evenif more than one user opens the same file, it is onlycounted once.

N_AFT_SECTION Number of sections in the AFT. Used for RFS only.

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 multi-level files. Used for RFS only.

N_TMAFT_BUCKET Number of hash buckets in each tm process’s active filetable (TMAFT). Used for RFS only.

udtconfig Parameters for Active File Table


ARCH_FLAG Toggles archiving function on and off for RFS. Must begreater than 0 for archiving.

N_ARCH The number of archive files.

ARCHIVE_TO_TAPE Switch for turning on automatic save of archive files tobackup. Changing the value to 1 turns on this feature.

ARCH_WRITE_SZ Size, in bytes, of blocks for the archive process to writefrom 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.

udtconfig Parameters for Archiving

A-13

The following parameters are used for the system buffer in the RFS.

The following table describes parameters used for message queues with the

Recoverable File System.

The following table describes parameters related to the before image and

after image log files used with RFS.


N_BIG Number of block index groups. This parameterdetermines the size of an index table for accessing the RFSsystem buffer. If you enlarge N_PUT, you should enlargeN_BIG as well. Must be a prime number.

N_PUT Number of 1,024-byte pages in the system buffer. The sizeof the buffer cannot exceed SHMMAX. Sometimes thedefault value of N_PUT must be decreased in order tocomplete a UniData installation.

udtconfig Parameters for the System Buffer


N_PGQ Number of message queues for tm processes to sendmessages to udt processes. Calculated by installation; onequeue for every four licenses.

N_TMQ Number of message queues for udt processes to sendmessages to tm processes. Calculated by installation; onequeue for every four licenses.

udtconfig Parameters for Message Queues


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.

udtconfig Parameters for Before Image/After Image


The following table describes the parameters that determine flushing

intervals for RFS.

The following table describes the parameters related to the sync daemon.

AIMG_MIN_BLKS Minimum number of blocks required in the after imagebuffer before the system flushes the blocks to the afterimage logs. Block size is set in the log configuration table.

BIMG_MIN_BLKS Minimum number of blocks required in the before imagebuffer before the system flushes the blocks to the beforeimage logs. Block size is set in the log configuration table.

AIMG_FLUSH_BLKS Number of blocks that are flushed to the after image logsfrom the after image buffer at one time.

BIMG_FLUSH_BLKS Number of blocks that are flushed to the before image logsfrom the before image buffer at one time.


CHKPNT_TIME Checkpoint interval: number of seconds between flushesof the system buffer to disk.

GRPCMT_TIME Interval, in seconds, between flushes to the after image logset.

udtconfig Parameters for Flushing Interval


N_SYNC Determines how many sync daemons UniData shouldstart.

SYNC_TIME Defines the number of seconds the sync daemon shouldwait before scanning the Block Index Group to flush dirtypages.

udtconfig Parameters for the sync daemon


udtconfig Parameters for Before Image/After Image (continued)

A-15

The following table describes the parameter related to the Century Pivot

date.

The following table describes the parameters related to replication.


CENTURY_PIVOT Determines the century pivot date. Default is 1930.

udtconfig Parameter for Century Pivot Date


REP_FLAG Turns UniData Data Replication on or off. If thisvalue is 0, UniData Data Replication is off. If thisvalue is a positive integer, it is on.

TCA_SIZE The maximum number of entries in the Trans-action Control Area. The default value is 128.

MAX_LRF_FILESIZE The maximum Log Reserve File size, in bytes. Thedefault value is 134217728 (128 MB).

N_REP_OPEN_FILE The maximum number of open replication log filesfor 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 segmentsize. The default value is 67108864 (64 MB).

UDR_CONVERT_CHAR When this value is set to 1, if the publishing systemand the subscribing system have a different I18Ngroup, UniData converts marks and SQLNULLmarks to those on the local machine on the datapassed between the two systems. The defaultvalue is 0.

udtconfig Parameters for Replication


The following table describes the parameters releated to Euro processing.

The following table describes the parameters related to the location of log

files.


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 to1, UniData performs conversion.

SYSTEM_EURO The configurable system Euro encoding. On UNIXsystems, the default is CHAR(164). On WindowsPlatforms, the default is CHAR(128).

TERM_EURO Sets the terminal system Euro Code. On UNIX systems,the default is CHAR(164). On Windows Platforms, thedefault is CHAR(128).

udtconfig Parameters for Euro Processing


LOG_OVRFLO Path to the directory where log overflow files are created.

REP_LOG_PATH Full path to the replication log file.

udtconfig Parameters for Location of Log Files

A-17

BAppendix

Environment Variables forUniData

This appendix lists environment variables that can be set at the

UNIX level to customize a UniData environment. Users with

access to the UNIX prompt can set them before entering UniData

to affect a particular UniData session. System administrators can

also set them in a .login or .profile 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

BACKUP_CNTL_FILE Used by the Recoverable File System (RFS); specifies apath where the udt.control.file can be automaticallybacked up at checkpoint time. If this variable is notdefined, udt.control.file is not backed up.

CSTACKSZ Establishes the maximum number of commands in theECL command stack. Each stack entry can hold a 2720character command. The default is 49.

INIT_BREAKOFF

[0 | 1]

Enables/disables break key prior to invoking UniData. IfINIT_BREAKOFF is not set, the break key is enabled bydefault.

JRNL_PATH Identifies a journaling directory if default path is notused.

Environment Variables for UniData

JRNL_RES_HOLD If this variable is set to a number greater than 0, thejournal restore process sleeps for 1 second at intervals. Ifthe value is between 1 and 100, the process sleeps afterevery 10,000 records are restored. Otherwise, it sleepsafter processing a number of records equal toJRNL_RES_HOLD.

LPREQ Identifies an alternate spooler directory. Must be a fullpath ending in “/”.

MAX_CAPT_LEVEL Number of levels allowed for nested UniBasic EXECUTEWITH CAPTURING or MDPERFORM WITHCAPTURING clauses. This environment variableoverrides the configuration parameter in the udtconfigfile.

MAX_RETN_LEVEL Number of levels allowed for nested UniBasic EXECUTEWITH RETURNING or MDPERFORM WITHRETURNING clauses. This environment variableoverrides the configuration parameter in the udtconfigfile.

MAX_TRANS_

FIELD

Number of TRANS fields that can be kept concurrently;default value is 64; 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 UNIX directory where UniDatacreates NFA client-side. If this variable is not defined, thelogs are created in /tmp.

NFA_LOG_LEVEL Used by NFA; debug level for NFA client processes. Maybe an integer 0-10; level 0 logs only fatal errors, and level10 logs all traffic and many internal functions. The defaultis level 0.

NOCHKLPREQ Bypasses UNIX printer verification; useful for largesystems with hundreds of printers defined.

RLBK_SECOND Used by journaling; controls the interval (in seconds) thatthe journal process waits before re-trying on an operationwhere it detected an error. Must be 1-10; if this variable isnot defined, UniData uses a 1-second interval.


Environment Variables for UniData (continued)

B-2 Administering UniData on UNIX

SETINDEX_

BUFFER_

KEYS

Controls whether READFWD and READBCK statementsuse a buffering mechanism. Default value is 0 (bufferingoff). Individual environment variable overridesudtconfig setting; BUFFER.KEYS keyword in theSETINDEX statement overrides both.

SETINDEX_

VALIDATE_KEY

Controls whether READFWD and READBCK statementsvalidate a key value just read against the record. Defaultvalue is 0 (no validation). Individual environmentvariable overrides udtconfig setting; VALIDATE.KEYkeyword 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 anequal join operation. Default is 7; if this is set to a numberless than 7, UniData SQL uses the default. No upper limit.Must be set before entering udt/SQL, or before startingUniServer.

TABSTOPS Specifies a number of characters to tab in UniBasic PRINTstatements. Must be 1-76. The default is 8.

TMP Identifies an alternate directory for /tmp whenadditional work space is needed by UniData. Must be adirectory path ending with /.

UDT_EDIT Identifies the path of the UNIX text editor UniDatainvokes when users execute the ECL ED command. Thedefault is vi. This variable cannot be set to AE.

UDT_SAVELIST Allows you to specify a default list name for eachUniData user. Set in the user’s .login or .profile. Users canalso specify a list name when executing the SAVE.LISTcommand.

UDT_SELECTSIZE Size of a buffer used to keep select list in memory. If aselect list is larger then the size of this buffer, UniDatawrites it to a file. If UDT_SELECTSIZE is not defined, thesystem uses a buffer size of 10 KB.

UDTBIN Location of UniData executables.



B-3

UDTHOME Location of the UniData home directory, which containsdirectories including sys, demo, lib, work, sybase, andinclude.

VFIELDSIZE Increases the size for the stack of C routines used toprocess 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 withread-only access to the VOC file.

VVTERMCAP The UNIX path of the vvtermcap file needed to run theUniData commands UENTRY, shmconf, and confprod.This variable is not necessary if UDTBIN is defined.



B-4 Administering UniData on UNIX

CAppendix

Configuring SSL forTelnet

/etc

rvers

esdns.

Server Side Configuration:To enable SSL for Telnet on UniData, you will need to edit fourdifferent files on the database server. The first two are system filesnamed services and inetd.conf. Both of these files reside under thedirectory on the unix server. Use vi or another suitable text editor tomake the changes described below.

Add the following line in /etc/services:

telnets 992/tcp

Where “telnets” is the service name. This can be any name of youchoosing. 992 is the standard port number used for secure telnet serand tcp is the protocol name for the service.

Add the following line in /etc/inetd.conf

telnets stream tcp nowait root UDTBIN_PATH/udtelnetdudtelnetd [-dN] [-o dir]

Where “telnets” is the telnet service name you specified in /etc/servicand UDTBIN_PATH is the path to the UniData bin directory. Udtelnetis the UniData secured telnet server and it takes the following optio

you

ared

d ided in a

or

.

g

There are two new files introduced into the unishared directory on the server thatneed to be familiar with,udtelnetd and .udscrfile. They are located on the databaseserver, under /unishared/unitelnet. You can determine the location of the unishdirectory by typingcat /.unishared. The two files are listed below.

udtelnetd.conf- This is the UniData telnet server configuration file and has thefollowing format:

security_context_record_id password

Where security_context_record_id and password are the security context recorand password used to get security context in a pre-generated security file (defin.udscrfile). This security context record id is system-wide, which is managed onper-machine basis rather than a per-user basis.

.udscrfile- This is the security file containing the path to the security context file. Fmore information on the Security Context File, refer to the Developing UniBasicReference Manual.

Option Description

-d N Debug level. Where N is the debugging level to be specifiedfrom 0 to 3. A setting of 3 is the highest level of debugging anda setting of 0 means no debugging message will be recordedThe debugging message goes into the TMP_DIR/udtelnet-pid.log where TMP_DIR is a temporary directory and pid is theprocess id of udtelnetd invoked by inetd.

-o dir Specify the path to the temporary directory. The default settinis /tmp.

C-2 Administering UniData on UNIX

@

Index

O QCA B D E F G H I J K L M N P R S T U V W X Y Z

Index

Aabnormal shutdown

removing ipc structure after 9-14

access modes, UNIX 2-6

accounts

displaying directory of 3-6

UniData

clearing space in 10-11

creating 8-10, 10-5

defined 3-4

deleting 10-10

described 10-4

files in 10-7

listing contents of 10-5

locating 8-4

permissions for 10-5

subdirectories in 10-6

UNIX

compared to UniData

account 8-10

creating 8-11, 11-4

relationship to UniData

account 10-4

acctrestore command

described 10-9

ACCT.SAVE command

described 10-9

not blocked by dbpause 9-7

adding

record to QUERY.PRIVILEGE

file 11-27

UNIX users 8-11, 11-4, 14-4

address space

attaching memory segment to 5-4

algorithms, hashing 3-11, 12-4

alternate key indexes

creating index file for 3-19

defined 3-4

performance 22-7

ANALYZE.FILE command

summarized 12-28

archive files

synchronizing with backup file 9-

8

ASCII files

as per-file part table 12-10, 12-12

assigning

part table to file 12-10

shared memory structure 5-9

attaching

shared memory segment 4-6, 5-4

auditor command

described 12-19

summarized 12-29

automatic indexing

disabling 3-19

enabling 3-19

automatic startup of UniData 9-6

Bbackground processes

daemon as 4-4

storing output from 10-7

backing up

file 8-14

UniData account 8-14, 10-9

backup files, synchronizing with

archive file 9-8

bar code readers, communicating

with 7-8

base.mk file 20-6

O QCA B D E F G H I J K L M N P R S T U V W X Y Z @

binary data files 3-11

BLIST command


block size

changing 8-13, 12-28

specifying

for dynamic file 12-15

for static files 3-11

block usage messages 12-56

blocking UniData processing 9-7

BLOCK.PRINT command


BLOCK.TERM command


BP directory

defined 10-6

described 3-16

dictionary for 10-7

buffering

UniBasic variables 5-5

building

shared memory structures and

tables 4-6

BUILD.INDEX command

populating index with 3-19

temporary disk storage and 3-21

BY.EXP sorts

storing temporary information

for 10-7

B+ tree format for indexes 3-19

CCallBasic

accessing UniData from C

program 20-20

building executable 20-29

C program example 20-22

callbas.mk file 20-27

requirements 20-20

steps for using 20-26

udtcallbasic_done( ) function 20-

21

udtcallbasic_init( ) function 20-20

UniBasic subroutine example 20-

25

using new executable 20-31

U_callbas( ) function 20-21

callbas.mk file 20-27

CALLC command

described 20-3

CATALOG command 19-5

cataloging

direct 19-5

global 19-6

local 19-5

programs 19-11

subroutines 19-11

cfuncdef file 20-6

cfuncdef_user file

creating 20-10

described 20-6

editing 20-12

changing

block size 8-13

file characteristics 8-13

file ownership 2-5

hashing algorithm 8-13

modulo 8-13

name of UniData file 12-27

permission 2-5

checking

UNIX ipc ID 4-7

CHECKOVER command


summarized 12-28

checkover command

summarized 12-29

checkpoints

forced by dppause command 9-7

chgrp UNIX command 2-5

chmod UNIX command 2-5

chown UNIX command 2-5

cleanupd daemon

described 4-7

lcp daemon and 4-5

log and error log for 4-9

sbcs daemon and 4-6

smm daemon and 4-7

cleanupd log file

entries made at UniData

startup 9-4

cleanupd.errlog file 4-9

cleanupd.log file 4-9

CLEARDATA command


clearing

hung processes 9-12

locks 13-18

semaphore lock 13-9

space in UniData account 10-11

system resources 9-10

UniData process 9-10

user 9-10, 9-12

_HOLD_ subdirectory 10-11

_PH_ subdirectory 10-11

CLEAR.ACCOUNT command

described 10-11


CLEAR.FILE command

failed due to dynamic file in part

table 12-11

removing records from dynamic

file with 12-20

security considerations for 11-12

summarized 12-27

CLEAR.LOCKS command


CLR command


CNAME command


summarized 12-27

commands

for clearing users and

processes 9-10

for dual-terminal debugging 16-

13

for file handling 12-27


reference for 10-7

UniBasic locking 13-7

UniBasic tape 16-5

UniData LINE 16-10

UniData printing 15-9

UniData tape 16-4

communicating

with hardware devices 7-4

COMO command

captured terminal input/output

and 10-7


computing

control table list (CTL) size 5-8

configuration file 12-8

configuration parameters

2 Administering UniData on UNIX


complete list of A-1

GRP_FREE_BLK 12-20

KEYDATA_MERGE_LOAD 12-8

KEYDATA_SPLIT_LOAD 12-8

MAX_FLENGTH 12-9, 12-12, 12-

15

MAX_OBJ_SIZE 5-13

NUSERS 5-8

PART_TBL 12-10

SBCS_SHM_SIZE 4-6, 5-13, 19-7

setting 8-6

shared memory 5-5, 5-12

SHM_FREEPCT 5-11

SHM_GNPAGES 5-8, 5-11

SHM_GNTBLS 5-7, 5-8, 5-14, 17-

18

SHM_GPAGESZ 5-11

SHM_LCINENTS 5-8

SHM_LMINENTS 5-14

SHM_LMINRNTS 5-8

SHM_LPAGESZ 5-11

SHM_LPINENTS 5-8

SHM_MAX_SIZE 19-7

SHM_NFREES 5-11

systest 17-14

TMP 3-22

CONFIGURE.FILE command


summarized 12-28

configuring

automatic startup of UniData 9-6

printer 15-3

UniData 8-4

UNIX kernel 5-4

control information (CI) table 5-7

control table list (CTL)

calculating size of 5-8

creating in shared memory 4-7

described 5-6

error message 17-26

memory requirements and 8-5

shmconf 17-11

controlling

access to ECL/UNIX prompt 11-

18

converting

between low-byte and high-byte

format 8-13

data files 8-13

legacy application 3-19

nonrecoverable file to

recoverable 8-13

static file to dynamic 8-13

COPY command


counter table (CT) 5-7

cpio UNIX utility 10-9

CREATE.FILE command

PARTTBL keyword with 12-10


static file 3-6

summarized 12-27

umask and 2-9

CREATE.INDEX command

alternate key index and 3-19


creating

alternate global catalog space 19-

3, 19-17

dat001 file 12-13

dynamic file 12-14

empty file 2-9

index file 3-19

over001 file 12-13

part table 12-11

pointer to file 8-14

prefix table 12-20

QUERY.PRIVILEGE file 11-26

recoverable file 8-13

schema 8-13

shared memory segment 5-9

shared memory structure

for globally cataloged

program 5-5

for internal table 5-5

UniData account 8-10, 10-5

UniData files 3-6

UNIX account 8-11, 14-4

UNIX directory 10-5

UNIX link 12-13

VOC records 8-14

VOC (vocabulary) file 10-5

cron UNIX command 22-5

CT (counter table) structures 5-7

CTL

See control table list (CTL)

CTLG directory 10-7

CTLGTB directory 19-9

customizing

default permissions 11-8

file permissions 2-10

length of dictionary attribute 11-

24

UniData security 11-3

VOC file 2-10, 10-5, 11-12

Ddaemons

cleanupd 4-7

defined 4-4

described 4-5

listing 9-10

log files for 4-9

monitoring 4-9

Recoverable File System (RFS) 2-

11, 4-8

sbcs (shared basic code server) 4-

5

smm (shared memory

manager) 4-6

UniData

running as root 2-11

damaged files

defined 12-31

detecting 12-34, 12-40

repairing 12-43

damaged groups

repairing 12-29, 12-46

unloading contents of 12-29

dat001 file 3-13, 12-6, 12-13

data files

converting 8-13

data integrity 12-34

data part files 12-16

databases

terminfo 7-5

DATE.FORMAT command


dbpause command

described 9-7

dbpause_status command

described 9-9

default files for UniData

account 10-4

default permissions



assigned at UniData

installation 2-10, 8-12

for file creation 2-8

UNIX 11-8

defining

peripheral device for UniData 8-

10

printer for UniData 15-12

tape unit for UniData 16-7

DELETE command

removing records from dynamic

file with 12-20

removing selected files with 10-

11


deleteuser command

described 9-12


removing user process with 14-8

summarized 9-10

DELETE.CATALOG command


DELETE.FILE command

failure due to dynamic file in part

table 12-11


summarized 12-27


DELETE.INDEX command

removing index file with 3-19


DELETE.LOCKED.ACTION

command


deleting

file from UNIX directory 2-5

UniData account 10-10

detecting

file corruption 12-34, 12-40

device drivers 7-4

device files 7-4

device ID

in part table entry 12-11

dictionaries

sharing 3-17, 3-18

for UniData account files 10-7

for VOC file 8-10

dictionary attributes

customizing length of 11-24

dictionary (DICT) files

UNIX file type for 3-4

dictionary files 3-4

direct cataloging 19-5

directing output to printer 7-7

directories

default permissions for 11-8

displaying for account 3-6

dynamic file 12-12

home, UniData 8-11

directory (DIR) files 3-5, 3-16

directory permissions

described 2-4

octal values for 2-8

DISABLE.INDEX command


turning off automatic indexing 3-

19

disabling

automatic indexing 3-19

disk drives, communicating

with 7-4

disk input/output (I/O) 8-4

disk space use 12-4

disk storage, temporary 3-21

disk striping 8-4

displaying

account directory 3-6

globally cataloged program

use 19-16

ipc facility 9-13

list of file and record locks 13-10

list of processes waiting for

locks 13-13

list of semaphore locks 13-12

memory use 17-16, 17-20, 17-21

message queue information 18-4

shared memory configuration

parameters 5-12


information 18-4

statistics for dynamic file 12-28

UNIX system semaphore

information 18-4

user and process activity 14-6

user ID and group 11-6

dual-terminal debugging

described 16-13

procedure 16-14

dumpgroup command

described 12-43

example 12-51


summarized 12-29

dynamic files

analyzing with auditor tool 12-19

checking for inconsistencies 12-

29

creating or modifying part

table 12-11

described 3-12, 12-6

disk space and 12-20

estimating required space for 12-

12

estimating size for part file 12-16

expanding part files for 12-15

expanding to new file system 12-

17

index file and index log file for 3-

20

KEYDATA split/merge type 12-8

KEYONLY split/merge type 12-8

locating directory and part

files 12-12

management tools for 12-19

merging 12-7

messages 12-60

modulo table for 5-5

moving part file 12-20

overflow block 3-13, 12-7

part file 12-9

part table 12-9

rebuilding .fil_prefix_tbl 12-18

repairing corruption in 12-50

resolving inconsistencies 12-29

selecting block size for 12-15

selecting minimum modulo 12-14

selecting split/merge type 12-8

splitting 12-7

symbolic link and 3-14


.fil_prefix_tbl file 12-17

D_BP file 10-7

D_CTLG file 10-7

D_MENUFILE file 10-7

D_QUERY.PRIVILEGE file

editing 11-27

D_SAVEDLISTS file 10-7



D_savedlists file 10-8

D_VOC file 10-7

D__HOLD_ file 10-7

D__PH_ file 10-7

D__REPORT_ file 10-8

D__SCREEN_ file 10-8

D___V__VIEW file 10-8

EECL commands

not blocked by dppause 9-7

ECLTYPE command


ED command


editing

dictionary for


empty files, creating 2-9

ENABLE.INDEX command


turning on automatic updating 3-

19

enabling

automatic indexing 3-19

environment variables

complete list of B-1

LPREQ 15-17

NOCHKLPREQ 15-17

PATH 8-12

setting 1-3, 3-8, 8-11

UDTBIN 8-11

UDTHOME 8-11

WORKPATH 20-17

errno.h UNIX file 17-25

error messages

from guide command 12-56

common 21-7

shared memory 17-3

smm error messages 17-25

UniData error logs 17-25

UniData error messages 21-7

estimating

memory requirement 8-5

size for part file 12-16

space required for dynamic

file 12-12

/etc/group file 11-4

/etc/passwd file 11-4

/etc/security/passwd file 11-4

/etc/shadow file 11-4

exclusive locks 13-6

execute permissions 2-4

expanding part file 12-15

expression buffers, storing 4-7

extensions to termcap file 7-5

Ffield-level security

customizing security with 11-22

turning on 11-25

file access messages 12-56

file characteristics, changing 8-13

file corruption

after UniData crash 21-4

causes of 12-31

detecting 12-34, 12-40

repairing 12-43

udt.errlog file and 4-10

file locks

displaying list of 13-10

setting 13-6

file owner, permissions for 2-4

file permissions

described 2-4


FILELOCK command

summarized 13-7

files

archive 9-8

backup 9-8

base.mk file 20-6

binary data 3-11

BP file 3-16

cfuncdef file 20-6

cfuncdef_user file 20-6, 20-10, 20-

12

changing name of 12-27

changing parameters of 12-28

checking for level 2 overflow 12-

28

converting data 8-13

corrupted 12-31

creating 3-6, 12-27

damaged 12-29


deleting 12-27

displaying statistics for a hashed

file 12-28

dynamic 12-6

etc/shadow file 11-4

GUIDE_ADVICE.LIS file 12-35,

12-38

GUIDE_BRIEF.LIS file 12-38

GUIDE_ERRORS.LIS file 12-35,

12-38

GUIDE_FIXUP.DAT file 12-35,

12-38

GUIDE_INPUT.DAT file 12-36

GUIDE_STATS.LIS file 12-38

hashed 10-7, 12-4

index file 3-20

index log file 3-20

log 9-4

name, reference for 10-7

new.mk file 20-16

over001 file 3-13, 12-6, 12-13

overflow 12-6

primary data 12-6


removing record from 12-27

repairing damaged group 12-29

setting a pointer to UniData

file 12-27

spooler configuration 7-7

static 12-5

tape device 7-6

udtconfig file 3-21, 12-8

UDTSPOOL.CONFIG file 15-4

unloading contents of damaged

group 12-29

vvtermcap file 7-5

.login file 3-22, 11-7, B-1

.profile file 3-22, 11-7, B-1



/us_admin file 11-8

_HOLD_ file 10-7

_MAP_ file 19-9

_PH_ file 10-7

_REPORT_ file 10-8

_SCREEN_ file 10-7

FILEUNLOCK command



summarized 13-7

FILE.STAT command

summarized 12-28


finger UNIX command 14-5

fixfile command

described 12-46

repairing dynamic file with 12-50

repairing static file with 12-48

summarized 12-29

fixfile group


fixgroup command

described 12-45


summarized 12-29

fixtbl command

described 12-19

rebuilding account with 12-18

summarized 12-29

FLOAT.PRECISION command


forcing logoffs 9-10

free block messages 12-59

FULLPATH parameter 11-24

function definition file 20-4

GGCT

See global control tables (GCT)

gencdef command 20-16

genefs command 20-16

general information (GI) table

defined 5-7

size of 5-8

genfunc command 20-16

GET command

communicating with GET and

SEND 16-11

GI

See general information (GI) table

gid

See group ID (gid)

global catalog

alternate 19-17

contents of 19-8

described 19-6

managing 19-8

global control tables (GCT)

described 5-7

process cleanup and 4-7

size of 5-8

smm daemon and 4-7

sms command and 17-18

global pages

determining size and number

of 5-11

dividing segment into 5-5

number to keep free 5-11

releasing 5-9

globally cataloged programs

loading and tracking 4-5

shared memory structure for 5-5

GRANT command

customizing permissions with 2-

10, 11-21

customizing table access with 8-

13

group header messages 12-57

group ID (gid)

displaying 11-6

record for 11-4

root access and 10-5

group logins 11-5

group members

file permissions for 2-4, 2-10

groups UNIX command 14-5

GROUP.STAT command

summarized 12-28

GRP_FREE_BLK parameter 12-20

gstt command

described 17-20

monitoring resource availability

with 17-19

guide command

creating UniData output file

with 12-38

described 12-34

error messages from 12-56

error output from 12-53

guidelines for using 12-53


output files from 12-38

purpose of 12-34

recoverable file and 12-39

summarized 12-29

GUIDE_ADVICE.LIS file 12-35, 12-

38

GUIDE_BRIEF.LIS file 12-35, 12-38

GUIDE_ERRORS.LIS file 12-35, 12-

38

GUIDE_FIXUP.DAT file 12-35, 12-

38

GUIDE_INPUT.DAT file 12-36

GUIDE_STATS.LIS file 12-38

Hhardware devices, communicating

with 7-4

hash groups

identifying 12-27

hash type

changing for static file 12-28

default 12-4

hashed files

checking for level 2 overflow 12-

28

default hash type 12-4

defined 3-11

dynamic 12-6

repairing corruption 12-43

static 12-5

structure of 12-4

in UniData account 10-7

hashing

dat001 file and 3-13

hashing algorithms 3-11, 12-4

HASH.TEST command


header key messages 12-57

HELP command


_HOLD_ file

clearing 10-11

defined 10-7

dictionary for 10-7

home directory

UniData 8-11

UNIX account and 11-6

hung processes, clearing 9-10



Iid UNIX command 11-6

identifying

damaged file 12-29

idx001 index file 3-20

index files

applying updates to 3-19

creating 3-19

dynamic file 3-20

idx001 file 3-20

populating 3-19

removing 3-19

static file 3-20

index log files 3-19, 3-20

index part files 12-16

indexes

alternate key 3-4

indirect segments 5-13

input/output (I/O)

disk 8-4

terminal 10-7

intermediate results, storing 5-5

internal flags, setting 4-7

internal tables, shared memory

structure for 5-5

interprocess communication (ipc)

facility

defined 6-3

removing 9-10

structure


removing 9-10, 9-14

UNIX kernel parameters and 6-4

iostat UNIX command 22-5

ipc

See interprocess communication

(ipc) 6-3

ipc IDs, checking 4-7

ipcrm UNIX command

managing ipc resources with 6-3

removing ipc facility with 9-14,

18-9

ipcs UNIX command


ipcstat command

checking status of ipc facility 21-5

described 9-13



output from 18-4

summarized 9-10

syntax for 18-4

I/O

See input/output (I/O)

Kkernel parameters

msgmap 6-4

msgmax 6-4

msgmnb 6-4

msgmni 6-4

msgseg 6-4

relationship to UniData 5-14

resetting 8-5

semmni 6-6

semmnu 6-6

shmmax 5-4

shmmni 5-4, 5-7

shmseg 5-4

KEYDATA split/merge type 12-8

KEYDATA_MERGE_LOAD

parameter 12-8

KEYDATA_SPLIT_LOAD

parameter 12-8

KEYONLY split/merge type 12-8

kill UNIX command 9-12, 12-32, 14-

8

killing

user process 9-12

Llcp daemon



lcp.errlog file 4-9

lcp.log file 4-9

LCT (local control table)

described 5-7

number of shared memory

segments 17-18

LD-type files 3-18

legacy applications, converting 3-

19

level 1 overflow

described 12-5

static file and 3-11

level 2 overflow

checking hashed file for 12-28

described 12-5

minimizing for dynamic file 12-6

static file and 3-11

LF-type files 3-17

LIMIT command

displaying default spooler

command with 15-20

displaying spooler options

with 7-7

summarized 15-9

line devices, defining for

UniData 8-10

LINE.ATT command


setting semaphore lock with 13-9

summarized 16-10

LINE.DET command


summarized 16-10

LINE.STATUS command

summarized 16-10

linking C routines into UniData 20-

4

links

symbolic

backup procedure and 3-14, 8-

14

creating 12-17

UNIX

creating 12-13

setting 3-9

used by UniData 3-4

list permissions, directory 2-4

listing

contents of UniData account 10-5

ipc structures 9-10

locks 13-10

LISTPEQS command

summarized 15-10

LISTPTR command

summarized 15-10

LISTUSER command

monitoring user processes 14-6

used in clearing locks 13-21

listuser command



displaying process ID with 9-12

summarized 9-10, 14-6


LIST.INDEX command


LIST.LOCKS command

checking for lock problem

with 21-6

described 13-12

LIST.QUEUE command

checking for lock problem

with 21-6

described 13-13

displaying locks requested 13-21

LIST.READU command

checking lock problem with 21-6

described 13-10

displaying current locks with 13-

21


LIST.TRIGGER command


load factor for splitting/merging

groups 12-7

local catalog 19-5

local control table (LCT)

described 5-7

number of shared memory

segments 17-18

size of 5-8

local pages

determining size and number

of 5-11

subdividing global page into 5-5

locally cataloged programs

storing 10-6

LOCK command


summarized 13-9

locking commands 13-7

locks

clearing 13-18

file


setting with UniBasic

command 13-6

record

clearing 13-20


setting 13-6

semaphore

clearing 13-22


setting 13-9

tracking 4-5

log files

described 9-4

identifying ipc facilities 18-7


for UniData daemons 4-9

logical volume management

protocol 8-4

.login file 3-22, 11-7, B-1

LOGIN paragraphs

defining 11-18

logins

group 11-5

separate 11-5

UNIX 11-4

logoff, forced 9-10

LOGOUT paragraphs

defining 11-18

LOGTO command

dbpause and 9-8

effect on LOGOUT paragraph 11-

18

long record messages 12-59

LPREQ environment variable 15-

17

lpstat UNIX command 15-11

LPTR keyword

generating print request with 15-

8, 15-23

LS command

displaying account directory

with 3-6

listing contents of account

with 10-5

ls UNIX command 2-5

lstt command

described 17-21

sms command and 17-19

L-type locks 13-6

Mmake files 20-4, 20-16

make UNIX utility 20-18, 20-29

makeudt command

described 20-6

linking C function with 8-13


setting up development test

with 20-15

MAP command

example of 19-9

_MAP_ file 19-9

MATREADL command

summarized 13-7

MATREADU command

summarized 13-7

MATWRITE command

summarized 13-7

MATWRITEU command

summarized 13-7

MAX_FLENGTH parameter 12-9,

12-12, 12-15

MAX_OBJ_SIZE parameter 5-13

memory

troubleshooting 17-25

memory information (MI) table 5-7

memresize command

PARTTBL keyword with 12-10

per-file part table and 12-12

summarized 12-29

MENUFILE file

component of UniData

account 10-7

dictionary for 10-7

menus

definition, storing 10-7

MERGE_LOAD parameter 12-8

merging groups in dynamic file 12-

7

merging threshold 12-7

message queues

congestion in 13-22



5

UniData 6-4

UNIX 6-4

MI (memory information) table 5-7

MIN.MEMORY command


mkdir UNIX command



creating directory for UniData

account 8-11, 10-5

MODIFY command


modifying

part table 12-11

TMP configuration parameter 3-

22

modulo

automatic increase in dynamic

file 12-6

changing 12-28

dynamic file size and 3-12

selecting minimum 12-14

specifying for static file 3-11

table for dynamic file 4-7, 5-5

monitoring

file integrity with guide

command 12-53

globally cataloged program

use 19-16


facilities 18-4

memory 17-21

shared memory 17-4

UniData daemons 4-9

UniData performance 22-3, 22-15

user processes 14-6

moving

part file 12-20

msgmap kernel parameter 6-4

msgmax kernel parameter 6-4

msgmnb kernel parameter 6-4

msgmni kernel parameter 6-4

msgseg kernel parameter 6-4

MULTIDIR file type 3-5, 3-18, 8-14

MULTIFILE file type 3-5, 3-17, 8-14

multilevel directory files 3-18

multilevel files

described 3-17


mvpart command

described 12-20

summarized 12-30

MYSELF command

summarized 14-6

Nnewacct command

creating UniData account with 8-

11

described 10-5

files created by 3-4, 10-4

setting permissions with 2-10

newgrp UNIX command 11-6

newhome command

creating UniData account

with 19-17

NEWPCODE command

described 19-14

newversion command 19-13

NEWVERSION keyword 19-12

new.mk file 20-16

NOCHKLPREQ environment

variable 15-17

nonrecoverable file

converting to recoverable 8-13

NUSERS parameter 5-8

Oobject code, UniBasic 10-6

octal values 2-8

ON.ABORT command

preventing access to ECL/UNIX

prompts 11-18

OPEN security as system

default 11-22

other header messages 12-57

other users, file permissions for 2-4

output

from background process 10-7

directing to printer 7-7

file 3-21

from guide command 12-35, 12-

38

from verify2 command 12-42

over001 file 3-13, 12-6, 12-13

overflow

dynamic file 12-7

files 12-6, 12-16

static file in 3-11

owner


Pparagraphs

LOGIN 11-18

LOGOUT 11-18

reference for 10-7

part files

data 12-16

defined 12-9

dynamic file and 12-9

estimating size for 12-16

index 12-16

locating 12-12

moving 12-20

overflow 12-16

part tables

components of 12-10

constraints for 12-11

creating dynamic file 12-13

dynamic files and 12-9

entries resolving to same device

ID 12-11

memresize command and 12-12

per-file 12-10

selecting location for new part

file 12-17

system default 12-10

partitioning shared memory 5-4

parttbl

See part tables, parttbl file

parttbl file


PARTTBL keyword

CREATE.FILE command

with 12-10

memresize command with 12-10

PART_TBL parameter 12-10

PATH environment variable 1-3, 8-

12, 9-4

pausing

UniData 9-7

per-file part tables 12-10

performance

alternate key index and 22-7, 22-

29

application design and 22-8, 22-

23

database design and 22-7

file and record locking and 22-25



file I/O and 22-20

file overflow and 12-5

file sizing and 22-7, 22-8

monitoring 22-3

tuning 22-3

UniData considerations 22-7

UNIX considerations 22-4

UNIX monitoring tool 22-5

using udtmon 22-15

peripheral devices, defining for

UniData 8-10

permissions

file and directory

described 2-4



recommended settings 11-9

setting for UniData account 10-5

UniData SQL 11-21

UNIX, customizing 11-8

PHANTOM command

background process and 10-7

_PH_ file

clearing 10-11

defined 10-7

dictionary for 10-7

PI (process information) tables 5-7

pid

See process ID (pid)

pointers

creating 8-14

to data file 10-4, 12-27

setting 3-6, 11-17

stored in VOC file 3-4, 8-10

populating

index file 3-19

subdirectory 10-7

prefix tables

inconsistencies with symbolic

link 12-29

mvpart command and 12-20

prefixes

related to path name 12-18

preventing

file corruption 12-32

primary data file 3-13, 12-6

PRINT command

spooling and 15-8

print files

storing in _HOLD_ directory 10-7

printers

communicating with 7-4

defining for UniData 8-10

printing

creating a dummy spooler 15-22

decoding a UniData print

command 15-21

example of 15-17, 15-18

overview of 15-4

to UNIX device 15-19

UNIX spooler and 7-7

using a quoted string 15-20

PRIV parameter of


privileges

See permissions

process cleanup

role of lcp daemon in 4-5

role of sbcs daemon in 4-6

role of smm daemon in 4-7

process ID (pid)

stopping process with 9-12

process information (PI) tables 5-7

processes

clearing 9-10

UniData 2-11

waiting for lock 13-13

product.info file



profiling UniBasic applications 22-

11

program variables, buffering 4-6

PROTOCOL command

summarized 16-10

ps UNIX command

checking for unneeded locks

with 13-21

checking slow response time

with 21-6

getting process ID with 9-12

performance monitoring with 22-

5

PTRDISABLE command


PTRENABLE command


Qquery privileges 8-13

query records, storing 4-7

QUERY.PRIVILEGE file

adding record to 11-27

creating 11-26

described 11-23

editing dictionary for 11-27

Rread permissions 2-4

READBCKL command

summarized 13-7

READBCKU command

summarized 13-7

READFWDL command

summarized 13-7

READFWDU command

summarized 13-8

READL command

summarized 13-8

read-only locks 13-6

READU command

summarized 13-8

READVL command

summarized 13-8

READVU command

summarized 13-8

REBUILD.FILE command

summarized 12-28

RECORD command

summarized 12-27

record locks

clearing 13-20


setting 13-6

RECORDLOCKL command

summarized 13-8

RECORDLOCKU command

summarized 13-8

records

adding to QUERY.PRIVILEGE

file 11-27

deleting from file 12-27

identifying group where key is

hashed 12-27



Recoverable File System (RFS)

checkpoint 9-7

crash recovery 21-5

daemons 2-11, 4-8

message queue 6-5

saving and restoring UniData

account with 10-9

semaphore and 6-6

shared memory and 5-5

sm daemon 9-4

synchronizing archive with

backup 9-8

system buffer and 5-14, 8-5, 17-12

recoverable files

creating 8-13

guide command and 12-39

recovering

semaphore 6-6

RELEASE command

summarized 13-8

releasing

file lock 13-7

record lock 13-7, 13-20

semaphore lock 13-9

shared memory 5-5, 5-9

remote entries 8-13

remote items

security for 11-15

removing

index file 3-19

ipc structure 9-10, 9-14, 18-8

user process 14-8

repairing

corrupted file 12-43

damaged group 12-29, 12-46

dynamic file 12-50

static file 12-48

_REPORT_ file


account 10-7

RESIZE command


summarized 12-28

resizing

static file 12-28

resource locks 13-9

restoring

UniData account 10-9

resuming

UniData processing after

dbpause 9-9

reviewing

backup procedures 8-14

UniData security 8-12

REVOKE UniData SQL command

customizing permissions

with 11-21

customizing table access with 8-

13

RFS

See Recoverable File System (RFS)

rm UNIX command 10-11

root

determining VOC file privileges

for 11-13


running UniData daemons as 2-

11

starting or stopping UniData

as 9-4

R-type VOC records

defined 11-15

Ssam UNIX utility 11-4

sar UNIX command 17-23

SAVEDLISTS file

dictionary for 10-7

savedlists file

dictionary for 10-8

SAVEDLISTS subdirectory 10-6

savedlists subdirectory 10-7

sbcs (shared basic code server)

daemon

creating shared memory

structure 5-5, 5-13

described 4-5

global cataloging 19-7


logging ipc facilities used 18-7

memory segment for 8-5

message queue for 6-5


sbcsprogs command

described 19-16

troubleshooting UniData

problems with 21-6

sbcs.log file 4-9


startup 9-4

SBCS_SHM_SIZ parameter 5-13

SBCS_SHM_SIZE parameter 4-6,

19-7

sbsc.errlog file 4-9

scales, communicating with 7-8

schemas, creating 8-13

screen definitions

for UEntry 10-7

_SCREEN_ file


account 10-7

scripts

startup 11-7

search permissions, directory 2-4

SECURE setting as system

default 11-22

security

checklist 8-12

customizing default

permissions 11-8

login and group 11-4

mechanism for 2-3

remote item 11-15

SETFILE command and 11-17

startup script 11-7

UniQuery 11-22

UNIX group 11-5

segment headers 5-7

segments of shared memory

attaching 4-6

described 5-4

divided into global pages 5-5

self-created 5-13

select lists

storing 4-7, 10-6

selecting

block size for dynamic file 12-15

minimum modulo for dynamic

file 12-14

split/merge type 12-8

semaphore

described 6-6


locks



clearing 13-9


setting 13-9

tracking 4-5

undo structures 6-6

semmni kernel parameter 6-6

semmnu kernel parameter 6-6

SEND

using GET and SEND 16-11

sentences

reference for 10-7

separate logins 11-5

serial devices, UNIX 7-8

set group ID (SGID) 2-6

set user ID (SUID) 2-6

SETFILE command

creating VOC entries with 8-14

customizing security 11-17

setting a VOC pointer with 3-7

setting VOC pointers 2-10

summarized 12-27

SETLINE command

defining peripheral with 8-10

summarized 16-10

SETOSPRINTER command

descrobed 15-7


summarized 15-9

SETPTR command


described 15-13

determining spooler selection

with 7-7

displaying default spooler

command with 15-20

modes 15-14


summarized 15-9

SETTAPE command


defining tape unit with 10-9, 16-7

described 16-6

summarized 16-4

setting

access mode on a file or

directory 2-6

configuration parameter 8-6

default file permissions 2-8

environment variable

PATH 8-11

path name 3-8

UDTBIN 8-11

UDTHOME 8-11

file and record locks 13-7

file pointer in UniData 2-10, 3-6

lock on record/file 13-6

permission for


TMP environment variable 3-22

UniData configuration

parameter 17-9

UNIX kernel parameter 8-5

UNIX symbolic link 3-9

SET.DEC command


SET.MONEY command


SET.THOUS command


SET.WIDEZERO command


SGID (set group ID) 2-6

shared basic code server (sbcs)

daemon 4-5

shared locks 13-6

shared memory

CI table 5-7

creating CTL segment 5-6

error messages 17-25

loading globally cataloged

program into 4-5


14

releasing 5-5

sbcs (shared basic code server)

daemon and 5-13

segment

attaching 4-6


self-created segment 5-13

structure 4-6, 5-7

table 4-6

troubleshooting 17-25

tuning 17-19, 17-21, 17-22

UniData and 5-5

UNIX system and 5-4

shared memory manager

See smm (shared memory

manager) daemon

shared memory structures

assigning 5-9

shmconf command

control table (CTL) and 17-11

described 17-9

shmmax UNIX kernel parameter 5-

4, 5-14

shmmni UNIX kernel parameter 5-

4, 5-7, 5-14

shmseg UNIX kernel parameter 5-4

SHM_FREEPCT parameter 5-11

SHM_GNPAGES parameter 5-8, 5-

11

SHM_GNTBLS parameter 5-7, 5-8,

5-14, 17-18

SHM_GPAGESZ parameter 5-11

SHM_LCINENTS parameter 5-8

SHM_LMINENTS parameter 5-14

SHM_LMINRNTS parameter 5-8

SHM_LPAGESZ parameter 5-11

SHM_LPINENTS parameter 5-8

SHM_MAX_SIZE parameter 19-7

SHM_NFREES parameter 5-11

showud command

checking status of daemons

after crash 21-4

if slow response time 21-6

described 9-11

listing UniData processes with 9-

10

monitoring UniData daemons

with 4-9

proceeding if daemons not

running 18-8

shutdown operations

abnormal 9-14

normal 9-4

sm daemon 9-4

smit UNIX utility 11-4

smm (shared memory manager)

daemon

creating CTL segment 5-8


segments 5-9


structure 5-5

described 4-6



error messages 17-25


structure 18-7


managing size of segment 5-9

message queue for 6-5



unable to create CTL segment 21-

5

smm.errlog file 4-9

smm.log file


startup 9-4

showud command and 4-9

sms command

described 17-16

output from 17-18

sm.log file 9-4

source code, UniBasic 10-6

splitting

groups in dynamic file 12-7

splitting threshold 12-7

SPLIT.LOAD factor 12-7

split/merge types

changing for dynamic file 12-28

KEYDATA 12-8

KEYONLY 12-8

selecting 12-8

SPLIT_LOAD parameter 12-8

spooler configuration file 7-7

spooler, UNIX 7-7

SP.ASSIGN command


summarized 15-9

SP.CLOSE command

summarized 15-9

SP.EDIT command


overriding file location and 3-21

summarized 15-9


SP.KILL command

summarized 15-9

SP.OPEN command

summarized 15-9

SP.STATUS command

summarized 15-10

starting

UniData 9-5

startud command

abnormal results 21-5

after system crash 21-4

expected response to 9-5

for normal startup 9-4


startup operations 9-4

startup scripts 11-7

startup, automatic 9-6

static files

converting to dynamic 8-13

described 3-11, 12-5

index file and index log file for 3-

20

repairing corruption in 12-48


sticky bit 2-5, 2-6

stopping

UniData

emergency shutdown 9-15

normal shutdown 9-6

user process 14-8

stopud command

control table (CTL) and 5-6

for emergency shutdown 9-10

-f option with 9-15

for normal shutdown 9-4, 9-6

stopudt command

described 9-11


removing process ID with 9-12

summarized 9-10, 14-8

storing

expression buffer 4-7

intermediate results 5-5

menu definition 10-7

modulo table for dynamic file 5-5

output from background

process 10-7

print file in _HOLD_

subdirectory 10-7

query record 4-7

select list 4-7, 10-6

temporary information for

BY.EXP sort 10-7

UEntry screen definition 10-7

UniBasic program 10-6

UniBasic source and object

code 10-6

UniData SQL view

specification 10-7

UReport definition 10-7

strip UNIX command 20-14, 20-30

SUID (set user ID) 2-6

SUPERCLEAR.LOCKS command

clearing semaphore lock with 13-

22

described 13-18


SUPERRELEASE command

described 13-20


releasing record lock with 13-21

superuser

See root

swap UNIX command 17-23

swapinfo UNIX command 17-23

symbolic links

backup procedure and 3-14, 8-14

creating 12-17

inconsistencies with prefix

table 12-29

setting 3-9

synchronizing

archive and backup files 9-8

system buffer

memory requirements and 8-5

Recoverable File System (RFS)

and 5-5

system performance

file overflow and 12-5

system resources, clearing 9-10

systest command

described 17-12

systest parameter 17-14

Ttape device files 7-6

tape devices, defining for

UniData 8-10

tape drives, communicating

with 7-4

tape use procedure 16-7

tar UNIX utility 10-9



temporary disk storage 3-21

TERM command


termcap file 7-5

terminal emulation 7-5

terminals

communicating with 7-4

terminated process cleanup

recovering semaphore for 6-6

role of cleanupd daemon in 4-7

role of lcp daemon in 4-5

role of sbcs daemon in 4-6

role of smm daemon in 4-7

terminfo database 7-5

testing

makeudt and 20-5, 20-19

text editors

creating part table with 12-10

hashed file and 3-11

threshold, splitting 12-7

TIMEOUT command

described 14-9

TMP configuration parameter 3-22

/tmp directory 8-4

TMP environment variable 3-21

TMP parameter 3-22

tmp space 3-21

touch UNIX command 2-9

troubleshooting

error messages 17-26, 21-7

makeudt 20-5

memory 17-3, 17-25

printer 15-11

response problem 21-6

UniData crash 21-4

tuning

memory 17-19, 17-21, 17-22

UniData performance 22-3

T.ATT command

attaching tape device with 16-7


obtaining exclusive use of tape

unit with 10-9


summarized 16-4

T.DET command

releasing tape device with 16-9


summarized 16-4

T.DUMP command


reading from or writing to tape

device 16-8

T.STATUS command

listing defined tape units with 16-

8

summarized 16-4

Uudapi_slave executable 20-11

udipcrm command

described 9-14


removing ipc structure with 18-9

removing message queue

with 18-4

summarized 9-10

udstat command

checking activity of processes

with 14-8

summarized 14-6

udt daemon

error log for 4-9

udt executables

defined 20-4

rebuilding 20-11

udt user processes 2-11, 4-5

$UDTBIN directory


in PATH 1-3

UDTBIN environment variable 1-3,

8-11, 9-4

$UDTBIN/product.info file


$UDTBIN/us_admin file


$UDTBIN/us_update_db file 11-8

udtconfig file 12-8

changing TMP parameter in 3-21

location of 8-6

reading when UniData started 5-

5

UDTHOME environment variable

modifying 19-19, 20-17

setting 1-3, 8-11, 9-4

$UDTHOME/demo directory


$UDTHOME/objcall directory


$UDTHOME/objcall/demo

directory


$UDTHOME/parttbl file

creating 12-10


$UDTHOME/sys directory


$UDTHOME/sys/HELP.FILE file


$UDTHOME/sys/udtpath file


$UDTHOME/work directory


udtmon utililty

described 22-15

udtmon utility

display options 22-16

menu 22-17

monitoring slow response time

with 21-6

UDTSPOOL.CONFIG file 15-5

udt.errlog file 4-9

UDT.OPTIONS

setting in login paragraph 11-18

UDT.OPTIONS 19

customizing UniData

environment with 11-13

UDT.OPTIONS 20

effect on root access 11-20

UDT.OPTIONS command


UEntry screen definitions

storing 10-7

uid

See user ID (uid)

umask UNIX command 2-8

UniBasic

application overview 22-29

BP file and 19-4

cataloging programs 19-3

coding tips for performance 22-8

compiled programs 19-4

debugging 16-3, 16-13

locks, tracking 4-5

profiling 22-11



program

shared memory structure for 5-

5

stored in BP file 10-7

storing code in BP

subdirectory 10-6

storing in CTLG

subdirectory 10-6

setting lock on file or record 13-6

source code 19-4

variable

buffering 5-5

UniData

account

backing up 10-9

clearing space in 10-11

creating 10-5

deleting 10-10

described 10-4

files in 10-7

listing contents of 10-5

restoring 10-9

clearing process 9-10

configuration file 12-8

customizing default

permissions 11-8

default permissions 2-10

master VOC (vocabulary) file 11-

13

pausing 9-7

starting 9-5

stopping 9-6

system resources, clearing 9-10

UNIX spooler and 7-7, 15-3

UNIX tape device 16-3

UniData accounts

backing up 8-14

locating 8-4

UniData configuration parameters

complete list of A-1

GRP_FREE_BLK 12-20

KEYDATA_MERGE_LOAD 12-8

KEYDATA_SPLIT_LOAD 12-8

MAX_FLENGTH 12-9, 12-12, 12-

15

MAX_OBJ_SIZE 5-13

NUSERS 5-8

PART_TBL 12-10

SBCS_SHM_SIZE 4-6, 5-13, 19-7


SHM_FREEPCT 5-11

SHM_GNPAGES 5-8, 5-11

SHM_GNTBLS 5-7, 5-8, 5-14, 17-

18

SHM_GPAGESZ 5-11

SHM_LCINENTS 5-8

SHM_LMINENTS 5-8, 5-14

SHM_LPAGESZ 5-11

SHM_LPINENTS 5-8

SHM_MAX_SIZE 19-7

SHM_NFREES 5-11

systest 17-14

TMP 3-22

UniData files

creating 3-6

UniData pointers, setting 3-6

UniData security

customizing VOC file 11-12

recommended UNIX

permissions 11-10

remote items 11-15

SETFILE command 11-17

UDT.OPTIONS 19 and 11-13

UDT.OPTIONS 20 and 11-20

UNIX groups 14-5

UniData SQL

permissions 11-21

storing view specifications 10-7

UniQuery

field-level security 11-22

UNIX access modes 2-6

UNIX accounts

compared to UniData account 8-

10

creating 8-11, 11-4

UNIX devices 7-4

UNIX directories, UniData’s use

of 3-4

UNIX files, UniData’s use of 3-4

UNIX kernel parameters

controlling use of semaphore 6-6

msgmax 6-4

msgmnb 6-4

msgmni 6-4

msgseg 6-4

relationship to UniData 5-14

resetting 8-5

semmni 6-6

semmnu 6-6

shared memory 5-4

shmmax 5-14

shmmni 5-7, 5-14

systest 17-16

UNIX links

creating 12-13

distinguished from VOC

pointer 3-6

setting 3-9

UniData’s use of 3-4

UNIX login 11-4

UNIX permissions

customizing 2-10

execute 2-4

file 2-4

read 2-4

sticky bit 2-5

write 2-4

UNIX security

login and group 11-4

mechanisms for 2-3

startup script 11-7

UNIX serial devices 7-8

UNIX user groups 11-5

UNIX users, adding 11-4

unloading

contents of damaged group 12-29

UNLOCK command

summarized 13-9

UNSETLINE command

summarized 16-10

updatevoc command


UPDATE.INDEX command

applying updates from index

log 3-19



uptime UNIX command 21-6, 22-5

UReport definitions

_REPORT_ subdirectory 10-7

user groups, UNIX 11-5

user ID (uid)

displaying 11-6

in group record 11-4

user processes (udt) 2-11, 4-5

USERNAME parameter of




users

adding 8-11

clearing 9-10, 9-12

file permissions for 2-4

UNIX, adding 11-4

/usr/ud41/include directory


/usr/ud41/ods directory


us_admin file


us_update_db file 11-8

U-type locks 13-6

U_IGNLGN_LGTO option

effect on root access 11-20

U_VERIFY_VKEY option

customizing UniData

environment with 11-13

Vvalidating

DEST and FORM 15-17

variables, environment 1-3

VCATALOG command


verify2 command

described 12-40

error messages from 12-56

examining data file with 21-4

output from 12-42

purpose of 12-34

summarized 12-30

verifying

UniBasic program version 19-10

view specifications

for UniData SQL 10-7

virtual memory pool 5-6

vmstat UNIX command 17-23, 21-

6, 22-5

VOC (vocabulary) file


account 10-4, 10-7

creating 10-5

customizing 2-10, 10-5, 11-12

dictionary for 10-7

environment variables 3-8

F-type record 3-9

limiting access to commands 8-12

master 11-13

role in UniData account 3-4

R-type record 11-15

setting pointer to data file 3-6

UniData account and 8-10

VVTERMCAP environment

variable 7-5

vvtermcap file 7-5

__V__VIEW file


account 10-7

WWHAT command


WHERE command

displaying currrent account

with 10-11

WHO command

summarized 14-6

who UNIX command 13-21

WORKPATH environment

variable 20-17

WRITE command

summarized 13-8

write permissions 2-4

WRITEU command

summarized 13-8

WRITEV command

summarized 13-8

WRITEVU command

summarized 13-8

Xxlog001 file 3-20

Symbols$UDTBIN directory


in PATH 1-3

$UDTBIN/product.info file


$UDTBIN/us_admin file


$UDTBIN/us_update_db file 11-8

$UDTHOME/demo directory


$UDTHOME/objcall directory


$UDTHOME/objcall/demo

directory


$UDTHOME/objcall/include

directory


$UDTHOME/parttbl file

creating 12-10


$UDTHOME/sys directory


$UDTHOME/sys/HELP.FILE file


$UDTHOME/sys/udtpath file


$UDTHOME/work directory



.login file 3-22, 11-7, B-1




/etc/security/passwd file 11-4

/etc/shadow file 11-4

/tmp directory 8-4

/usr/ud41/include directory


/usr/ud41/ods directory


@ID parameter of


_HOLD_ file

dictionary for 10-7

_HOLD_ subdirectory

clearing 10-11

defined 10-7

_MAP_ file 19-9

_PH_ file

dictionary for 10-7

_PH_ subdirectory

clearing 10-11

defined 10-7

_REPORT_ file




account 10-7

dictionary for 10-8

_SCREEN_ file


account 10-7

dictionary for 10-8

__V__VIEW file


account 10-7

__V__VIEWS file

dictionary for 10-8

Index 17

@

/productinfo/alldoc/UNIDATA60/ADMINUNIX/

ADMINUNIXIX.fm

O QCA B D E F G H I J K L M N P R S T U V W X Y Z


unidata - prismhr os/400, ibm informix®, ... chapter 22 performance monitoring and tuning ... tips...

Documents