266
Rocket UniData Administering UniData on UNIX Version 8.1.2 April 2016 UDT-812-ADMU-1
Rocket UniData
Administering UniData on UNIX
Version 8.1.2
April 2016UDT-812-ADMU-1
2
NoticesEdition
Publication date: April 2016Book number: UDT-812-ADMU-1Product version: Version 8.1.2
Copyright© Rocket Software, Inc. or its affiliates 1985-2016. All Rights Reserved.
Trademarks
Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks goto: www.rocketsoftware.com/about/legal. All other products or services mentioned in this documentmay be covered by the trademarks, service marks, or product names of their respective owners.
Examples
This information might contain examples of data and reports. The examples include the names ofindividuals, companies, brands, and products. All of these names are fictitious and any similarity tothe names and addresses used by an actual business enterprise is entirely coincidental.
License agreement
This software and the associated documentation are proprietary and confidential to Rocket Software,Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance withthe terms of such license.
Note: This product may contain encryption technology. Many countries prohibit or restrict theuse, import, or export of encryption technologies, and current use, import, and export regulationsshould be followed when exporting this product.
3
Corporate informationRocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,and compliance; database servers and tools; business information and analytics; and applicationdevelopment, integration, and modernization.
Website: www.rocketsoftware.com
Rocket Global Headquarters77 4th Avenue, Suite 100Waltham, MA 02451-1468USA
To contact Rocket Software by telephone for any reason, including obtaining pre-sales informationand technical support, use one of the following telephone numbers.
Country Toll-free telephone number
United States 1-855-577-4323Australia 1-800-823-405Belgium 0800-266-65Canada 1-855-577-4323China 400-120-9242France 08-05-08-05-62Germany 0800-180-0882Italy 800-878-295Japan 0800-170-5464Netherlands 0-800-022-2961New Zealand 0800-003210South Africa 0-800-980-818United Kingdom 0800-520-0439
Contacting Technical Support
The Rocket Community is the primary method of obtaining support. If you have current support andmaintenance agreements with Rocket Software, you can access the Rocket Community and reporta problem, download an update, or read answers to FAQs. To log in to the Rocket Community or torequest a Rocket Community account, go to www.rocketsoftware.com/support.
In addition to using the Rocket Community to obtain support, you can use one of the telephonenumbers that are listed above or send an email to [email protected].
4
Contents
Notices................................................................................................................................................................................... 2
Corporate information......................................................................................................................................................... 3
Chapter 1: Introduction......................................................................................................................................................12Audience.................................................................................................................................................................. 12IPv6 support............................................................................................................................................................ 12
Chapter 2: UniData and UNIX security.............................................................................................................................. 13UNIX file permissions..............................................................................................................................................13Additional UNIX access modes.............................................................................................................................. 14UNIX umask............................................................................................................................................................. 15UniData default permissions................................................................................................................................. 16UniData processes and root.................................................................................................................................. 17
Chapter 3: UniData and the UNIX file system...................................................................................................................18UniData directories and files................................................................................................................................. 18Files, pointers, and links........................................................................................................................................ 19
Creating files............................................................................................................................................... 19Setting a UniData pointer.......................................................................................................................... 19Setting an Environment Variable.............................................................................................................. 20Setting a UNIX link......................................................................................................................................21
UniData hashed files.............................................................................................................................................. 22Static files....................................................................................................................................................22
Points to remember about static files.......................................................................................... 23Dynamic files...............................................................................................................................................23
The dat001 file................................................................................................................................ 23The over001 file.............................................................................................................................. 24Points to remember about dynamic files..................................................................................... 24
Sequentially hashed files........................................................................................................................... 24The dat001 file................................................................................................................................ 24The over001 file.............................................................................................................................. 24The gmekey file...............................................................................................................................25
DIR-type files............................................................................................................................................... 26Multilevel files............................................................................................................................................. 26
Points to remember about multilevel files...................................................................................27Multilevel directory files.............................................................................................................................27
Points to remember about multilevel directory files...................................................................28Index files and index log files.................................................................................................................... 28
Index-related files for a static hashed file.................................................................................... 28Index-related files for a dynamic hashed or sequentially hashed file.........................................29
UniData and tmp space......................................................................................................................................... 29Changing TMP in the udtconfig file...........................................................................................................30Setting an environment variable...............................................................................................................30
Chapter 4: UniData and servicesdaemons........................................................................................................................31What is a daemonservice?..................................................................................................................................... 31Principal UniData daemonsservices......................................................................................................................31
Shared basic code server (sbcs)................................................................................................................ 31Shared memory manager (smm).............................................................................................................. 32Clean up (cleanupd)................................................................................................................................... 33UniRPC service (unirpcd)........................................................................................................................... 33sync daemon...............................................................................................................................................33
Monitoring UniData daemons................................................................................................................................33showud command...................................................................................................................................... 33
Contents
5
Log files....................................................................................................................................................... 34The udt.errlog file........................................................................................................................... 34
Chapter 5: UniData and memory.......................................................................................................................................36Windows platforms UNIX and shared memory.................................................................................................... 36UniData and shared memory.................................................................................................................................36
smm and shared memory..........................................................................................................................37Control table list (CTL)................................................................................................................... 37Creating and assigning memory structures..................................................................................40Displaying parameter settings.......................................................................................................41
sbcs and shared memory...........................................................................................................................42Self-created segments................................................................................................................................42UniData and the UNIX kernel.....................................................................................................................43
Chapter 6: UniData and UNIX ipc facilities....................................................................................................................... 44Message queues...................................................................................................................................................... 44
UniData and message queues................................................................................................................... 44Semaphores.............................................................................................................................................................45
Chapter 7: UniData and UNIX devices...............................................................................................................................46UNIX devices: overview.......................................................................................................................................... 46UniData and terminal devices............................................................................................................................... 46UniData and tape devices......................................................................................................................................46UniData and printers.............................................................................................................................................. 47UniData and serial devices.................................................................................................................................... 47
Chapter 8: Configuring your UniData system................................................................................................................... 48Configuration procedure........................................................................................................................................ 48
1. Identify disk requirements.....................................................................................................................482. Identify memory requirements..............................................................................................................483. Verify version compatibilities................................................................................................................ 494. Check/reset UNIX kernelsystem-level parameters............................................................................... 495. Check/reset UniData configuration parameters...................................................................................506. Define peripherals within UniData........................................................................................................ 537. Create UniData accounts....................................................................................................................... 538. Add UNIXWindows users........................................................................................................................ 539. Set environment variables.....................................................................................................................54
Setting UDTHOME and UDTBIN..................................................................................................... 54Setting PATH................................................................................................................................... 55Setting additional environment variables.................................................................................... 55
10. Review UniData security...................................................................................................................... 5611. Convert data files................................................................................................................................. 5612. Perform makeudt................................................................................................................................. 5613. 12. Review backup procedures............................................................................................................57
Chapter 9: Starting, stopping, and pausing UniData....................................................................................................... 58Normal operation................................................................................................................................................... 58
UniData log files..........................................................................................................................................58Start UniData with startud.........................................................................................................................60Stop UniData with stopud......................................................................................................................... 61
Pausing UniData..................................................................................................................................................... 61The dbpause command............................................................................................................................. 61The dbpause_status command................................................................................................................. 63Resuming processing..................................................................................................................................63
Additional commands............................................................................................................................................ 64Listing processes with showud..................................................................................................................64Stopping a user process with stopudt...................................................................................................... 65Stopping a user process with deleteuser................................................................................................. 65Displaying ipc facilities with ipcstat..........................................................................................................66
Contents
6
Removing ipc structures with udipcrm.....................................................................................................67Stopping UniData with stopud -f...............................................................................................................67
Chapter 10: Managing UniData accounts......................................................................................................................... 69What is a UniData account?...................................................................................................................................69Creating a UniData account...................................................................................................................................69Saving and restoring accounts.............................................................................................................................. 72Deleting an account............................................................................................................................................... 73Clearing space in UniData accounts..................................................................................................................... 73
CLEAR.ACCOUNT......................................................................................................................................... 73
Chapter 11: Managing UniData security........................................................................................................................... 75Logins and groups.................................................................................................................................................. 75
Adding a UNIX user.....................................................................................................................................75Use separate logon IDs.............................................................................................................................. 76User groups................................................................................................................................................. 76Home directories........................................................................................................................................ 77Startup scripts.............................................................................................................................................77
Customizing permissions....................................................................................................................................... 77Customizing a VOC file........................................................................................................................................... 79
Customizing UniData..................................................................................................................................81Remote items.......................................................................................................................................................... 81The SETFILE command.......................................................................................................................................... 82LOGIN and LOGOUT paragraphs........................................................................................................................... 83
Creating a login paragraph for UniData ODBC connections....................................................................85Creating a login paragraph for UniObjects connections......................................................................... 86
UniData SQL privileges...........................................................................................................................................87Field-level security for UniQuery........................................................................................................................... 87
Points to remember about field-level security.........................................................................................88The QUERY.PRIVILEGE file..........................................................................................................................88
UniQuery processing...................................................................................................................... 90Turning on field-level security................................................................................................................... 90
1. Log in...........................................................................................................................................902. Create QUERY.PRIVILEGE........................................................................................................... 913. Set permissions.......................................................................................................................... 914. Edit the dictionary......................................................................................................................915. Add records to QUERY.PRIVILEGE............................................................................................. 92
Chapter 12: Managing UniData files..................................................................................................................................93UniData hashed files.............................................................................................................................................. 93Static hashed files.................................................................................................................................................. 93Dynamic hashed files............................................................................................................................................. 94
Dynamic files and overflow........................................................................................................................94Splitting and merging.....................................................................................................................95KEYONLY type................................................................................................................................. 95KEYDATA type..................................................................................................................................95Selecting a split/merge type..........................................................................................................96Dynamic files and hash type..........................................................................................................96
Dynamic files, part files, and part tables.................................................................................................. 96Location of part tables...................................................................................................................96Components of a part table.......................................................................................................... 97Part table tips and constraints......................................................................................................97
When dynamic files are created................................................................................................................ 98Estimating the size of the file........................................................................................................ 98Locating the dynamic file directory.............................................................................................. 98Locating the part files.................................................................................................................... 99
Tips and constraints for creating a dynamic file....................................................................................100Choosing the initial modulo........................................................................................................ 100
Contents
7
Choosing the block size............................................................................................................... 101When dynamic files expand..................................................................................................................... 101
Determining whether a new part file Is needed......................................................................... 101Locating space for a new part file...............................................................................................102
How part files are stored......................................................................................................................... 102Management tools for dynamic files.......................................................................................................103
auditor........................................................................................................................................... 103fixtbl............................................................................................................................................... 104mvpart........................................................................................................................................... 104
Dynamic files and disk space.................................................................................................................. 104Sequentially hashed files......................................................................................................................... 109
The dat001 file.............................................................................................................................. 109The over001 file............................................................................................................................ 110The gmekey file.............................................................................................................................110
File-handling commands......................................................................................................................................111File corruption.......................................................................................................................................................113
What causes file corruption?................................................................................................................... 113Preventing file corruption........................................................................................................................ 113
UniData detection tools....................................................................................................................................... 114guide.......................................................................................................................................................... 114guide_ndx.................................................................................................................................................. 118
UniData recovery tools.........................................................................................................................................119dumpgroup................................................................................................................................................120fixgroup......................................................................................................................................................121fixfile...........................................................................................................................................................122
How fixfile works with static files................................................................................................123How fixfile works with dynamic files...........................................................................................124
Detection and repair examples........................................................................................................................... 124How to use guide..................................................................................................................................................125
1. Monitor file integrity with guide..........................................................................................................1252. Check error output (GUIDE_ERRORS.LIS)........................................................................................... 1253. Repair damaged files........................................................................................................................... 1264. Back up the repaired files....................................................................................................................1265. Continue processing.............................................................................................................................126
Error messages......................................................................................................................................................126File access messages................................................................................................................................127Block usage messages..............................................................................................................................127Group header messages...........................................................................................................................127Header key messages...............................................................................................................................127Other header messages........................................................................................................................... 128Free block messages................................................................................................................................ 129Long record messages..............................................................................................................................129
Chapter 13: Managing UniData locks.............................................................................................................................. 130The global lock manager..................................................................................................................................... 130
How GLM works........................................................................................................................................ 130GLM udtconfig parameters.......................................................................................................... 130N_GLM_GLOBAL_BUCKET............................................................................................................ 130N_GLM_SELF_BUCKET..................................................................................................................130GLM_MEM_SEGSZ......................................................................................................................... 130
Locking in UniBasic.............................................................................................................................................. 131How locks work........................................................................................................................................ 131
Exclusive locks (U type)................................................................................................................131Shared locks (L type)....................................................................................................................131Writing and deleting..................................................................................................................... 131
Locking commands...................................................................................................................................131Resource locks...................................................................................................................................................... 132
Contents
8
Listing locks...........................................................................................................................................................133LIST.READU................................................................................................................................................133
LIST.READU display...................................................................................................................... 134LIST.LOCKS................................................................................................................................................ 135LIST.QUEUE............................................................................................................................................... 135
LIST.QUEUE display...................................................................................................................... 137Commands for clearing locks.............................................................................................................................. 139
SUPERCLEAR.LOCKS Command.............................................................................................................. 139SUPERRELEASE command................................................................................................................................... 140Procedure for clearing locks................................................................................................................................141
1. Check for unneeded locks................................................................................................................... 1412. Note information for clearing..............................................................................................................1413. Release record locks............................................................................................................................ 1414. Clear semaphore locks.........................................................................................................................1415. Check for message queue congestion................................................................................................ 142
Chapter 14: Managing UniData users..............................................................................................................................143Adding users..........................................................................................................................................................143
Every user needs a login ID..................................................................................................................... 143Create logon IDs at the UNIX level.......................................................................................................... 143Assign users to groups............................................................................................................................. 144
Monitoring user processes................................................................................................................................... 144UniData commands.................................................................................................................................. 144
Removing user processes.....................................................................................................................................145Using TIMEOUT......................................................................................................................................... 146
Chapter 15: Managing printers in UniData..................................................................................................................... 147UniData and UNIX spoolers................................................................................................................................. 147
Configuring the spooler............................................................................................................................147Enabling and disabling printers.................................................................................................. 149
SETOSPRINTER Command.......................................................................................................................150Spooling from UniData.............................................................................................................................150
UniData printing commands................................................................................................................................150Configuring and troubleshooting a printer.........................................................................................................151
Physical connection..................................................................................................................................151Troubleshooting............................................................................................................................152
Spooler definition..................................................................................................................................... 152Definition in UniData................................................................................................................................ 152
SETPTR.................................................................................................................................................................. 153Environment variables......................................................................................................................................... 154
Disabling printer validation..................................................................................................................... 154Defining an alternate search path...........................................................................................................155
Examples............................................................................................................................................................... 155Redefining the default UniData print unit.............................................................................................. 155Submitting concurrent print jobs............................................................................................................155Printing to a UNIX device.........................................................................................................................156Passing spooler options to UNIX............................................................................................................. 156
Decoding a UniData print statement.................................................................................................................. 1571. Determine your default spooler command........................................................................................ 1572. Create the C program...........................................................................................................................1583. Compile the C program........................................................................................................................1584. Redefine your path...............................................................................................................................1585. Test UniData printing........................................................................................................................... 1596. Reset your execution path...................................................................................................................159
Chapter 16: Accessing UNIX devices................................................................................................................................160UniData tape handling commands..................................................................................................................... 160SETTAPE.................................................................................................................................................................161
Contents
9
Steps for tape device use.....................................................................................................................................1611. Define tape units.................................................................................................................................. 1612. Attach a tape device.............................................................................................................................1613. Read from or write to the tape device................................................................................................1624. Release the tape device....................................................................................................................... 163
UniData LINE commands..................................................................................................................................... 163Communicating with GET and SEND.................................................................................................................. 164
1. Define a tty device in UniData.............................................................................................................1642. Attach the line to your process........................................................................................................... 1653. Access the line...................................................................................................................................... 1654. Release the line.................................................................................................................................... 165
Dual-terminal debugging in UniBasic................................................................................................................. 165Setting up dual-terminal debugging................................................................................................................... 166
1. Log on to two terminals (or Windows)............................................................................................... 1662. Set a pointer to the display terminal..................................................................................................1663. Connect to the display terminal..........................................................................................................1664. Conduct the debugging session.......................................................................................................... 1665. Detach from the display terminal....................................................................................................... 1676. Release the display terminal............................................................................................................... 167
Chapter 17: Managing memory....................................................................................................................................... 168UniData monitoring/configuring tools................................................................................................................ 168
udtconf main display................................................................................................................................168Calculating udtconfig parameters...........................................................................................................169Checking configuration parameters........................................................................................................169Saving configuration parameters............................................................................................................ 170Recalculating the size of the CTL............................................................................................................ 170Viewing current and suggested settings................................................................................................. 170Exiting udtconf..........................................................................................................................................170
Setting shared memory parameters................................................................................................................... 171shmconf: main display............................................................................................................................. 171shmconf: viewing current and suggested settings.................................................................................172shmconf: Recalculating the size of CTL.................................................................................................. 172shmconf: Recalculating other parameters............................................................................................. 173Shared memory and the Recoverable File System................................................................................ 173Analyzing UniData configuration parameters........................................................................................ 173Checking and changing UniData configuration parameters................................................................. 174Checking kernel parameters....................................................................................................................175sms............................................................................................................................................................. 176Learning about global pages................................................................................................................... 178Learning about local control tables........................................................................................................ 179
UNIX monitoring tools..........................................................................................................................................180UniData configuration parameters......................................................................................................................180
UNIX kernel parameters........................................................................................................................... 181UniData error messages for smm........................................................................................................................181
Chapter 18: Managing ipc facilities................................................................................................................................. 184Message queues, shared memory, and semaphores......................................................................................... 184
UniData log files........................................................................................................................................186Removing ipc structures...................................................................................................................................... 186
1. Check for remaining facilities.............................................................................................................. 1872. Stop UniData.........................................................................................................................................1873. Decide how to proceed........................................................................................................................ 1874. Remove ipc facilities with udipcrm.....................................................................................................1875. Remove ipc facilities with UNIX ipcrm................................................................................................ 1886. Restart UniData.................................................................................................................................... 189
Chapter 19: Managing cataloged programs................................................................................................................... 190
Contents
10
UniBasic source and compiled programs........................................................................................................... 190UniBasic compiled programs...................................................................................................................190
Cataloging UniBasic programs............................................................................................................................ 190Direct cataloging.......................................................................................................................................191Local cataloging........................................................................................................................................191Global cataloging......................................................................................................................................191
Managing global catalogs.................................................................................................................................... 192Contents of a global catalog................................................................................................................... 193Verifying a program version.....................................................................................................................194
Activating newly cataloged programs and subroutines............................................................ 195Main programs.............................................................................................................................. 195Subroutines................................................................................................................................... 196
Listing programs in use........................................................................................................................................198Creating an alternate global catalog space........................................................................................................199
Files and directories created by newhome.............................................................................................199Procedure for creating an alternate global catalog space.................................................................... 201
1. Change to the new account directory.....................................................................................2012. Execute newhome.................................................................................................................... 2023. Modify VOC entries for users....................................................................................................2024. Modify UDTHOME for users......................................................................................................2035. Copy application programs..................................................................................................... 2036. Use the alternate global catalog space.................................................................................. 203
Procedure for using an alternate global catalog space.........................................................................204
Chapter 20: CallBasic, CALLC, and makeudt.................................................................................................................. 205Linking C routines into UniData.......................................................................................................................... 205
Overview.................................................................................................................................................... 205Requirements............................................................................................................................................ 205Rebuilding for troubleshooting............................................................................................................... 206
Rebuilding for application testing...............................................................................................206makeudt.................................................................................................................................................................206
File examples............................................................................................................................................ 207base.mk example..........................................................................................................................207cfuncdef example......................................................................................................................... 209
Creating cfuncdef_user............................................................................................................................ 209Steps for linking in C functions........................................................................................................................... 210Steps for setting up a development environment............................................................................................. 213Accessing UniData from a C program................................................................................................................. 215
Requirements............................................................................................................................................ 215How CallBasic works................................................................................................................................ 216
C program example.............................................................................................................................................. 216Header files............................................................................................................................................... 218Error handler............................................................................................................................................. 218Initializing CallBasic..................................................................................................................................218Calling a UniBasic subroutine..................................................................................................................218Freeing resources......................................................................................................................................218Ending CallBasic....................................................................................................................................... 218
UniBasic subroutine example.............................................................................................................................. 219Steps for CallBasic................................................................................................................................................ 219
Chapter 21: General troubleshooting..............................................................................................................................223Crashes and restart problems............................................................................................................................. 223
UniData crashes........................................................................................................................................ 223UniData cannot start................................................................................................................................ 223
Response problems in UniData........................................................................................................................... 224UniData consistently slow........................................................................................................................224UniData is hung........................................................................................................................................ 224
Contents
11
Error messages......................................................................................................................................................224Common error messages......................................................................................................................... 225
Syntax error...................................................................................................................................225Not a verb command................................................................................................................... 226cannot open abcdef..................................................................................................................... 226[100004]......................................................................................................................................... 226[100000]......................................................................................................................................... 226Virtual field too big.......................................................................................................................227Record is too long. Ask Unidata to extend the U_MAXEXTRA....................................................227Numra is maxed out in installshmid........................................................................................... 227
Chapter 22: Performance monitoring and tuning.......................................................................................................... 228UNIX performance considerations...................................................................................................................... 228UNIX performance monitoring.............................................................................................................................228
Tools.......................................................................................................................................................... 228Tips.............................................................................................................................................................229
uptime............................................................................................................................................229ps, vmstat......................................................................................................................................229iostat.............................................................................................................................................. 229
UniData performance factors.............................................................................................................................. 229Database design considerations..............................................................................................................229Using alternate key indexes.....................................................................................................................230Sizing static hashed files..........................................................................................................................230Sizing dynamic hashed files.....................................................................................................................230UniBasic coding tips................................................................................................................................. 230
Use modular programming..........................................................................................................231Use efficient commands...............................................................................................................231Use dynamic and dimensioned arrays appropriately................................................................ 231Use the correct READ in each situation...................................................................................... 231Manage locks carefully.................................................................................................................232
UniBasic profiling..................................................................................................................................................2321. Compile the programs with -G............................................................................................................ 2322. Run the programs with -G................................................................................................................... 2323. Review the profile output.................................................................................................................... 232
UniData performance monitoring: udtmon........................................................................................................234udtmon: UniData user statistics.............................................................................................................. 237udtmon: file I/O statistics.........................................................................................................................238udtmon: program control statistics........................................................................................................ 239udtmon: dynamic array statistics............................................................................................................240udtmon: lock statistics.............................................................................................................................241udtmon: sequential I/O statistics............................................................................................................ 242udtmon: data conversion statistics.........................................................................................................242udtmon: index statistics...........................................................................................................................243udtmon: Mglm performance....................................................................................................................245
Chapter 23: Account-based licensing..............................................................................................................................247Managing the license configuration.................................................................................................................... 247
Managing account-based licensing with listuser -a............................................................................... 248Verifying the acct_licn.def file..................................................................................................... 248Listing the acct_licn.def file.........................................................................................................248Reloading the acct_licn.def file................................................................................................... 248
Appendix A: UniData configuration parameters.............................................................................................................250
Appendix B: Environment variables for UniData............................................................................................................263
Appendix C: Configuring SSL for Telnet..........................................................................................................................266Server side configuration:.................................................................................................................................... 266
12
Chapter 1: IntroductionThe purpose of this manual is to collect, in a single book, as much information as possible aboutactivities that are needed to administer a Rocket UniData installation on UNIX.
This manual repeats some information that is presented elsewhere in the UniData documentationset. Certain command descriptions and examples have been amplified or modified in this manual toincrease their usefulness to system administrators as opposed to end users.
Note: Before you try repeating the examples in this manual, make sure that you have set theenvironment variables UDTHOME and UDTBIN, and make sure that your PATH includes udtbin.See Configuring your UniData system, on page 48 for information about setting these variables.
Many of the administrative functions you can run from the command line are available through The U2Extensible Administration Tool.
AudienceAdministering UniData on UNIX is intended for people whose responsibilities include the following:
▪ Tasks that are 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 that are performed within UniData▫ Creating and managing UniData accounts
▫ Optimizing UniData configuration
▫ Customizing security
▫ Managing files
▫ Monitoring and accessing files, peripherals, and system resources
IPv6 supportStarting at UniData 8.1.0, IPv6 support is included. IPv6 is an industry standard for the IP network. IPv6removed the IP addressing limitation of IPv4, and provides more quality of service and IP security.UniData provides dual stack support, meaning it supports IPv4 and IPv6 simultaneously.
13
Chapter 2: UniData and UNIX securityThis chapter describes UNIX security mechanisms and outlines how these mechanisms are used byUniData. It is important to understand UNIX security because UNIX file permissions form the basis ofUniData security.
UNIX file permissionsIn UNIX, each file or directory has permissions set for the owner (called user), for members of thegroup owner (called group), and for all other users except root (called other). The root user has allaccess 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 theUNIX permissions mean when applied to a file.
Permission Description
r (read) Read or copy a filew (write) Modify a filex (execute) Run a script or program
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 shownin the following table.
Permission Description
r (read) List the directory’s contentsw (write) Add or remove files from the directoryx (search) cd to the directory, or include it in a path
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 ACCOUNTis 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.
Chapter 2: UniData and UNIX security
14
To delete a file from a directory, a user needs write permission to the directory, but does not need anypermissions 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 overridethem, 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 usersfrom deleting a file unless they have write permission on that file. See Additional UNIX access modes,on page 14 for more information.
Note: The UNIX commands ls, chmod, chown, and chgrp are used for viewing and modifyingfile ownership and permissions. Refer to your host operating system documentation for detailedinformation about these commands.
Additional UNIX access modesUNIX supports three more file access modes, as shown in the following table.
Access Mode Description
t (sticky bit) Varies with UNIX version; when set on a directory, restricts delete accesson files within the directory.
s (set UID or SUID) Set on executable files. Allows a user to invoke the executable, which runswith the privileges of the owner of the file.
s (set GID or SGID) Set on executable files. Allows a user to invoke the executable, which runswith the privileges of the owner of the group.
Warning: Setting SUID or SGID on executables allows access to users they would not be grantedbased on the permissions. These access modes, if not used with caution, can compromise thesecurity of your system. Also, these access modes behave somewhat differently in different UNIXversions. Review your host operating system documentation before you set SUID or SGID.
The following screens show how to set these access modes, and what permissions look like when eachof 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%
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
UNIX umask
15
-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 fileowner 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 theowner or as root to set SUID.
UNIX umaskThe UNIX umask command sets default permissions for file creation. umask allows you to specifypermissions that apply when a file is created. To use umask, you need to know the octal values of thebasic permissions (read, write, execute), and the UNIX default permissions for files and directories. Thefollowing table shows the octal values for the permissions and for common combinations.
Permission Octal value
read 1write 2execute (or search) 4read+execute 5read+write 6write+execute 3read+write+execute 7
The UNIX default permissions for file creation are shown in the next table.
Type UNIX default permission
File rw-rw-rw- (octal: 666)Directory drwxrwxrwx (octal: 777)
The value of umask is also expressed in octal format, and its effect is shown by subtracting the valuefrom the UNIX default. For example, if you set umask to 002 and create a file, the permissions on thatfile are represented by the difference between the default (666) and umask (002), or 664. Permissionsof 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
Chapter 2: UniData and UNIX security
16
% 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, UniData sets filepermissions in most cases according to the user’s current umask. The exceptions are thedirectories for dynamic files and multilevel files and directories. Permissions for these are set to775 octal (rwxrwxr-x).
Note: For security purposes, a system administrator can set a default value of umask in any user’s.login or .profile file. However, if users have access to the UNIX prompt, they can overridethe default before they enter UniData.
Refer to your host operating system documentation for detailed information about the umaskcommand.
UniData default permissionsWhen you install UniData software on your system, the installation process sets the ownership ofthe files that are 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 thefiles it installs. For each file, the owner permissions apply to root. The group permissions apply to allmembers of the group you specify in the installation procedure. The final set of permissions applies toall other users on your system.
The following screen shows a long listing for the file /usr/ud82/include/udtconfig,illustrating the default permissions set when you install UniData.
% cd /usr/ud82/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. The root hasread and write access to the file, and all other users have read access only.
If you log on as root and create a new UniData account with the newacct command, the systemallows you to specify the owner and group for the account. The system sets the owner and groupowner accordingly.
You can customize the file permissions to meet specific needs for your system. See Managing UniDatasecurity, on page 75 for information about customizing file protections.
UniData also allows you to fine-tune your system security by customizing the VOC files in yourUniData accounts and by granting specific privileges to UniData SQL users via the UniData SQL GRANTcommand. See Managing UniData security, on page 75 for information about tuning UniDatasecurity.
Note: The ECL SETFILE command lets you set pointers in the UniData VOC file to allow files tobe shared among accounts or distributed among file systems. For each file, the permissions thatcontrol access are those permissions at the location where the file resides, which may be differentfrom those permissions in the directory that contains the VOC file.
UniData processes and root
17
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 youare 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 (calleda udt) runs under the UID of the user. Since the udt process drives all file access, users can performonly actions that are allowed by your system’s security, which consists of UNIX file permissions, thelocal VOC file, and SQL privileges.
18
Chapter 3: UniData and the UNIX file systemThis chapter describes relationships between UniData file types and UNIX file types, and outlines thestructures of various types of UniData files.
UniData directories and filesUniData uses UNIX files, directories, and links to organize its database. A UniData account is, insimplest terms, a UNIX directory that contains a VOC file, its dictionary (D_VOC), and other files thatare created by the newacct command.
The VOC file serves as the central repository for information about the account. It contains directinformation (such as commands and keywords you can use) and pointers to menus, data, dictionaryfiles, and cataloged programs. For information about the newacct command, see Managing UniDataaccounts, on page 69.
Note: The data and dictionary files that are referenced in a VOC file are not necessarily located inthe same UNIX directory as the VOC file. You can list the files that are defined for a UniData accountby listing VOC entries. It is normal for the resulting file list to differ from a UNIX or UniData listing(ls) of the files that are actually located in the directory.
In UniData, as in UNIX, a directory is treated as a type of file. The following table shows therelationships 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 files) and indexes (if any are built). Thedata, overflow, and index files are UNIX data files.
Sequentially hashed file UNIX directory that contains data files and overflow files andindexes whose records are stored in sequential order based onthe @ID. A sequentially hashed file has a fixed modulo, just like astatic hashed file.
Dictionary (DICT) file (A statichashed file)
Data file that contains attribute and record definitions for aUniData file.
Alternate key index (for staticfile)
Data file located in the same directory at the same level as the filethat is be indexed.
Alternate key index (for dynamicfile)
Data file located in the dynamic file directory along with the datafile and the overflow file.
DIR file UNIX directory. You can copy records from another file into a DIRfile with the ECL COPY command; each such record is stored as aUNIX text file.
MULTIFILE (multilevel file) UNIX directory that contains one or more UniData hashed files.One dictionary exists for the MULTIFILE, which is shared by allhashed files in the directory. You can copy records from one fileinto another file within the directory.
MULTIDIR (multilevel DIR file) UNIX directory that contains one or more subdirectories. Onedictionary exists for the MULTIDIR, which is shared by eachsubdirectory. If you copy records from another file into one of thesubdirectories, each record is stored as a UNIX text or data file.
Files, pointers, and links
19
You can define links and pointers within UniData to reference files that are located in different UNIXfile systems. When setting pointers in VOC entries, you can also define environment variables for thepaths of UniData accounts, and then use those variables.
Files, pointers, and links
Creating files
By default, the physical location of a UniData file is the UniData account directory where the file wascreated. The following screen shows the ECL CREATE.FILE command (creating a static file) and theECL LS command (displaying the account directory).
UniData Release 8.1.2 Build: (6069)© Rocket Software, Inc. 1985-2015.All rights reserved.
Current UniData home is /disk1/ud82/.Current working directory is /disk1/ud82/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 featureallows users that are working in different UniData accounts to share data files. Remember two pointsto 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, evenbackup utilities that follow symbolic links do not automatically follow VOC pointers. See Setting aUNIX link, on page 21 for more information about UNIX links.
▪ Setting a VOC pointer does not alter the physical location of the data file. Although you can accessthe file from the directory where the pointer resides, the physical location of the file and its indexesremains unchanged.
The following screen shows the ECL SETFILE command (setting a VOC pointer):
:SETFILE /usr/ud82/demo/INVENTORY INVENTORYEstablish the file pointerTree name /usr/ud82/demo/INVENTORYVoc name INVENTORYDictionary name /usr/ud82/demo/D_INVENTORYOk to establish pointer(Y/N) = YSETFILE completed.
Chapter 3: UniData and the UNIX file system
20
:LIST INVENTORY WITH FEATURES LIKE "Portable..." FEATURESLIST INVENTORY WITH FEATURES LIKE "Portable..." FEATURES 18:56:11 May 21 2011 1INVENTORY. Features......................39300 Portable, Sports Model12006 Portable Color Ink Jet39400 Portable Model39000 Portable Sports Model38000 Portable, 5-disk52070 Portable Color, 3 ppm52060 Portable Ink Jet, 5 ppm10008 Portable, B/W, 6 ppm30000 Portable Clock Radio10009 Portable Color, 6 ppm39100 Portable, Basic Functions11 records listed:LSBP D_SAVEDLISTS D__REPORT _SAVEDLISTS _REPORT_CTLG D_STATIC.TST D__SCREEN sandSTATIC.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 fileremains in /usr/ud82/demo, and the INVENTORY file is not included in the LS display.
Note: For more information about creating and listing UniData files, see the UniData CommandsReference manual and Using UniData.
Setting an Environment Variable
You can replace the “path” portion of a file reference in a VOC entry with a UNIX environment variable.This environment variable makes it easy to move a file or files when necessary without having tochange each associated VOC entry. The following screen shows how to set an environment variable forthe UniData demo account:
% setenv DEMO /usr/ud82/demo% printenv DEMO/usr/ud82/demo% cd $DEMO% pwd% /usr/ud82/demo%
Notice that you can use the environment variable to access the demo database.
Note: The above example shows the C shell syntax for setting the environment variable. If you areusing the Bourne or Korn shell, use the following syntax:
DEMO=/usr/ud82/demo; export DEMO
The following screen shows a VOC entry that uses the environment variable to identify a file in thedemo database:
:WHERE/users/testacct:!printenv DEMO
Setting a UNIX link
21
/usr/ud82/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 youmove the entire demo database, you can redefine the environment variable to the new path. Userscan continue to access the files.
Note: If you use an environment variable in a VOC entry, precede the environment variable withthe @ character as shown in the above example. The @ character directs UniData to handle thepath reference with the environment variable.
Warning: You can use environment variables only in VOC entries for files. You cannot use them inother types of entries that include file paths (for instance, catalog pointer items).
Setting a UNIX link
You can create a pointer to a file in another account directory by setting a symbolic link at the UNIXlevel. When you set a symbolic link, UNIX creates an entry in your current working directory that pointsto 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/ud82/demo/ORDERS ORDERS% ln -s /usr/ud82/demo/D_ORDERS D_ORDERS:udt
UniData Release 8.1.2 Build: (6069)© Rocket Software, Inc. 1985-2015.All rights reserved.
Current UniData home is /disk1/ud82/.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 currentworking directory for the link, although the ORDERS file remains physically located in /usr/ud82/demo.
To access ORDERS from the current account, you must add a VOC entry for the file. You can useSETFILE (by entering SETFILE ORDERS ORDERS at the colon prompt), or you can use AE, asshown in the following example:
:LIST ORDERS WITH ORD_DATE LIKE "...1996"Not a filename :
Chapter 3: UniData and the UNIX file system
22
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 22 20111OrderORDERS.... Date......912 01/13/1996941 01/14/1996830 01/24/1996970 01/15/1996834 01/24/1996
Notice that even though ORDERS appeared in the LS output, you need to add a VOC entry to definethe file to your current UniData account.
Note: Refer to your host operating system documentation for more information about UNIXsymbolic links. For more information about the VOC file, see Using UniData.
UniData hashed files
Static files
Hashed files are binary data files. They cannot be read by text editors external to UniData. EachUniData hashed file consists of a file header and one or more groups of data. UniData supports twoproprietary hashing algorithms, which determine which data groups contain each record. Hashingallows direct access to a record by translating its record key into its location in a data file.
The following screen shows 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 VOC savedlists:!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 ofthe 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 that are hashed to the group. UniData adds overflow blocks to thefile, but subsequent accessing and updating of records is then resource-intensive and performance
Points to remember about static files
23
suffers. UniData provides utilities to resize static files by adding more groups (changing the modulo) orby 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.
▪ When you create the file, you define the size of a static file by specifying the number and size ofgroups in the file.
▪ When you add records to the file, each record is hashed to a group by using a proprietary hashingalgorithm.
▪ 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 dynamicfile.
See Managing UniData files, on page 93 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 linksto these files). 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 filesystem. The following screen shows 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. Thedat001 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, UniDatahashes the keys to groups in dat001. As the file fills up, UniData adds more groups to the dat001file. If the current file system fills up or if dat001 grows larger than a UniData limit, UniData creates adat002 file. If dat002 is in another file system, UniData creates a UNIX link to the dat002 file in theoriginal dynamic file.
Chapter 3: UniData and the UNIX file system
24
The over001 file
As you add records to a dynamic file, whenever the space reserved for data in a group in the primaryfile gets too full, UniData writes the excess data into blocks in over001. Registers within UniDatatrack how blocks in over001 are linked to groups in dat001. If over001 gets too large, UniDataadds more blocks to it. If the current file system becomes full or over001 grows larger than a UniDatalimit, UniData creates an over002 file. If the over002 file is in a file system different from thecurrent 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 dynamicfile with an overflow file for each dat file. For example, over001 corresponds to dat001, over002corresponds to dat002, and so forth. When the file is cleared, UniData maintains this overflowstructure.
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 placeautomatically during UniData processing.
▪ Dynamic files can expand across UNIX file systems. The original dynamic file contains UNIX links toany “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 thatfollows symbolic links to guarantee complete backups of dynamic files.
Note: Managing UniData files, on page 93 includes detailed information about the behaviorof UniData dynamic files.
Sequentially hashed files
A sequentially hashed file has the same structure as a dynamic file, but UniData stores all recordssequentially based on the primary key. The modulo (number of groups) for a sequentially hashed file isfixed, 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. Youspecify a percentage of the file that you want to remain empty to allow for growth. Although thestructure for a sequentially hashed file is the same as a dynamic file, the modulo is fixed.
Use sequentially hashed files for files where most access is based on the primary key.
The dat001 file
The dat001 file is also called the primary data file. As you add records to a sequentially hashed file,UniData hashes the keys, based on information in the gmekey file, to groups in dat001. If your dataoverflows 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 inthe primary file gets too full, UniData writes the excess data into blocks in over001. Registers withinUniData track how blocks in over001 are linked to groups in dat001. If over001 gets too large,
The gmekey file
25
UniData adds more blocks to it. If the current file system becomes full, or over001 grows larger thana UniData limit, UniData creates an over002 file. If the over002 file resides in a different file systemthan 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 by using the shfbuildcommand.
The gmekey file
Each sequentially hashed file contains a static, read-only file that is called the gmekey file. This fileis read into memory when you open a sequentially hashed file. The gmekey file contains informationabout the type of keys in the file (alphabetic or numeric), and controls which group a record is hashedto when it is written.
You create a sequentially hashed file by converting an existing dynamic or static file with theshfbuild command:
Syntax:
shfbuild [-a |-k] [-n | -t] [-f] [-e empty percent] [-m modulo] [-bblock size multiplier] [-i infile] outfile
The following table describes the shfbuild options.
Parameter Description
-a Only rebuild the last group of the sequentially hashed file. UniData splitsthe last group into groups according to the records in the group. If you usethis option, the outfile should be the name of the sequentially hashed file.Do not specify infile.
-k Build the gmekey file only. If you use this option, outfile should be thename of the sequentially hashed file. Do not specify infile. UniData rebuildsthe gmekey file according to the keys in each group of outfile.
-n/-t Force the outfile to be in numeric or alphabetic order. By default, theorder of outfile is determined by the infile primary key type. If infile is asequentially hashed file, UniData uses the same order in outfile. If infileis not a sequentially hashed file, the order of outfile is determined by thejustification of the @ID of the infile dictionary record. If it is right justified, itis numeric. Otherwise, it is alphabetic.
If you use the -a or the -k option, these options have no effect.-f Force outfile to truncate before it is built.-m Specifies the new modulo of outfile.-e Empty percent. This percent is a number between 0 - 99 which indicates
how much space in the rebuilt groups to reserve. UniData calculates thenew modulo of the file from empty_percent and the number of recordsin the rebuilt groups. If you do not specify -e or -m, UniData rebuilds thesequentially hashed file according to the default empty percent of 20.
-b Specifies the block size of the sequentially hashed file in kilobytes.-i infile Load the contents from infile instead of outfile. infile can be any type of
UniData file.outfile The name of the output file.
To convert an existing file, run the shfbuild command from the system level prompt, as shown inthe following example:
% shfbuild -m 59 SEQUENTIAL
Chapter 3: UniData and the UNIX file system
26
175 keys found from SEQUENTIAL.175 records appended to SEQUENTIAL; current modulo is 59.
After you convert a file to a sequentially hashed file, you must manually enter a file pointer in the VOCfile 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".
DIR-type files
A UniData DIR-type file is a UNIX directory that contains UNIX text or data files. Each UNIX text ordata file is a UniData record. The BP file, a UniData file that stores UniBasic source files and compiledprograms, is a DIR-type file.
The following screen shows the structure of a sample BP file:
:LIST BPLIST BP 12:08:40 May 22 2011 1BP........MAINPROG_MAINPROGSUBR_SUBR4 records listed
In the example, MAINPROG and SUBR are UniBasic source files. _MAINPROG and _SUBR are compiledprograms.
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 boththe directory and the hashed file where the record is located. The following screen shows an exampleof 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
Points to remember about multilevel files
27
ECLTYPECPlistdictCTSP.OPENLISTDICT6 records listed
Note: If the subfile of a multilevel file has the same name as the directory, you can use thedirectory name only to access the subfile. For instance, LIST MULTI1 is correct syntax if thedirectory 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 ordinarystatic or dynamic files. The leveled structure requires more system resources to read and updatethese files. For this reason, we recommend that you use ordinary static or dynamic hashed filesrather than multilevel files whenever possible. You can share a single dictionary among UniDatafiles 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 moreUNIX subdirectories (UniData DIR type files). All of the DIR files share the same dictionary. To access arecord, you must specify both the multilevel directory file and the DIR file where the record resides.
The following screen shows 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 2011 1MULTID....MAINPROG_MAINPROGSUBR_SUBR4 records listed
Chapter 3: UniData and the UNIX file system
28
Note: If a subdirectory of a multilevel directory file has the same name as the main directory, youcan use the main directory name to access the subdirectory. For instance, LIST MULTID is correctsyntax if the directory MULTID contains the subdirectory 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 (UNIXsubdirectories).
▪ 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. Theleveled structure means that more system resources are needed to read and update these files.For this reason, we recommend that you use ordinary DIR files rather than multilevel directory fileswhenever possible. You can share a single dictionary among UniData DIR files by modifying theVOC 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 hashedfile. 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 asingle index file.
The ECL CREATE.INDEX command creates the index file. The ECL BUILD.INDEX commandpopulates 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 turnoff automatic indexing on one or more data files (by using the ECL DISABLE.INDEX command) tospeed performance during periods of heavy activity on your system. If you turn off automatic indexingfor a file, UniData creates a log file and stores all updates to it. The ECL UPDATE.INDEX commandallows you to apply updates from index logs to indexes in batch mode, and the ECL ENABLE.INDEXcommand turns automatic updating back on. Either CLEAR.FILE or DELETE.INDEX (with the ALLoption) removes the index log file.
Note: For more information about index handling commands, see the UniData CommandsReference.
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 accountdirectory with the data file. The following screen shows a sample account where a static file namedSTATIC.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_
Index-related files for a dynamic hashed or sequentially hashed file
29
CTLG D_MULTI1 D__REPORT_ SAVEDLISTS _V__VIEWDYNAMIC.TEST D_MULTID D__SCREEN_ STATIC.TEST savedlistsD_AE_COMS D_ORDERS D___V__VIEW VOC x_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 logfile in the dynamic file directory. The following screen shows a sample account where a dynamic filenamed 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.TEST
dat001 idx001 over001 xlog001
Notice that the index and index log files are located in the dynamic file directory rather than in theaccount. The file idx001 is the index file, and xlog001 is the index log file.
UniData and tmp spaceUniData uses temporary disk storage for various 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 analternate temporary disk storage location by setting an environment variable that is called TMP, or bychanging the TMP parameter in the udtconfig file, located in /usr/ud82/include. If both areset, the environment variable overrides the configuration parameter.
Chapter 3: UniData and the UNIX file system
30
Note: You can override the default location for many UniData work files. However, some filescannot be overridden. Among these files are working files that are used by SP.EDIT (copiesof hold files you are editing) , working files that are used by UniData SQL for sorting with theORDER BY clause, and working files for the UniBasic compiler. UniData creates these files in /tmpregardless of any other setting.
In most cases, UniData removes its temporary work files when they are no longer needed. Certain filesexist that UniData does not remove, including output files that it generates from filetools. Because thedefault /tmp is routinely cleared on many systems, you should consider defining alternate temporarystorage if you know you are going to be repairing files, for example. Otherwise, you risk losing crucialdata if the workfiles are removed before you are finished.
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 Unidata installations.## 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 definealternate temporary disk storage for those users. A user with access to a UNIX prompt can set theenvironment 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 environmentvariable:
TMP=directory-name/;export TMP
printenv TMP
31
Chapter 4: UniData and servicesdaemonsThis chapter explains what UNIX daemons are, and describes daemons specific to UniData.Thischapter explains what services are, and describes services specific to UniData.
What is a daemonservice?A daemonservice is a background process that performs a specific task or set of tasks.DaemonsServices wait in the background until they receive a request for their specific function. Anumber of standard UNIXWindows daemonsservices run on every UNIX platform to control systemprocesses, schedule commands, handle print requests, and perform other similar functions. Refer toyour host operating system documentation for detailed information about the UNIX daemonsservicesthat run on your system.
Principal UniData daemonsservicesThree UniData daemons Database services control your UniData environment. All three of theseUniData daemons run as root. When a user starts a UniData session, the user’s process, called a udt,communicates with the daemonsservices. The udt runs with the permissions valid for the user,preventing inappropriate file access by the UniData daemonsservices.
▪ Lock tracking — smm records all UniBasic locks and semaphore locks, identifying which UniDatauser holds each.
▪ Process cleanup — At periodic intervals, the cleanupd servicedaemon checks the cleanupddaemon to see if terminated process flags have been set. If cleanupd detects a terminatedprocess flag, it deletes the associated process from internal tables, removes requests from thequeue, and removes messages sent to the terminated process. If cleanupd receives a messagefrom a process, it checks to see if the message was sent from a terminated process. If so, it throwsaway the message.
Shared basic code server (sbcs)
The shared basic code server, sbcs, manages shared memory used by globally cataloged UniBasicprograms. UniData starts sbcs when you run startud, and stops it when you run stopud.
The functions of sbcs include:
▪ Loading and tracking globally cataloged programs—sbcs loads globally cataloged programs intoshared memory as needed, and tracks the programs that are loaded and the number of processesthat are running each one. When you run a globally cataloged program, sbcs checks in sharedmemory, then takes the following actions:▫ If the program is already loaded, sbcs increments the counter for the number of users running
it, and tells the udt process which segment to attach to run the program.
▫ If the program has not been loaded yet, sbcs loads the program into shared memory andstarts a counter for it.
▪ Periodically sbcs checks shared memory and removes loaded programs that are no longer in use.
▪ Controlling shared memory—The sbcs daemon can attach up to 20 shared memory segments.(On some platforms sbcs cannot attach 20 segments because the operating system imposes alower limit. For instance, AIX allows a process to attach only 10 shared memory segments.)
Chapter 4: UniData and servicesdaemons
32
▪ The maximum size of each segment for sbcs is determined by the UniData configurationparameter SBCS_SHM_SIZE. sbcs attaches segments as it needs to load globally catalogedprograms, and releases memory back to the operating system when it is no longer needed.Whenit no longer needs the memory, sbcs attaches segments as it needs to load globally catalogedprograms, and releases memory back to UNIX.
▪ Process cleanup — At periodic intervals, the sbcs process checks the cleanupd daemonserviceto see if terminated process flags have been set. If sbcs detects a terminated process flag, itremoves all messages that are sent for the process. If the terminated process is the only processthat is using a program in shared memory, the program is removed from shared memory. sbcsuses the process ID to determine if a message it receives is from a terminated process. If so, sbcsdiscards the message.
Note: For more information about sbcs, see Managing cataloged programs, on page 190.
Shared memory manager (smm)
The shared memory manager, smm, builds and manages structures and tables within shared memory.UniData starts smm when you run startud, and stops it when you run stopud.start the UniDataDatabase Service, and stops it when you stop the UniData Database Service.
UniData processes (udt processes) communicate with smm to request and return shared memory. TheUniData 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, andprevents more than that number of users from logging in to UniData. When a license is about toexpire, smm also displays warning messages.
▪ User process tracking — When a user logs on to UniData, smm assigns an internal tracking numberto 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 daemonservice tosee if terminated process flags have been set. If smm detects a terminated process flag, it checksall ipc IDs. If one of the ipc IDs is invalid, smm exits, bringing down UniData. smm also checks allprocess groups to see if a group leader terminated abnormally. If so, smm removes all self-createdshared memory pieces and reclaims all global pages that are occupied by the terminated group.smm also corrects inconsistencies the global control tables (GCT) might have. An inconsistencycould 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 CTLtracks all information about the shared memory segments that smm manages. The size of the CTL isrelated to the number of users on the system and to a series of configuration parameters.
See UniData and memory, on page 36 and UniData and UNIX devices, on page 46 for moreinformation about smm.
Clean up (cleanupd)
33
Note: If you are using NFS-mounted file systems, make sure the file systems are mounted asSOFT mounts. If they are mounted as HARD mounts and the remote system is unavailable, theinternal system functions to determine available space on the file system hang until the file systembecomes available. Because of this behavior, udt processes trying to log on to UniData, processesrequesting new shared memory global pages, and processes trying to log off hang. If you mountNFS files as SOFT mounts, these system functions will timeout and return instead of hang.
Clean up (cleanupd)
The clean up daemonprocess, cleanupd, detects terminated user processes at check time intervals.If cleanupd detects a terminated process, internal flags are set. The smm and sbcs daemonsservicesperiodically check to see if cleanupd has set internal flags. If these daemonsservices detect flags,each daemonservice performs the necessary cleanup and resets its own flag to zero. The cleanupddaemonservice performs clean up that is not handled by smm or sbcs. When the smm and sbcsdaemonsservices have reset their flags to zero, the cleanupd daemonservice resets its flag to zero,makes the user process ID available, and frees the local control table.
UniRPC service (unirpcd)
The UniRPC service is used by The U2 Extensible Administration Tool, 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 you are running theRecoverable File System (RFS), you can start sync daemons by setting the udtconfig parametersN_SYNC and SYNC_TIME. Sync daemons periodically flush updated pages from the system buffer tothe 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, theamount 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 UniData daemons. Ifyou are using the Recoverable File System, refer to Administering the Recoverable File System forinformation 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.
Chapter 4: UniData and servicesdaemons
34
The following screen shows output from showud:
# showudUID PID TIME COMMANDroot 19503 0:00 /disk1/ud82/bin/aimglog 0 27543root 19504 0:00 /disk1/ud82/bin/aimglog 1 27543root 19505 0:00 /disk1/ud82/bin/bimglog 2 27543root 19506 0:00 /disk1/ud82/bin/bimglog 3 27543root 19494 0:06 /disk1/ud82/bin/cleanupd -m 10 -t 20root 19500 1:14 /disk1/ud82/bin/cm 27543root 19490 0:00 /disk1/ud82/bin/sbcs -rroot 19499 0:01 /disk1/ud82/bin/sm 60 10705root 19483 0:05 /disk1/ud82/bin/smm -t 60root 19525 0:00 /disk1/unishared/unirpc/unirpcd#
Log files
The sbcs, cleanupd, and smm daemonsservices each record messages in a pair of logs in theudtbin directory. In addition, the udt process writes messages to a log file, called udt.errlog, if aUniData process encounters file corruption in a data file. The following table lists these log files.
Daemon/Process Routine messages Error messages
smm $UDTBIN\/smm.log $UDTBIN\/smm.errlog
sbcs $UDTBIN\/sbcs.log $UDTBIN\/sbsc.errlog
cleanupd $UDTBIN\/cleanupd.log $UDTBIN\/cleanupd.errlog
udt N/A $UDTBIN\/udt.errlog
startud udtbin\startud.log udtbin\startud.errlog
rm udtbin\rm.log udtbin\rm.errlog
rw udtbin\rw.log udtbin\rw.errlog
sm udtbin\sm.log udtbin\sm.errlog
Note: All messages written to the .errlog for a daemonprocess are also written to thedaemonprocess log file. For example, if an error is written to the smm.errlog, the message alsoappears in the smm.log.
For more information and examples, see Starting, stopping, and pausing UniData, on page 58.
The udt.errlog file
If a UniData process encounters file corruption in a data file during processing, the process writesa message to the udt.errlog in udtbin. System administrators can monitor this log and takecorrective action for the specified file.
The following example illustrates errors that are printed to the udt.errlog when a SELECTstatement is run against a corrupted 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
The udt.errlog file
35
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
36
Chapter 5: UniData and memoryThis chapter describes how UniData interacts with the UNIX kernel to configure, attach, and releaseshared memory.
Windows platforms UNIX and shared memoryShared memory is a region of memory that one or more processes may access. Shared memoryresides on a UNIXWindows system outside the address space of any process. It is partitioned intosegments, depending on the configuration of the system. As a process requires memory, the processattaches a segment to its own address space. Processes use UNIX system system-level calls to create,attach, and release shared memory segments.
UNIX kernels define certain limits, such as the maximum and minimum size of a shared memorysegment and the maximum number of shared memory segments the system supports. The names ofthese kernel parameters vary from system to system. The following table lists kernel parameters thatare related to shared memory on an HP-UX system.
UNIX Parameter Description
shmmax The size, in bytes, of the largest shared memory segment the systemsupports.
shmmni The maximum number of shared memory segments the system supports.shmseg The maximum number of shared memory segments the system can assign to
one process.
Note: Kernel configurations vary among UNIX versions. In some UNIX versions (AIX for example),all resources are allocated dynamically, and the system administrator has limited ability toaffect the configuration. Some UNIX versions also have fixed limits on some parameters (forinstance, AIX, where shmseg is 10). Other UNIX versions allow the system administrator to changeparameter 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 UniData configurationparameter names in this manual. UNIX kernel parameter names are in lowercase (for instance,shmmax) and UniData parameters are in uppercase (for instance, SHM_MAX_SIZE).
UniData and shared memoryUniData interacts with UNIX shared memory by using UNIX system system-level calls, UniDataservices,daemons, and UniData configuration parameters (within the limits that are imposed by thehost UNIX system) to build its own structures in shared memory.
UniData, like UNIX, defines shared memory segments that can be attached by UniData processes. Thesbcs servicedaemon creates shared memory structures for storing active globally cataloged UniBasicprograms.
For more information about sbcs, see Managing cataloged programs, on page 190.
The smm servicedaemon creates shared memory structures for internal tables that are required byUniData processes. UniData processes request memory for:
▪ Buffering UniBasic variables
smm and shared memory
37
▪ Storing intermediate results
▪ Storing a current modulo table for dynamic files
Note: The Recoverable File System (RFS) uses a specially allocated region of memory that iscalled the system buffer. If you are using RFS, refer to Administering the Recoverable File Systemfor information about the system buffer.
smm and shared memory
The smm servicedaemon creates shared memory segments as needed. The size and characteristicsof segments smm creates are determined by UniData configuration parameters. Whenever UniDatais started, UniData reads the udtconfig file, which is located in /usr/ud82/include, andstores these values in shared memory. smm subdivides each of its segments into global pages, andsubdivides each global page into local pages.
smm also creates and maintains internal tables that track the use of the structures it creates. Theseinternal tables, which are stored in a shared memory structure that is called CTL, allow smm to protectshared memory pages against accidental overwriting, and optimize the efficiency of memory use byreleasing unneeded shared memory pages back to UNIXthe operating system.
Control table list (CTL)
When you start UniData, smm creates one shared memory segment for the UniData control table list(CTL). The CTL remains in memory when UniData is running, and is returned to the operating systemwhen you run the stopud command.
CTL is subdivided into three regions, as shown in the following example:
Chapter 5: UniData and memory
38
The following table describes the structures in the CTL.
CTL structure Description
GI Segment header; also called general information table.GCTs (global control tables) Each GCT records the use of global pages in a shared memory
segment. UniData determines the number of GCTs in the CTL by theconfiguration parameter SHM_GNTBLS. SHM_GNTBLS must notexceed the kernel parameter shmmni.
LCTs (local control tables) Each LCT records the shared memory activity of a UniData processgroup. UniData determines the number of LCTs in the CTL bythe configuration parameter NUSERS. Each LCT comprises foursubtables: PI, CT, MI, and CI. A process group is related to a processgroup leader, which can be a udt or SQL session, or a user thatis running UniData system-level commands from the operatingsystem level.a UNIX prompt.
PI (process information) table Each PI table registers all processes within a process group.CT (counter table) Each CT records information about the behavior of the process
group.MI (memory information) table Each MI table records all global pages or self-created shared
memory segments that are used by the process group.CI (control information) table Each CI table records all blocks that are allocated from shared
memory for temporary buffers.
smm creates the CTL by using a series of configuration parameters. The following table lists theparameters smm uses to compute the size of CTL.
Control table list (CTL)
39
Configuration parameter Description
SHM_GNTBLS The number of GCTs in the CTL, which is also the maximum numberof shared memory segments that UniData can attach at one time.
NUSERS The number of LCTs in the CTL, which is also the maximum numberof UniData process groups that can run at 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 is also the
number of processes that can be included in a UniData processgroup.
SHM_LCINENTS The number of entries available in the CI table of each LCT; this isthe maximum number of local memory segments that can be usedby a process group at one time. A local segment is made up of oneor more contiguous local pages. This value must be greater than orequal to SHM_LMINENTS. It cannot exceed 255.
SHM_LMINENTS The number of entries available in the MI table of each LCT; thisis the maximum number of global pages or self-created memorysegments a process group can use at one time.
N_GLM_GLOBAL_BUCKET The number of hash buckets system-wide, used to hold the locknames in shared memory. This setting directly affects performance.Normally, the default value of this parameter should not bechanged. However, if you notice significant degradation inperformance, or your application intensively accesses specific files,you can increase this parameter. The default value is the closestprime number to NUSERS * 3.
N_GLM_SELF_BUCKET The number of hash buckets for the per-process locking table.This parameter is highly application dependent. If the applicationrequires a large number of locks in one transaction (more than 20),you should increase this setting to the closest prime number to themaximum number of locks per transaction.
SHM_FIL_CNT Maximum number of dynamic files that can be open concurrently,system-wide.
N_FILESYS Maximum number of UNIX file systems allowed. If you have morethan 200 UNIX file systems, increase to your number of file systems.
The size of the CTL is determined by the totaling the size of the various memory components. Theseinclude the GI tables, GCTs, LCTS, locally locked hash tables, dynamic file tables, OS file system tables,GLM tables, and account-based licensed tables.
The formula for calculating the size of each these components varies slightly on each platform andversion and will be affected by additional components of UniData such as the recoverable file systemand U2 Data Replication.
You can also use the UniData command shmconf to calculate the size of CTL. See Managing memory,on page 168 for more information.
Note: The size of the shared memory segment that is reserved for CTL does not need to match thesize of the segments smm manages. All the segments smm manages are the same size (computed bymultiplying the number of global pages per segment by the size of a global page by 512), but theyare not necessarily the same size as CTL.
Chapter 5: UniData and memory
40
Creating and assigning memory structures
When a UniData process requests memory, smm assigns one or more global pages, as requested, andupdates 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 hasfinished using the assigned memory, the process sends a message to smm, which releases the globalpage or pages and updates the GCTs and LCT.
The following figure illustrates smm’s shared memory structures:
UniData determines the size and number of local pages per global page, and the size and number ofglobal pages per segment, by configuration parameters. The following table lists these parametersand some of the relationships between them.
Parameter Description
SHM_LPAGESZ The size (in 512-byte blocks) of a single local page of sharedmemory.
SHM_GPAGESZ The size (in 512-byte blocks) of a global page of shared memory.SHM_GPAGESZ must be an integral multiple of SHM_LPAGESZ.Divide SHM_GPAGESZ by SHM_LPAGESZ to obtain the number oflocal pages in a global page.
SHM_GNPAGES The number of global pages in a shared memory segment. Computethe size, in bytes, of a shared memory segment by multiplying thesize of a single global page (512*SHM_GPAGESZ) by the numberof global pages per segment (SHM_GNPAGES). This total cannotexceed the maximum segment size that is defined by your operatingsystem.in your UNIX kernel.
Displaying parameter settings
41
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 howmuch memory to reserve and how much to release.
Parameter Description
SHM_FREEPCT Percentage of global pages in a shared memory segment that shouldbe kept free. If the percentage of free pages in a segment dropsbelow this value, smm creates a new segment to handle requests.
SHM_NFREES Number of free shared memory segments that should be kept forUniData. If the number of free segments is larger than this value,smm releases the additional segments back to the operating system.If the number drops below this value, smm creates another segment.This parameter is usually set to one.
Displaying parameter settings
Use the UniData system-level command sms -h to display the current settings for configurationparameters that are 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 = 1SHM_FIL_CNT = 2048JRNL_BUFSZ = 53248
C:\UniData73t\Bin>sms -hShmid of CTL: 1094717696-------------------------------- IDs ---------------------------------smm_pid smm_trace PtoM_msgqid MtoP_msgqid ct_semid (values)108 0 0 1 -2126512128(1,1,1)-------------------- GENERAL INFO ---------------------SHM_GNTBLS = 40 (max 40 global segments / system)SHM_GNPAGES = 32 (32 global pages / global segment)SHM_GPAGESZ = 256 (128K bytes / global page)NUSERS = 128 (max 128 process groups / system)SHM_LPINENTS = 10 (max 10 processes / group)SHM_LMINENTS = 32 (max 32 global pages / group)SHM_LCINENTS = 100 (max 100 control entries / group)SHM_LPAGESZ = 8 (4K bytes / local page)SHM_FREEPCT = 25SHM_NFREES = 1SHM_FIL_CNT = 2048JRNL_BUFSZ = 53248N_FILESYS = 200
Chapter 5: UniData and memory
42
C:\UniData73\Bin>
Note: Refer to UniData configuration parameters, on page 250 for further information aboutthese parameters.
sbcs and shared memory
sbcs creates structures in shared memory as needed for storing active globally cataloged UniBasicprograms. The limits for structures that are created by sbcs are different from those created for smm.
The following table describes two udtconfig parameters that control the size of sbcs segments.
Parameter Description
SBCS_SHM_SIZE Size, in bytes, of shared memory segments sbcs creates.sbcs uses the segments to store globally cataloged programs.sbcs can attach a maximum of 20 segments. (On some UNIXversions, the kernel parameter shmseg constrains sbcs to 10segments.)
MAX_OBJ_SIZE Maximum size, in bytes, of object code files that sbcs can loadinto shared memory. sbcs loads object code files larger thanthis size into the address space of the user instead of sharedmemory.
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 udtprocess. Some circumstances that result in self-created segments are:
▪ Editing a large report with AE. AE is a UniBasic program, and UniData reads a report in as a singlevariable.
▪ Reading a large array as a single variable.
smm creates a segment large enough to hold the variable. smm determines the maximum size by theUNIX kernel parameter shmmax. The self-created segment is counted as a global page used by theUniData process that created the segment.
Warning: Creating these segments of memory is not an efficient resource use, and might resultin poor performance or in thrashing. Use the system-level lstt command or the ipcstatcommand to determine if your application is using self-created segments on a regular basis. If so,analyze the sizes of variables the application uses. Consider increasing the value of SHM_GPAGESZ(the size of a global page) to handle the variables. Also, consider modifying the application to readarrays by element rather than as a single variable.
UniData and the UNIX kernel
43
UniData and the UNIX kernel
When optimizing configuration parameters for shared memory, certain changes might impactparameters in the UNIX kernel. Before you implement configuration changes, you should explore theimpact of these changes on your kernel parameters, and determine if the kernel parameters should bechanged. The following table describes relationships between UNIX kernel parameters and UniData.
UNIX kernel Relationship to UniData
Maximum size of shared memorysegment (shmmax)
Must be larger than CTL, and larger than a shared memorysegment created by smm or sbcs. If this kernel parameteris too low, UniData might not start. If you change theconfiguration parameters that control the size of memorystructures, you might need to adjust this kernel parameter.
Maximum number of shared memorysegments (shmmni)
Must be greater than SHM_GNTBLS, the number of GCTs inthe control table. This parameter should be set high enoughto accommodate all the GCTs, plus one segment for CTL,and one or more (up to 20) for sbcs.
Maximum number of shared memorysegments per process (shmseg)
Must be greater than SHM_LMINENTS, the number of entriesavailable in the MI table for each LCT, which is the numberof global pages that can be attached to a process.
Note: If you are using RFS, UniData allocates a portion of shared memory as a system buffer forRFS processing. When you start UniData with RFS, UniData reserves this buffer, and it is thereforenot available to smm or sbcs. For information about the system buffer, see Administering theRecoverable File System.
44
Chapter 6: UniData and UNIX ipc facilitiesInterprocess communication (ipc) facilities consist of message queues, shared memory segments,and semaphores.
UniData and memory, on page 36 describes shared memory handling. This chapter describes howUniData uses message queues and semaphores.
Note: The UNIX ipcs and ipcrm commands, and the UniData system-level ipcstat andudipcrm commands, are useful for tracking and managing ipc resources. Refer to your hostoperating system documentation for information about ipcs and ipcrm, and see Managing ipcfacilities, on page 184 for information about ipcstat and udipcrm.
Message queuesA message queue is a system resource that can accept input from a number of processes. Processescan then retrieve messages from the queue, with some degree of selectivity. UNIX kernels generallyinclude parameters that define the number of message queues, their size, and the number ofoutstanding messages the system can support.
The following table shows UNIX kernel parameters related to message queues and messages.
Parameter Description
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 sum
of the length of all messages in the queue.msgmap Maximum number of entries in an internal table that UNIX uses to
manage shared memory segments for holding messages.msgseg Number of shared memory segments that UNIX reserves at kernel
startup time for holding messages.
Note: UNIX parameter names differ among versions of UNIX. These parameter names were readfrom a HP-UX kernel.
UniData and message queues
The smm and sbcs daemons use message queues for interprocess communication. When you startUniData, UniData initializes log files for each daemon, and lists the queues that are assigned to eachdaemon in its log.
The following table describes the queues that are required for the UniData daemons.
UniData daemon Queues
smm Two queues: one request queue and one reply queue.sbcs Three queues: one request queue, one reply queue, and one “new
version” queue, used to replace a cataloged program with a newversion.
Semaphores
45
Note: If you are using RFS, you need more message queues to handle communications for the RFSdaemons. See Administering the Recoverable File System for information about RFS requirementsfor message queues.
Tip: If one or more of your UniData daemons will not start, check the error logs for each daemon.Your UNIX kernel might not be configured with enough of message queues. Often, kernels areconfigured for a minimal number of queues. Refer to your host operating system documentationfor information about kernel configuration.
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, thatprocess has access to the system resource the semaphore controls. When the process is finished withthe resource, the process releases the semaphore.
A semaphore undo structure is a resource that is used to recover a semaphore if the process thatacquired it terminates abnormally.
The following table lists UNIX kernel parameters that are important for the use of system semaphores.
UNIX Parameter Description
semmni The maximum number of semaphore identifiers system-wide.semmnu The maximum number of semaphore “undo” structures system-
wide.semmns The maximum number of semaphores available system-wide.
Note: UNIX parameter names differ between versions of UNIX. These parameter names were readfrom a HP-UX kernel.
UniData uses one system semaphore for smm plus an additional NUSERS number of semaphores,starting with 8.1.0. We also recommend that semmnu, the number of undo structures system-wide, beset to three times the number of licensed UniData users.
Note: For a Server license, the number of concurrent sessions is the same as the licensed usercount. Licenses such as “Workgroup” or “Enterprise” allow multiple concurrent connections fromthe same client system to use only one license seat. For these licenses the estimated maximumnumber of concurrent sessions should be used. While the theoretical maximum value is ten timesthe license count, the actual number is usually below this figure. Three times the license count ismore typical figure to use for estimation. Exact requirements will depend upon usage.
Note: If you are using RFS, you might need additional system semaphores. RFS semaphoreoperations may be handled at the UNIX system level, or by C or assembler instructions, dependingon what method is most efficient for your UNIX version. For more information, see Administeringthe Recoverable File System.
46
Chapter 7: UniData and UNIX devicesThis chapter briefly outlines how the UNIX operating system communicates with devices such asterminals, disk drives, tape drives, and printers. The chapter also outlines how UniData interacts withUNIX devices and device handling.
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 communicatewith each type of hardware. The UNIX kernel accesses these programs whenever a process requestsinteraction with a device.
The UNIX communication interface is set up so that any device can be viewed as a file. Data canbe read from and written to a device file. The UNIX kernel translates actions on the device file intorequests from the appropriate device driver program.
On most UNIX systems, device files reside in the /dev directory. This directory contains special files forserial devices, terminals of various sorts, disk devices, tape devices, and so forth. The names for thesespecial device files vary among UNIX versions.
Note: For more information about device files and device drivers on your system, see your hostoperating system documentation.
UniData and terminal devicesFor virtually all terminal input/output, UniData relies on your host UNIX operating system to performterminal emulation. UniData does not maintain its own terminal definition files. Different versions ofUNIX handle terminal definitions differently. Some store terminal definition information in a termcapfile while others use a terminfo database. Refer to your host operating system documentation forinformation about terminal definitions for your system.
Because terminal emulation in UniData happens at the UNIX level, terminal emulation problems thatoccur within UniData must be resolved at the UNIX level.
Note: A handful of UniData utilities require a specific terminal definition file. For these utilities,your UniData product includes a file that is called vvtermcap, which is a termcap-like filewith extensions. This file is located in udtbin. To run the utilities that require it (which includeconfprod, udtconf, and shmconf) you must define either the UDTBIN or the VVTERMCAPenvironment variable. See Environment variables for UniData, on page 263 for furtherinformation.
UniData and tape devicesNames for tape device files vary considerably between UNIX versions. The name of a tape device fileoften 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 UNIXtape devices. To use these commands effectively, you need to understand the tape device namingconventions 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 and printers
47
UniData uses various proprietary methods, as well as standard UNIX commands, to read/write data totape devices. Tape devices must be defined in a UniData file before you can access them via UniDatacommands. See Accessing UNIX devices, on page 160 and the UniData Commands Reference for moreinformation.
UniData and printersUniData uses the UNIX spooler on each system to perform all printing. In order to print from withinUniData to a UNIX printer, that printer must be connected to your system and defined within yourspooler software. UniData provides commands and options that interface with your spooler andenable 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 theUniData commands do not interact directly with a printer device. You need to understand the printerconfiguration and spooler software on your system to troubleshoot UniData printing problems.
Since different UNIX versions use different spooler commands, UniData enables you to definethe translation between UniData printing options and UNIX spooler options by defining a spoolerconfiguration file. You can determine your current spooler selection with the ECL LIMIT or SETPTRcommand. For more information about defining spooler commands, refer to Managing printers inUniData, on page 147.
UniData and serial devicesUniData includes a group of commands that allow you to read data from or write data to a UNIX serialdevice. Although you can use these commands to access a terminal or printer device, they are mostcommonly used for communicating between UniData and a device, such as a bar code reader orscale. If such a device has a physical connection to your system, you can define it within UniData andcommunicate with it through UniBasic commands.
To make effective use of these UniData capabilities, you need to understand your configuration anddevice naming conventions. Refer to your host operating system documentation for this information.See Accessing UNIX devices, on page 160 and Developing UniBasic Applications for information aboutcommunicating with serial devices.
48
Chapter 8: Configuring your UniData systemThis chapter outlines configuration considerations that might be appropriate when you firstimplement UniData or when you make major changes to your system. (Major changes include addingor 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 tosources of more information.
Configuration procedureIf you are installing or upgrading UniData, see Installing and Licensing UniData Products for estimatesfor initial disk and memory needs for your system. These estimates should be sufficient to allow you toinstall and start UniData with a minimal configuration.
1. Identify disk requirements
Disk space and disk configuration are key factors that determine system performance. The initialestimates in Installing and Licensing UniData Products should allow you to install and run UniData.However, we recommend that you evaluate your system, including your operating system, yourhardware configuration, and your application, to develop accurate disk space requirements. We offerthe following suggestions.
▪ Disk Requirements—Use the largest expected size for your data files to estimate how much diskspace you need. In certain applications, such as financial applications, the number of recordsvaries in a predictable way over time. Your system must have enough disk space to handle themaximum number of records without difficulty.
▪ Disk I/O—For best results, configure your disk system so that access is balanced across all devices.We suggest the following:▫ /tmp\TEMP directory—Locate your /tmp\TEMP 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 accountdirectories on separate devices to distribute load.
▫ Logical volume management—Consider implementing a logical volume management protocolthat includes disk striping. Various products and utilities are available; consult with yourhardware vendor for recommendations. Striping, which allows you to create logical volumesthat span physical devices, can provide significant performance improvements by balancingthe load on the system.
Tip: If your application frequently accesses data files that are larger than 300 MB in size, westrongly recommend striping.
2. Identify memory requirements
The initial estimates in Installing and Licensing UniData Products should allow you to install and runUniData with a minimal configuration. However, memory requirements can be platform-dependent as
3. Verify version compatibilities
49
well as application dependent. Estimate the memory that is required for the following components ofyour 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 UniData and memory, on page 36 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, consultyour Rocket Software account representative early in your planning process to determine if yourcurrent UniData version is supported by the hardware or software you are considering.
4. Check/reset UNIX kernelsystem-level parameters
Depending on your version of WindowsUNIX, you may or may not be able to modify kernelsystem-levelparameters directly. When you first implement UniData, the following categories of parameters mightneed adjustment:
▪ Memory — Review parameters that limit the number of shared memory segments system-wide,the maximum and minimum size of a segment, and the maximum number of segments perprocess. For more information, see UniData and memory, on page 36.For more information, seeUniData and memory, on page 36 and Managing memory, on page 168.
▪ Files and Users — Review parameters that define the maximum number of open files and file lockssupported system-wide, the maximum number of files per user process, and the maximum numberof user processes the system can support at one time.
▪ ipc Facilities — Review parameters that define the number and size of message queues yoursystem supports, the number of semaphore sets and semaphores your system supports, and thenumber of semaphore undo structures that are supported. For more information, see UniData andUNIX devices, on page 46 and Managing ipc facilities, on page 184.
Warning: The number of system-wide semaphores, normally semmns, should be a minimumof NUSERS + 20 (NUSERS+10 prior to UniData 8). The number of semaphore identifiers, normallysemmni, must be at least NUSERS/NSEM_PSET + 1. If either of these kernel parameters are notadequate for the number of licensed users, UniData displays an error message similar to “Exit:smm: cannot allocate semaphore for udtno xx errno 28. Exit: SMM can’t setup Control Table List,”and fails to start.
Note: If you discover that you need to change both UNIX kernel parameters and UniDataconfiguration parameters, identify all your requirements and then plan to rebuild the UNIX kernelfirst. If you attempt to start UniData with new parameters, and the UNIX kernel parameters areinsufficient, UniData might not start.
Chapter 8: Configuring your UniData system
50
5. Check/reset UniData configuration parameters
The UniData udtconfig file, which is located in udtbin\include/usr/ud82/include,contains a set of parameters that are given default values when you install UniData. When you start aUniData session, UniData sets UNIX environment variables for each value in the udtconfig file.
Note: The udtconfig file is always located in udtbin\include/usr/ud##/include,where ## is the release number of UniData. For example, the udtconfig file for Release 8.1 islocated in /usr/ud81/include, the udtconfig file for Release 7.2 is located in /usr/ud72/include, and so forth. Do not move the directory to another location, or UniData will not run.
The udtconfig file enables you to define values for each parameter that applies to your UniDataenvironment. Most udtconfig parameters can be adjusted for your environment, but someparameters should not be changed. Refer to UniData configuration parameters, on page 250 fordetailed information about each udtconfig parameter.
You must log on as an Administrator to modify udtconfig parameters.
You must be logged on 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 Unidata installations.## 1.1 System dependent parameters, they should not be changed.LOCKFIFO=1SYS_PV=3# 1.2 Changable parametersNFILES=1019NUSERS=40WRITE_TO_CONSOLE=0TMP=/tmp/NVLMARK=FCNTL_ON=0TOGGLE_NAP_TIME=2QUOTED_IDENTIFIER=1N_FILESYS=200N_GLM_GLOBAL_BUCKET=101N_GLM_SELF_BUCKET=23GLM_MEM_SEGSZ=4194304BGINPUTTIMEOUT=0LB_FLAG=1USE_DF=0NFA_COMPAT_FLAG=0UDT_SPLIT_POLICY=0# 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=2147467264SHM_ATT_ADD=0SHM_LBA=268435456
5. Check/reset UniData configuration parameters
51
SHM_MIN_NATT=4SHM_GNTBLS=75SHM_GNPAGES=8SHM_GPAGESZ=1024SHM_LPINENTS=10SHM_LMINENTS=128SHM_LCINENTS=254SHM_LPAGESZ=8SHM_FREEPCT=25SHM_NFREES=1# 2.2 Size limitation parametersAVG_TUPLE_LEN=4EXPBLKSIZE=64MAX_OBJ_SIZE=307200MIN_MEMORY_TEMP=256STATIC_GROWTH_WARN_TABLE_SIZE=256STATIC_GROWTH_WARN_SIZE=1610612736STATIC_GROWTH_WARN_INTERVAL=300# 2.3 Dynamic file related parametersGRP_FREE_BLK=5SHM_FIL_CNT=2048SPLIT_LOAD=60MERGE_LOAD=40KEYDATA_SPLIT_LOAD=95KEYDATA_MERGE_LOAD=40MAX_FLENGTH=1073740800PART_TBL=/disk1/srcman/alpha/ud82_111222_6069/parttbl# 2.4 NFA/Telnet service related parameterEFS_LCKTIME=0TSTIMEOUT=60NFA_CONVERT_CHAR=0# 2.5 Journal related parameters# 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## 3.1 RFS flag# 3.2 File related parametersBPF_NFILES=80N_PARTFILE=2000# 3.3 AFT related parameters
Chapter 8: Configuring your UniData system
52
N_AFT=1000N_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=8192SB_PAGE_SZ=1# 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# 3.10 dump file controlRFS_DUMP_DIR=RFS_DUMP_HISTORY=1## Section 6 Century Pivot Date#CENTURY_PIVOT=1930## Section 7 Replication parameters#REP_FLAG=1TCA_SIZE=2048MAX_LRF_FILESIZE=1073741824N_REP_OPEN_FILE=8MAX_REP_DISTRIB=1REP_CP_TIMEOUT=300MAX_REP_SHMSZ=2147467264UDR_CONVERT_CHAR=1## Euro data handling symbols# Section 7 Replication parameters#REP_FLAG=1TCA_SIZE=2048MAX_LRF_FILESIZE=1073741824N_REP_OPEN_FILE=8MAX_REP_DISTRIB=1REP_CP_TIMEOUT=300MAX_REP_SHMSZ=2147467264UDR_CONVERT_CHAR=1
6. Define peripherals within UniData
53
## Euro data handling symbols#CONVERT_EURO=0SYSTEM_EURO=164TERM_EURO=164LOG_OVRFLO=/disk1/srcman/alpha/ud82_111222_6069/log/log_overflow_dirREP_LOG_PATH=/disk1/srcman/alpha/ud82_111222_6069/log/replogSB_FLAG=1NULL_FLAG=0#
6. Define peripherals within UniData
You need to define tape devices, printers, and line devices needed by UniData before they canbe accessed from UniData. Before you define a device within UniData, make certain that it isproperly installed and functioning in your UNIX environment. Refer to your host operating systemdocumentation for information about setting up peripherals on your system.
Use the ECL SETTAPE, SETLINE, and SETPTR commands to define your peripherals to UniData.
For more information, see Managing printers in UniData, on page 147 and Managing and using tapedevices.
For more information, see UniData and UNIX spoolers, on page 147, Managing printers in UniData, onpage 147, and Accessing UNIX devices, on page 160.
7. Create UniData accounts
When you implement UniData, you might need to create one or more UniData accounts for yourapplication. 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 filesmay be in the same UNIX directory as the VOC file, or the VOC file may contain pointers to data files inother UNIX file systems. Your system may have a single UniData account or several, depending on yourapplication.
Note: A UNIXWindows account (login, password) is not the same as a UniData account. EveryUniData user should have a separate UNIXWindows account (login and password), but many userscan access the same UniData account.
Use the UNIXWindows platform mkdir command and the UniData system-level newacct commandto create UniData accounts. Refer to your host operating system documentation for information aboutthe mkdir command, and see Managing UniData accounts, on page 69 for information about thenewacct command.
8. Add UNIXWindows users
Accessing UniData requires each user to have a login and password on your UNIXWindows system.We recommend you create a separate UNIX login (UNIX account)Windows account for each UniDatauser. For detailed information about creating UNIXWindows accounts, see your host operating systemdocumentation.
Chapter 8: Configuring your UniData system
54
For UniData-specific information, see Managing UniData security, on page 75.
9. Set environment variables
You do not have to set the UDTHOME and UDTBIN environment variables on Windows platforms,unless your udthome and udtbin directories differ from those defined in the Registry. A user whowants to access UniData using a different UDTHOME and UDTBIN than those defined in the Registry Auser who wants to access UniData must have two environment variables set: UDTHOME and UDTBIN.The settings that you assign for these variables depend on whether you performed a basic or anadvanced UniData installation.
Note: See Installing and Licensing UniData Products for information about installation types.
UDTHOME — This variable identifies the absolute path of the UniData “home” directory. The homedirectory contains subdirectories UniData needs for processing.
UDTBIN — This variable identifies the path for the directory that contains UniData executables. Bydefault, 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 setthese environment variables to each user’s .login or .profile, or a user can set them at the UNIXprompt.profile, if the user is accessing UniData with a different UDTHOME or UDTBIN than defined inthe Registry.
Use the following commands to set these variables:
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
set UDTHOME \directory-name
set UDTBIN \directory-name
set PATH \directory-name
You can also set environment variables from the System window. From the Start menu, click ControlPanel, then double-click System. Click the Advanced system settings, then click EnvironmentVariables. A dialog box similar to the following example appears:
Setting PATH
55
To change add a new environment variable, click New. To change the value of an environmentvariable, highlight the variable you want to change, then click Edit. Enter the name of the environmentvariable you want to establish or change in the Variable box. Enter the setting for the environmentvariable in the Value box. Click OK to set the variable.
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
Environment variables for UniData, on page 263 lists an additional set of variables that aresignificant for UniData users. These environment variables can be set in a user’s login script ordefined from a UNIX prompt before you enter UniData.These can be set in the same manner as theenvironment variables in the previous example before entering UniData.
Chapter 8: Configuring your UniData system
56
Note: While you are in a UniData session, you cannot change environment variables for thatsession. Even if you run setenv, for instance, from the ! prompt, the new setting affects onlyprocesses started from the ! prompt. The new settings do not affect the current UniData session.
10. Review UniData security
Depending on your application, you might need to implement extra measures to ensure data securityand separation of duties. Review your application, and implement any or all of the following:
▪ Default Permissions—Modify the default permissions for udthome and its contents that were setwhen you installed UniData.
▪ Users and domains—Assign UniData users to separate domains, and set permissions on yourdatabase so that each group of users has access to the data they need.
▪ Users and groups—Assign UniData users to separate UNIX groups, and set permissions on yourdatabase 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-grainedprotection.
▪ SQL Privileges—For SQL access, use the UniData SQL GRANT and UniData SQL REVOKEcommands to customize access to tables.
▪ Query Privileges—For UniQuery access, use the QUERY.PRIVILEGE file.
For more information, see Managing UniData security, on page 75.
11. Convert data files
Depending upon the nature of your system change, you might need to perform some conversion ofUniData hashed files. Consider the following:
▪ Recoverable files—If you are implementing UniData’s Recoverable File System, you need to createrecoverable 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 might need to make UniDatafiles accessible to UniData SQL, and you might also need to utilize the Schema API to incorporateODBC compliance for field and attribute names. See Using VSG and the Schema API for detailedinformation.
▪ 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 staticfile, and change file format between high-byte and low-byte formats. For more information, seeManaging UniData files, on page 93 and the UniData Commands Reference.
12. Perform makeudt
UniData provides the capability to invoke C functions from within UniBasic programs. It is necessaryto rebuild the UniData executable (the binary file udtbin/udt) whenever you wish to link in more Cfunctions.
13. 12. Review backup procedures
57
13. 12. Review backup procedures
Special considerations are needed to back up UniData accounts. Make certain your backupprocedures have the following capabilities:
▪ Subdirectories—Your backup procedure should be able to back up at least three levels ofsubdirectories to support UniData MULTIDIR and MULTIFILE files.
▪ Symbolic links—Your backup procedure should be able to follow UNIX symbolic links to supportlarge dynamic files.
▪ Backing up selected files—Your backup procedure should allow you to input a list of files to backup to support full backups of UniData accounts. Simply backing up the directory that contains theVOC file may be insufficient, since data files may not be located in the same UNIX directory as theVOC 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 filethat is associated with the account.
58
Chapter 9: Starting, stopping, and pausingUniData
This chapter describes procedures for normal startup and shutdown of UniData, and also describescommands that are used to log out users, stop processes, and remove ipc facilities if needed.
These commands are also documented in the UniData Commands Reference.
Normal operationUse the UniData startud and stopud commands, respectively, for normal startup and shutdown.These commands start and stop the sbcs, cleanupd, and smm daemonsprocesses, in the correctorder.
Note: You must be logged on as an Administratorroot to run startud or stopud. Make sureyou have defined the environment variables UDTHOME and UDTBIN, and make sure your PATHincludes udtbin. If you are running more than one version of UniData, make sure that theseenvironment variables are set for the version of UniData you want to start and stop.
UniData log files
startud makes entries in the log files (smm.log, sbcs.log, and cleanupd.log) that identifythe system resources that are used by the processesdaemons. If you are using the Recoverable FileSystem (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.logSBCS version: 7.3
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.log
UniData log files
59
SMM version: 7.3
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
The following example is a sample sbcs.log file:
%# type sbcs.logSBCS version: 7.3
BEGSMALL = 1 BEGMED = 5 BEGLARGE = 20 BEGHUGE = 45Begsmall = 0 Begmed = 163 Beglarge = 490 Beghuge = 981Beginning of emergency area = 1638, size = 410Recover = 1 Debugmode = 0
Shm Attach Address: 0Shm Max. Size.....: 1048576SBCS process id...: 2474
IPC facilities:
q - 205 (request queue)q - 206 (reply queue)q - 207 (new version queue)m - 408
The next example shows a sample smm.log:
% type smm.logSMM version: 7.3
Number of users......: 16SMM checking interval: 60 secondsSMM process id.......: 108
Chapter 9: Starting, stopping, and pausing UniData
60
IPC facilities:q - 0 (request queue)q - 1 (reply queue)m - 1094717696 (ctl)m - -1795163136 (glm)m - -1795163134 (shmbuf)s - -2126512128 (ctl)s - -2126512127 (journal)s - -2126512103 (SUPERRELEASE/SUPERCLEAR.LOCKS)s - -2126512128 (latch)s - -2126512127 (latch)s - -2126512126 (latch)s - -2126512125 (latch)s - -2126512124 (latch)s - -2126512123 (latch)s - -2126512122 (latch)s - -2126512121 (latch)s - -2126512120 (latch)s - -2126512119 (latch)s - -2126512118 (latch)s - -2126512117 (latch)s - -2126512116 (latch)s - -2126512115 (latch)s - -2126512114 (latch)s - -2126512113 (latch)
The next example is a sample cleanupd.log
% pg cleanupd.log
CLEANUPD daemon:CLEANUPD checking interval: 20 secondsCLEANUPD minimum interval: 10 secondsCLEANUPD process id.....: 880
Start UniData with startud
The following screen shows the normal output from the startud command:
C:\UniData73\Bin>startudWait for Unidata Service to be started ...The Unidata Service has been started successfully.
Note: When you install UniData for Windows Platforms, UniData installs the UniData Database8.1.2 Service with a setting to automatically start when you boot your computer. You can changethis setting to manually start the UniData Database Service 8.1.2. See your host operating systemdocumentation for detailed information about starting and stopping services.
# startudUsing UDTBIN=/disk1/ud82/binAll output and error logs have been saved to ./saved_logs directory.SMM is started.SBCS is started.CLEANUPD is started.SM is started.Unirpcd is started
Stop UniData with stopud
61
UniData R8.1.2 has been started.#
Note: You can configure your system so that UniData starts automatically when you boot yourcomputer. You need to add or modify a startup script to accomplish this. Refer to your hostoperating system documentation for detailed information about startup scripts.
Warning: If you are using RFS, We recommend that you not start UniData automatically at reboot.If your system is rebooting because of a machine failure, and one or more file system has beendamaged, UniData failure recovery will not complete successfully.
Stop UniData with stopud
For normal operation, use the stopud command with no options. You need to make sure users arelogged out of UniData before you run this command.
The following screen shows the expected response to the stopud command:
C:\UniData73\Bin>stopudDBpause is OFF.Stop Unidata Service now ...CLEANUPD stopped successfully.The Unidata Service has been stopped successfully.#
# stopudUsing UDTBIN=/disk1/ud82/binSM stopped successfully.CLEANUPD stopped successfully.SBCS stopped successfully.SMM stopped successfully.Unirpcd has already been stoppedUnidata R8.1.2 has been shut down.#
Pausing UniDataUniData includes a system-level command that enables you to temporarily block updates to thedatabase. You can use this feature to perform some tasks that require UniData to be stopped, such asbacking up your data.
The dbpause command
UniData includes a system-level command that enables you to temporarily block updates to thedatabase. You can use this feature to perform some tasks that require UniData to be stopped, such asbacking up your data.
Syntax:
dbpause -c
You must log on as Administrator to issue the dbpause command.
Chapter 9: Starting, stopping, and pausing UniData
62
When you specify the -c option, UniData checks to see if any process would prevent dbpause fromcompleting and displays details about those processes that would prevent completion withoutactually pausing the database.
UniData starts a new archive file when you resume processing.
Note: You must log on as root to issue the dbpause command.
dbpause blocks most updates to the database that are made within UniData. UniData completeswrites or transactions in process when you issue the dbpause command before dbpause takeseffect. Updates are blocked until the system administrator runs the dbresume command.
UniData does not block UNIX commands, such as cp or mv. UniData does not block system-levelcommands, such as COPY or MOVE. In addition, UniData does not block updates to the _HOLD_ fileand the _PH_ file, and does not interrupt report printing. If you run dbpause while you are runningRFS, UniData forces a checkpoint, flushes the after image logs to the archive files (if archiving isenabled), and marks the next available logical sequence number in the archive file for use after thebackup. UniData displays this information on the screen from which you ran dbpause, and writes itto udtbin/sm.log.
Note: Some UniData system-level commands, such as cntl_install, require that UniData notbe running. These commands do not run successfully with dbpause in effect. You cannot stopUniData with dbpause in effect.
When dbpause is in effect, the following ECL commands are not blocked:
▪ ACCT.SAVE, T.ATT, T.DUMP
▪ BLOCK.PRINT, BLOCK.TERM
▪ CHECKOVER, dumpgroup, fixfile, fixgroup, guide
▪ CLEAR.ACCOUNT, CLEARDATA, CLR
▪ COMO
▪ CONFIGURE.FILE, HASH.TEST
▪ LIST.TRIGGER
▪ DATE.FORMAT
▪ CLEAR.LOCKS, DELETE.LOCKED.ACTION, LOCK, SUPERCLEAR.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 definedin the login paragraph that is paused)
▪ MIN.MEMORY
▪ SET.DEC, SET.MONEY, SET.THOUS, SET.WIDEZERO
▪ SETOSPRINTER, SETPTR, SP.ASSIGN, SP.EDIT
The dbpause_status command
63
▪ TERM
▪ WHAT
The following example illustrates the output from the dbpause command:
# dbpauseDBpause successful.#
C:\UniData73\bin>dbpauseDBpause successful.#
If you are running RFS, it is important that you synchronize your archive files with your backup fileswhen you are using the dbpause command. For more information about using dbpause with RFS,see Administering the Recoverable File System.
The dbpause_status command
The UniData system-level dbpause_status command returns information about the status ofdbpause.
Syntax:
dbpause_status
The following example illustrates the output from the dbpause_status command when dbpauseis in effect:
C:\UniData73\bin>dbpause_statusDBpause is ON.%
% dbpause_statusDBpause is ON.%
Resuming processing
To resume processing after you issue the dbpause command, issue the dbresume command. Userprocesses resume, and writes that were blocked when the dbpause command was issued complete.
Syntax:
dbresume
You must log on as an Administratorroot to issue the dbresume command.
The following screen illustrates the output from the dbresume command:
# dbresumeDBresume successful.#
C:\UniData73\bin>dbresumeDBresume successful.
Chapter 9: Starting, stopping, and pausing UniData
64
#
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 hungprocesses, clearing ipc facilities for a clean start of UniData, or logging users and resources off for anemergency shutdown. These commands are listed in the following table.
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,
but subsequent operations for that udt do not take place.stopudt runs the UNIX kill -15 command.
deleteuser Forces a user out of UniData and removes the user’s entryfrom the internal tables.
deleteuser first issues the UNIX kill -15 command. If kill-15 is not successful after 5 seconds, deleteuser issues theUNIX kill -9 command. Kill -9 may interrupt a write in progress,causing inconsistent data and file corruption.
ipcstat Lists all ipc structures in use on the system; identifies thosethat are used by UniData processesdaemons.
udipcrm Removes all ipc facilities that are associated with UniData(queues, shared memory segments, semaphores). Thiscommand shuts UniData down and may corrupt files; use thecommand only if a daemon has been killed and has left ipcstructures behind.
stopud -f Forces all UniData processesdaemons to stop regardless ofsystem activity.
Warning: Notice that stopudt, deleteuser, udipcrm, and stopud -f all carry the risk ofdisturbing the integrity of your data. They should never be used as a routine substitute for normaluser logoff.
Listing processes with showud
The showud command lists all UniData processes that are currently running. The following screenshows an example of showud output:
# showudUID PID TIME COMMANDroot 20376 0:00 /disk1/ud82/bin/aimglog 0 14553root 20377 0:00 /disk1/ud82/bin/aimglog 1 14553root 20378 0:00 /disk1/ud82/bin/bimglog 2 14553root 20379 0:00 /disk1/ud82/bin/bimglog 3 14553root 20367 0:00 /disk1/ud82/bin/cleanupd -m 10 -t 20root 20373 0:00 /disk1/ud82/bin/cm 14553root 20363 0:00 /disk1/ud82/bin/sbcs -rroot 20372 0:00 /disk1/ud82/bin/sm 60 30482
Stopping a user process with stopudt
65
root 20356 0:00 /disk1/ud82/bin/smm -t 60root 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 UNIXsystem-level process ID., found in the USRNBR column of listusercommand.
If you need to log out a user you cannot reach, or to clear a hung user process, use this command. Thefollowing screen shows the action of stopudt.
You must log on as rootan Administrator to run stopudt. If you run listuser immediately afterstopudt, the user may still be included in the display. This behavior is because the cleanupdprocess performs its checking and cleanup routines at a predefined interval.
Note: The argument for stopudt is the process ID (pid) associated with the udt process you areremoving. Use the UniData listuser command, as shown in the preceding example. The pid isunder the USRNBR column.If you use the UNIX ps command to get the number, the pid is clearlylabeled. If you use the UniData listuser command, as shown in the above screen, the pid iscalled USRNBR.
Stopping a user process with deleteuser
The deleteuser command first tries to kill the udt process by sending UniData an internal signalequivalent to the UNIX kill -15 command. If this signal is unsuccessful after five seconds, it uses theWin32 API Terminate Process to kill that process.The deleteuser command first tries to kill theuser process with the UNIX kill -15 command. If the kill -15 is unsuccessful after five seconds, a kill -9 isissued.
Syntax:
Chapter 9: Starting, stopping, and pausing UniData
66
deleteuser pid
The argument pid is the UNIX process ID.
Warning: Because deleteuser may execute the Terminate Processissue the UNIX kill -9command, it is important that you verify the pid carefully.
The following screen shows an example of the deleteuser command:
Note: You must log on as rootan Administrator to execute deleteuser.
Displaying ipc facilities with ipcstat
The ipcstat command displays a list of all ipc facilities (message queues, semaphores, and sharedmemory segments) in use on a system, and identifies those facilities that are used by UniDataprocesses. You do not need to log on as an Administratorroot to execute ipcstat.
Syntax:
ipcstat [-q] [-m] [-s]
The following screen shows an example of ipcstat output:
Removing ipc structures with udipcrm
67
Notice that, because the -m option was specified, the output lists shared memory segments only. Useipcstat -q to display message queues, ipcstat -s to list semaphores, and ipcstat with nooptions to list all ipc facilities.
Note: UniData does not use all the ipc facilities on the system. The output from ipcstatindicates which ones are used by UniData processes. The ones that correspond to “unknown” arenot associated with UniData daemonsprocesses.
Removing ipc structures with udipcrm
The udipcrm command uses the UNIX ipcrm command to remove any and all ipc facilitiesassociated with any UniData process. After an abnormal shutdown, you may be unable to startUniData because some ipc facilities did not stop cleanly. You can use either the UNIX ipcrmcommand or udipcrm to remove them.
Syntax:
udipcrm
The udipcrm command is related to the ipcstat command. ipcstat lists all ipc facilitiescurrently in use on a system, and identifies which ones are used by UniData processes. udipcrm onlyremoves the ones associated with UniData.
Warning: Do not use udipcrm to shut down UniData. Use this command only if UniData is down,you cannot restart UniData, and there are ipc facilities that did not stop normally. Use the system-level command showud to verify that the UniData daemons are not running, and use ipcstatto identify ipc facilities that did not stop normally. See Managing ipc facilities, on page 184 forfurther information.
Stopping UniData with stopud -f
This command stops all daemonsprocesses and UniData processes regardless of activity on thesystem. Use this only if your system is hung and stopud fails to work.
Chapter 9: Starting, stopping, and pausing UniData
68
Syntax:
stopud -f
The following screen shows the expected output from stopud -f:
# stopud -fUsing UDTBIN=/disk1/ud82/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 stoppedUnidata R8.1.2 has been shut down.#
C:\UniData73\Bin>stopud -fDBpause is OFF.WARNING: 'stopud -f' will stop the Unidata system with force.This may not gurantee the consistency of the database files.
Would you like to continue?(y/n) [n]yStop Unidata Service now ...CLEANUPD stopped successfully.The Unidata Service has been stopped successfully.
You must log on as an Administratorroot to run stopud -f.
Warning: stopud -f may leave your database in an inconsistent state; use it as a last resort.
69
Chapter 10: Managing UniData accountsThis chapter describes UniData accounts, and describes procedures that are used to create, save, andclear the accounts.
What is a UniData account?A UniData account is a UNIX directory that contains a default set of UniData files, including a VOC fileand its dictionary.
Note: The default files UniData requires for an account are created by the UniData system-levelnewacct 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 pointersto data files in other UNIX directories. Your system may have a single UniData account, or several,depending on your application.
Note: A UNIXWindows account typically means a login ID, its associated password, and its defaultdirectory. No direct relationship exists between UniData accounts and UNIXWindows accounts(logins). Many UNIXWindows users may access any UniData account. A UNIXWindows user’s defaultdirectory does not have to be (and usually is not) a UniData account.
Creating a UniData accountComplete the following fourthree steps to create a UniData account:
1. Make sure the environment variable UDTHOME is set.2. Use the UNIXMS-DOS mkdir command to create the directory that will house the account. The
name of the UniData account directory can be in uppercase, lowercase, or mixed uppercase andlowercase.
3. Change to the directory with the UNIX cd command.4. Make the new directory your working directory. You can change to the directory with the MS-DOS
cd command.5. Use the UniData newacct command to create the VOC and other UniData-specific files in the
directory.
Note: You do not need to log on as rootan Administrator to create a UniData account.However, the newacct command prompts you for a user and group for your account. If youare logged on as root, UniData uses this information to set ownership and permissions forthe account. If you are not logged on as root, UniData ignores your responses and uses yourcurrent logon and group ID.However, you must have Change access in the account directory.
The following three screens illustrate how to create an account, how to enter UniData in the newaccount, and how to use the UniData LS command to list the contents of the account:
# mkdir ACCOUNT# cd ACCOUNT# newacct% newacct
Chapter 10: Managing UniData accounts
70
The UDTHOME for this account is /disk1/ud82/.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/ud82. When you runnewacct, UniData creates the new VOC file by using a standard VOC file that is located in udthome/sys.
Tip: If you want to tailor your standard VOC file before you create new accounts, you may do so.We recommend that you save a copy of the standard VOC before you make changes.
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 8.1.2 Build: (6069)© Rocket Software, Inc. 1985-2015.All rights reserved.Current UniData home is /disk1/ud82/.Current working directory is /disk1/ud82/demo.:
The following three screens illustrate how to create a UniData account. In the examples, the newaccount is names ACCOUNT, and is located in the UniData directory:
C:\U2\ud82>mkdir ACCOUNTC:\U2\ud82>cd ACCOUNTC:\U2\ud82\ACCOUNT>dirVolume in drive C has no label.Volume Serial Number is 5CAF-C1C1Directory of C:\U2\ud82\ACCOUNT12/20/2011 02:08 PM <DIR>.
Creating a UniData account
71
12/20/2011 02:08 PM <DIR>..0 File(s) 0 bytes2 Dir(s) 209,704,177,664 bytes freeC:\U2\ud82\ACCOUNT>
The example illustrates executing the newacct command:
C:\U2\ud82\ACCOUNT>\u2\ud82\bin\newacctThe UDTHOME for this account is C:\U2\ud82\.Do you want to continue(y/n)?
Notice that the screen displays the current setting of UDTHOME and prompts you if you wish tocontinue.
The final example shows the contents of your new UniData account:
When you execute newacct, UniData creates the VOC file for the new account using a standard VOCfile located in the sys subdirectory of your UniData home directory.
Tip: If you want to tailor your standard VOC file before creating new accounts, you may do so.There are a number of reasons you may wish to tailor your VOC file. You may want to add customparagraphs, for instance, that all users should execute. We recommend that you save a copy of thestandard VOC before making changes.
The following table describes the default subdirectories UniData creates with a new account.
Subdirectory Description
BP Used to store UniBasic source and object code.CTLG Used to store locally cataloged UniBasic programs.SAVEDLISTS Used to store SELECT lists.SAVEDLISTSL Used to store temporary information for BY.EXP sorts.
UniData automatically creates and deletes the contents ofthis subdirectory.
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.
Chapter 10: Managing UniData accounts
72
Subdirectory Description
_PH_ Used to store output from background processes (createdby the UniData ECL PHANTOM command) and capturedterminal I/O (created by the UniData ECL COMO command).
_EDAXMAP_ Used to store EDA mapping files._XML_ Used to store XML mapping files.UD_SQLTABLES Used to store system tables for ODBC.
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.
File Description
MENUFILE Stores user-generated menu definitions. VOC VOC (vocabulary) file, containing references for ECL
commands, sentences, paragraphs, and file names._REPORT_ Used to store UReport report definitions._SCREEN_ Used to store UEntry screen definitions.__V__VIEW Used to store UniData SQL view specifications.privilege Used to store UniData SQL access privileges.D_BP Dictionary for the BP file, which holds UniBasic programs.D_CTLG Dictionary for CTLG.D_MENUFILE Dictionary for MENUFILE.D_SAVEDLISTS Dictionary for SAVEDLISTS.D_VOC Dictionary for VOC.D__HOLD_ Dictionary for _HOLD_.D__PH_ Dictionary for _PH_.D__REPORT_ Dictionary for _REPORT_.D__SCREEN_ Dictionary for _SCREEN_.D___V__VIEW Dictionary for __V__VIEWS.D_savedlists Dictionary for savedlists.
Note: See Developing UniBasic Applications and Using UniData SQL for information about UniBasicand UniData SQL
Saving and restoring accountsUniData includes two commands that are specifically designed for backing up and restoring UniDataaccounts. These commands are described in the following table.
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.)
Deleting an account
73
UniData command Description
acctrestore [n] Restores a UniData account that was saved withACCT.SAVE; uses UNIX cpio utility; restricted to asingle tape volume. Specify the tape unit number n;the tape unit must be defined with SETTAPE. If yourun acctrestore while UniData is running, you maycorrupt your data files.
Note: If you are using the Recoverable File System, these commands do not function. If youattempt to run them, an error message displays to the terminal.
Note: Use ACCT.SAVE and acctrestore carefully. These commands do not follow eitherUniData pointers to other directories (set with the SETFILE command) or symbolic links for largedynamic 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, toback up UniData files and accounts. Consult your host operating system documentation and vendordocumentation to determine the procedures to use at your site.
Deleting an accountNo UniData command or utility exists that allows you to delete an entire account. If you need to deletean account, complete the following steps:
1. Analyze the database and identify which files should be deleted. Take care not to delete sharedfiles 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 -rMS-DOS rmdir /s command to delete the account directory. If the account hasfile pointers to other file systems, or dynamic files with part files on other file systems, you maywish to use the ECL DELETE.FILE command to delete the files before you remove the accountdirectory. Use the ECL MAX.USER command to prevent inadvertent access to the UniDataaccount.
Warning: Be careful with rmdir /srm -r. This command removes all files andsubdirectories below the directory you specify. If you have nested accounts (a UniDataaccount within a UniData account) and you remove an account directory with rmdir /srm-r, you could remove more than one account.
Clearing space in UniData accountsThe _PH_ and _HOLD_ subdirectories of each UniData account store output from backgroundprocesses and temporary print files, respectively. These subdirectories can become large, causing diskspace problems. The UniData ECL CLEAR.ACCOUNT command removes all files from either or both ofthese subdirectories.
CLEAR.ACCOUNT
Syntax:
Chapter 10: Managing UniData accounts
74
CLEAR.ACCOUNT
You must log on to the UniData account you are clearing. You do not need to log on as rootanAdministrator, however, you must have write permission for the _PH_ and _HOLD_ directories. Whenyou issue the command, UniData prompts you for confirmation to clear each directory, as shown inthe following example:
:WHERE/disk1/ud82/ACCOUNT:CLEAR.ACCOUNTClear _PH_ directory(Y/N)? YClear _HOLD_ directory(Y/N)? Y
:WHEREC:\UniData73\ACCOUNT:CLEAR.ACCOUNTClear _PH_ directory(Y/N)? YClear _HOLD_ directory(Y/N)? Y
Notice that the ECL WHERE command displays the current account.
Warning: CLEAR.ACCOUNT removes all files from the subdirectories. Use this command only ifyou are certain none of the information is needed. Use the UniData DELETE command or the UNIXrmMS-DOS DEL command, if necessary, to remove only selected files.
75
Chapter 11: Managing UniData securityWhile UniData uses UNIX permissions as its primary security mechanism, a number of procedures existthat you can use for customizing the security of your UniData applications. This chapter describes howto use UNIX login IDs 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 privilegesand other UniData security mechanisms.
When you install UniData, UniData sets default permissions on system files and directories. Afterinstalling UniData, you may want to customize some permissions.
Logins and groupsTo access UniData, users need a UNIX login ID (account).
Note: Utilities for adding and maintaining UNIX accounts are available on many systems.Examples are sam or smit. They require root access, and automate the required steps. Forconsistency, we recommend that you use your UNIX system administration utility to createand maintain UNIX accounts. Refer to your host operating system documentation and vendordocumentation for information about procedures available on your particular system.
UNIX typically stores user and group information in two files, as shown in the following table.
UNIX filename Description
/etc/group Contains a record for each group ID number (gid).Each record includes a group name and definesthe user ID numbers (uid) associated with thegroup.
/etc/passwd Contains a record for each user ID. Each recordincludes a login name, uid, gid, password, homedirectory, default shell identifier, and otheroptional information.
Note: Some UNIX systems use additional files for security. For example, Solaris uses a file called /etc/shadow, and AIX uses one called /etc/security/passwd. Refer to your host operatingsystem documentation for complete information about these files.
Adding a UNIX user
Adding a UNIX user, either manually or through your system administration utility, involves thefollowing 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.
Chapter 11: Managing UniData security
76
Use separate logon IDs
Although other database systems use group login IDs, which are shared by a number of users, UniDataenables you to define a separate logon ID for each user. We strongly recommend that you use separatelogin IDs 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 login IDs makes your system utilize resourcesmore effectively.
▪ It is easier to identify processes that belong to an individual user, which facilitates troubleshooting.
▪ Using separate login IDs allows you to define your users’ responsibilities for protecting theirpasswords and your data.
User groups
Every UNIX user is assigned to a default group. The system recognizes the user as a member of thatdefault group at log on. UNIX permissions allow you to differentiate access among members of agroup and users who are not members of that group. You can use this feature to provide security inUniData by defining applications (or accounts) that should be accessible to certain users, defininggroups to which those users belong, and setting the group owners of the files and directoriesaccordingly.
For example, consider the directory structure that is 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: PAYABLESand RECEIVABLES. Notice the following:
▪ Users in group apusers have read, write, and execute access to the contents of PAYABLES, but onlyread access to RECEIVABLES. They can list the contents of RECEIVABLES, but they cannot add ordelete 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 accessto PAYABLES. They can list the contents of PAYABLES, but they cannot add or delete files inPAYABLES, 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 forinformation about your system. The UNIX id command enables root users to display the current uidand group assignment for any login name. The UNIX newgrp command lets users change betweengroups. 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 they use newgrp to changeto it. In the preceding example, a user who is a member of only group arusers cannot use newgrp tochange to apusers.
Home directories
77
Home directories
UNIX requires you to define a home directory for each login ID. This directory is the working directoryof the user at login time. You can define the same home directory for a group of users, or create aseparate one for each user. The home directory does not must be a UniData account.
Tip: A user’s home directory can contain startup scripts as well as output from non-UniDataapplications (such as UNIX text editors). The UniData command stack is also saved here. If you useUniData accounts as home directories, and users generate other kinds of output there, you mayencounter space or performance problems.
Note: The home directory that you define for a user must exist. If you define a directory and youdo not create it or set appropriate permissions, the user may be unable to log on to UNIX. Whenyou add a user, some administrative utilities create the directory and set permissions. Check thedocumentation for your UNIX system administration utility to determine procedures at your site.
Startup scripts
When a user logs on, the default shell (specified in /etc/passwd) runs a startup script, if one exists, inthe user’s home directory. The file name of the startup script depends on the user’s default shell. Ifthe shell is the Bourne or Korn shell, the startup script is called “.profile”. If the shell is the C shell, thestartup script is called “.login”.
Tip: Many UNIX systems offer a default shell script that you can copy into a user’s home directoryand then customize. Some systems also execute a system-wide script for all login IDs. Refer to yourhost operating system documentation for specific information about your system.
A sample .login file follows:
setenv TERM vt100stty erase ^Hset path=( $path /usr/ud82/bin)umask 002cd /usr/ud82/PAYABLESudt
This example shows how to use a startup script to ensure that a user logs on to a particular UniDataaccount and receives an ECL prompt, rather than a UNIX prompt. The example also defines the user’sterminal type, defines the key sequence for erasing characters, modifies the user’s path to include theUniData bin directory, and specifies the default permissions on files the user creates.
Customizing permissionsWhen you install UniData, the system sets default permissions on system files and directories, asshown in the following table.
File or directory name Permission settings of file/directory
Permission settings of files/subdirectories
udtbin drwxr-xr-x See next rowsudtbin/product.info -rw-r--r-- Not applicable
Chapter 11: Managing UniData security
78
File or directory name Permission settings of file/directory
Permission settings of files/subdirectories
udtbin/us_admin -r-sr-xr-x Not applicableudtbin/us_update_db -r-sr-xr-x Not applicableudthome drwxr-xr-x See following rowsudthome/demo drwxrwxrwx -rwxrwxrwxudthome/lib drwxr-xr-x udthome/objcall drwxrwxr-x See next rowsudthome/objcall/demo drwxrwxr-x rw-rw-rw-udthome/objcall/include
drwxrwxr-x rw-r--r--
/usr/ud82/ods drwxrwxr-x Variesudthome/parttbl Not applicable -rw-r--r--udthome/sybase drwxrwxr-x Variesudthome/sys drwxr-xr-x Variesudthome /sys/HELP.FILE -rw-r--r-- Not applicableudthome/sys/udtpath -rw-rw-rw Not applicableudthome/work drwxr-xr-x -rw-rw----/usr/ud82/include drwxr-xr-x -rw-r--r--
We make 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 global catalog tablefile, are -rw-rw-rw-. Users responsible for cataloging or deletingcataloged programs need write permission. Other users needonly read permission.
udthome sys/DICT.DICT Users need only read permission. Administrators need writepermission as well.
udthome/sys/VOC Users need only read permission. Administrators need writepermission as well.
udthome/sys/CTLG Users, including programmers, need execute permission to thisglobal catalog directory. In general, do not allow users to add ordelete subdirectories to CTLG.
udthome/sys/ CTLG/nand directories andfiles within thesesubdirectories
CTLG contains a subdirectory for each letter of the alphabetand one for symbols. Users need execute permission to thesedirectories and read access to the files in them. Programmersmay need read and write permissions so that they can catalog ordelete cataloged programs.
udthome/demo This directory is used for training and experimentation. Use anypermissions settings that suit your situation.
udthome/sys/AE_BP All users with access to AE (the line editor) need read and writepermissions.
When you create a UniData account, we suggest the following guidelines for setting permissions forthe directory, subdirectories, and files in the account:
Customizing a VOC file
79
Directory or File Guidance
./ Only users who need to create files in the directory should havewrite permission.
./BP Users need read and execute permissions so they can runUniBasic programs that are not globally cataloged. Programmersneed write permission.
./CTLG Users need read and execute permissions so they can run locallycataloged programs. Programmers and administrators needwrite permission so they can locally catalog and delete locallycataloged programs.
./SAVEDLISTS Users need read and write permissions.
./_HOLD_ Users need read and write permissions.
./_PH_ Users need read and write permissions.
./VOC (This refers to the account VOC file, not the master VOC file inudthome/sys.) Users must have read and write access toenter their accounts unless you have set the VOC_READONLYenvironment variable. See Using UniData for more informationabout the VOC file.
The following screen shows a long listing for a UniData account called PAYABLES, incorporating thesuggestions outlined in the preceding tables:
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, userslogged on to that account will not be able to execute them. When a user enters an ECL command,UniData searches the VOC file in the current account. If there is no corresponding entry, UniDatadisplays an error message instead of executing the command.
Chapter 11: Managing UniData security
80
The following example shows the results of deleting a VOC entry:
LIST VOC WITH @ID = COPY 19:03:11 May 23 2011 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 executeUNIX system-level commands. You may want to consider removing some or all of these from the VOCfiles for your accounts.
Command Description
! Escapes to a UNIX shell prompt.CLEAR.FILE Clears the data or dictionary of a file.CNAME Changes a file name.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.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.
Note: You can remove entries from the UniData master VOC file (located in udthome/sys)or from the VOC files in one or more UniData accounts. The master VOC is installed as part ofthe UniData installation, and is used to build VOC files for your accounts when you execute thenewacct command. If you remove commands from the master VOC file, and then create newUniData accounts, users in the new accounts will not be able to execute the commands youremoved.
Tip: If you choose to modify the master VOC file, make sure you save a copy of it and its dictionarybefore you begin your modifications.
Warning: When you remove a VOC command entry, UniData no longer recognizes that command.UniData displays an error message if a user tries to execute the command, whether at the ECLprompt, or within a UniBasic program.
Customizing UniData
81
Customizing UniData
The UDT.OPTIONS command enables you to customize your UniData environment. UDT.OPTIONS19 allows you to choose whether superusers (root access) can bypass security restrictions created byremoving entries from the VOC file. If UDT.OPTIONS 19 is on, UniData prevents even superusers fromexecuting commands after you remove the entries are from the VOC file.
If UDT.OPTIONS 19 is off (the default), UniData allows superusers to execute ECL commands evenif the command entries were removed from the VOC file. When a user logged on as root executes acommand, 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, andif UDT.OPTIONS 19 is off, root users can still execute the command. The following table shows thebehavior of UDT.OPTIONS 19.
UDT.OPTIONS 19 Command status Behavior
ON VOC entry exists root can execute command
Others can execute commandOFF VOC entry exists root can execute command
Others can execute commandON No VOC entry root cannot execute command
Others cannot executecommand
OFF No VOC entry root can execute command
Others cannot executecommand
UDT.OPTIONS 19 is turned off by default. Leave it off to allow root users to execute commands thatusers cannot; turn it on to make root users consistent with other users.
Note: See the UDT.OPTIONS Commands Reference for detailed information about theUDT.OPTIONS command.
Remote itemsYou can further customize security by replacing some command entries in your VOC file with remoteitems. A remote item (R-type VOC record) allows you to store a record definition in a location otherthan the VOC file. You can substitute remote items for sentences, paragraphs, commands, locallycataloged 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 UNIXWindows file permissionsfrom the current account, limiting access to the item.
▪ You can supply a “security routine” for the remote item. R-type items name a cataloged subroutinethat 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 securitysubroutine, 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:
Chapter 11: Managing UniData security
82
With this VOC record in place, when a user executes the LIST command, UniData executes a securitysubroutine called SECTEST2. If that subroutine returns a value of 1, UniData executes the item calledLIST in a file called OTHER_VOC.
The next screen shows the security subroutine:
:AE BP SECTEST2Top of "SECTEST2" in "BP", 4 lines, 66 characters.*--: P001: SUBROUTINE SECTEST2(OKAY)002: COMMON /SECUR/ VALID003: OKAY = VALID004: RETURNBottom.
In this example, the subroutine obtains the value of VALID from named COMMON. The value can be setby 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 verbLIST
The next screen shows what happens if VALID is 1 (true):
:LIST VOC WITH F1 = PALIST VOC WITH F1 = PA 11:13:27 May 24 2011 1VOC.......ECLTYPECPCTSP.OPENlistdictLISTDICT6 records listed
The SETFILE commandYou can also customize security by placing data files in a location with different UNIXNTFS permissionsthan your UniData account, and then modifying the corresponding VOC entries to point to thelocation. Use the SETFILE ECL command to establish the file pointers, as shown in the followingexample:
:SETFILE /usr/SECURE/INVENTORY INVENTORYEstablish the file pointerTree name /usr/SECURE/INVENTORYVoc name INVENTORYDictionary name /usr/SECURE/D_INVENTORYOk to establish pointer(Y/N) = Y
LOGIN and LOGOUT paragraphs
83
SETFILE completed.
:SETFILE \USERS\SECURE\INVENTORY INVENTORYEstablish the file pointerTree name \USERS\SECURE\INVENTORYVoc name INVENTORYDictionary name \USERS\SECURE\D_INVENTORYOk to establish pointer(Y/N) = YSETFILE completed.
You can set the UNIXNTFS permissions at the location of the file to limit access. If a user withinsufficient permissions tries to access the file, UniData displays an error message similar to the oneshown in the following example:
:LIST INVENTORY ALLOpen /usr/SECURE/INVENTORY error.Open file error.:
See the UniData Commands Reference for information about the SETFILE command.
LOGIN and LOGOUT paragraphsYou can define LOGIN and LOGOUT paragraphs in the VOC files of your accounts to provide furthercontrol of users’ environments. A typical LOGIN paragraph sets UDT.OPTIONS and invokes anapplication menu. A typical LOGOUT paragraph executes a routine that cleans up application files andexits the application in an orderly manner.
If a user’s .login or .profile sets their working directoryIf you define the environment so that a user logsdirectly on to a UniData account and executes the udt command, and the LOGIN paragraph definesthe UDT.OPTIONS and displays a menu, the user does not see either the UNIX shellMS-DOS prompt orthe 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 aLOGIN paragraph. If there is one, UniData automatically executes it.
▪ If the user changes accounts with the ECL LOGTO command, UniData does not execute theLOGOUT paragraph in the account the user is leaving. UniData looks in the VOC file of the accountthe 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 executesthe LOGOUT paragraph, if one is there.
Note: You can also use the ECL ON.ABORT command to prevent users from accessing the ECLor UNIXMS-DOS prompt. ON.ABORT defines a paragraph that executes whenever a UniBasicprogram aborts. See the UniData Commands Reference for information about ON.ABORT.
The following sample session shows simple examples of LOGIN and LOGOUT paragraphs in a UniDataaccount, and a different LOGOUT paragraph in a second account:
:WHERE/users/testacct:CT VOC LOGINVOC:LOGIN:PA
Chapter 11: Managing UniData security
84
UDT.OPTIONS 19 ONUDT.OPTIONS 20 ONDISPLAY ENTERING UNIDATA APPLICATION:CT VOC LOGOUTVOC:LOGOUT:PADISPLAY EXITING UNIDATA APPLICATION::LOGTO /usr/ud82/demo:CT VOC LOGOUTVOC:LOGOUT:PARUN BP EXIT_PROGDISPLAY LOGGING OUT OF UNIDATA:
:WHEREC:\USERS\TEST:CT VOC LOGINVOC:
LOGIN:PAUDT.OPTIONS 19 ONUDT.OPTIONS 20 ONDISPLAY ENTERING UNIDATA APPLICATION:CT VOC LOGOUTVOC:
LOGOUT:PADISPLAY EXITING UNIDATA APPLICATION::LOGTO \UniData73\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 andreporting functions.
The next screen shows the response when two of these paragraphs are executed:
C:\USERS\TEST% udtUniData Release 8.1.2 Build: (6063)¬ Rocket Software, Inc. 1985-2015.All rights reserved.
Current UniData home is \U2\ud82\.Current working directory is C:\U2\ud82\TEST.ENTERING UNIDATA APPLICATION::LOGTO \U2\UD82\DEMO
Creating a login paragraph for UniData ODBC connections
85
:WHEREC:\U2\UD82\DEMO:QUITEXITING THE INVENTORY APPLICATIONLOGGING OUT OF UNIDATA%
% pwd/users/testacct% udtUniData Release 8.1.2 Build: (6069)© Rocket Software, Inc. 1985-2015.All rights reserved.Current UniData home is /disk1/ud82/.Current working directory is /users/testacct.ENTERING UNIDATA APPLICATION:LOGTO /usr/ud82/demo:WHERE/users/ud82/demo:QUITEXITING THE INVENTORY APPLICATIONLOGGING OUT OF UNIDATA%
Notice that the LOGIN paragraph defines UDT.OPTIONS and then prints a message. A LOGIN paragraphcan also execute a program or display a menu. If a user’s .login or .profile file sets their workingdirectory to a UniData account and executes the udt command, and the LOGIN paragraph definesthe UDT.OPTIONS and displays a menu, the user does not see either the UNIX shell prompt or the ECLprompt.
Notice also that logging out of UniData after the LOGTO command executes the LOGOUT paragraph ofthe current account only.
Note: If UDT.OPTIONS 20, U_IGNLGN_LGTO, is on, users logged on as root can access an accountthrough the LOGTO command without executing the LOGIN paragraph. If a user logged on as rootaccesses the account directly, UniData executes the LOGIN paragraph regardless of the setting ofUDT.OPTIONS 20.
Creating a login paragraph for UniData ODBC connections
ODBCLOGIN is a UniBasic subroutine you can create to initialize the UniData environment for UniDataODBC, UCI, UniOLEDB, U2.Net, and JDBC connections. You must globally catalog the subroutine.
Note: When a connection is made through UniData ODBC, UCI, UniOLEDB, U2.Net, or JDBC,the standard LOGIN paragraph for an account is not executed. You must create an ODBCLOGINsubroutine to initialize environments when accessing through UniData ODBC, UCI, UniOLEDB,U2.Net, or JDBC.
The syntax for ODBCLOGIN is:
SUBROUTINE ODBCLOGIN(RTNVAL,USERNAME)
When a UniData ODBC, UCI, UniOLEDB, U2.Net, or JDBC connection is made, UniData attempts toexecute the ODBCLOGIN paragraph during the verification phase of a connection, in the database youspecify in the connection information.
Chapter 11: Managing UniData security
86
Note: If there is no cataloged ODBCLOGIN, the connection is allowed.
The following table describes the parameters of the subroutine.
Parameter Description
RTNVAL If RTNVAL is a nonzero value, the connection is allowed. If it iszero, the connection is disallowed.
USERNAME The user name that is being used to establish the connection.
Tip: You can use ODBCLOGIN to define COMMON variables and other environment settings for useduring a UniData ODBC connection.
In the following example, the ODBCLOGIN subroutine returns zero and does not allow a connectionunless the user name is “root.”
SUBROUTINE OEDBCLOGIN(RTNVAL,USERNAME)IF USERNAME=”root” THENRTNVAL = 1END ELSERTNVAL = 0ENDRETURN
Creating a login paragraph for UniObjects connections
UOLOGIN is a UniBasic subroutine you can create to implement any sort of security functionalityyou would like. You must globally catalog the subroutine. For example, you may want to prevent aUniObjects connection unless a user provides the name of the application.
The syntax for UOLOGIN is:
SUBROUTINE UOLOGIN(RTNVAL,SECRET)
When a UniObjects connection is made, UniData attempts to execute the UOLOGIN paragraph duringthe verification phase of a connection, in the database you specify in the connection information.
Note: If there is no cataloged UOLOGIN subroutine, the connection is allowed.
The following table describes the parameters of the subroutine.
Parameter Description
RTNVAL If RTNVAL is a nonzero value, the connection is allowed. If itis zero, the connection is disallowed and an error message isreturned.
SECRET A secret value that the client passes to the server to identify itself.It can be the client application name, an alternative user ID, oranything that only the client and the server know between them toidentify the client.
UniData SQL privileges
87
In the following example. UniData does not allow a connection unless the name of the application andthe user name is provided. In this case, the user information is “<SECURITYTOKEN>:username”.
SUBROUTINE UOLOGIN(RTNVAL,SECURITYTOKEN)IF SECURITYTOKEN=”uocommand” THENRTNVAL=1END ELSERTNVAL=0ENDRETURN
If the UOLOGIN subroutine is cataloged on the server, the UniObjects server runs the subroutine whenthe connection is made. If the return value is zero, the server process terminates and returns Error80011.
The UOLoginCommand file
The UOLOGIN subroutine provides similar functionality as the LOGIN paragraph, where UniObjectsconnections bypass paragraphs. You can use some LOGIN paragraph commands from UniData, suchas DATE.FORMAT, in the UOLOGIN subroutine to set global conditions, but they would not result in aglobal change.
At UniData 8.1.1, you can enable these commands to be read from UOLOGIN by utilizing theUOLoginCommand file, located in the $UDTBIN directory, when a UniObjects session starts.Currently, only one command can run from this file and must be specified on the first line of theUOLoginCommand file (for example, DATE.FORMAT)
This UOLoginCommand file is in addition to the UOLOGIN subroutine. It does not impact the existingUOLOGIN functionality.
UniData SQL privilegesWhen a user creates a UniData SQL table or view, that user has exclusive UniData SQL access toit. Regardless of file permissions set at the UNIXsystem level, no other user can execute UniDataSQL operations against the table or view until the owner grants privileges through the UniData SQLGRANT command. The UniData SQL REVOKE command allows the owner (or any other user with ALLprivileges) to revoke privileges that were granted. UniData SQL privileges can be granted or revokedfor an entire table or for specified commands.
Note: UniData and UniData SQL share data and dictionary files. Therefore, depending on theUNIXsystem-level file permissions, tables you create in UniData SQL can be accessed by otherUniData tools, such as ECL or UniQuery. The GRANT and REVOKE commands affect UniData SQLoperations only.
See the UniData SQL Commands Reference and Using UniData SQL for additional information aboutUniData SQL privileges.
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 singleuser, or for all users in the UNIX group, by creating a QUERY.PRIVILEGE table in a specified format andadding records to that table.
Chapter 11: Managing UniData security
88
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 UNIXsystem-level file permissions,other UniData security implementations, and privileges granted using the QUERY.PRIVILEGE table. In aSECURE system, unless privileges are granted in the QUERY.PRIVILEGE table, users cannot access filesthrough UniQuery, regardless of UNIXsystem-level 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 mustcreate and populate the QUERY.PRIVILEGE file manually.
▪ ECL commands, such as CREATE.FILE, DELETE.FILE, and CNAME, do not update theQUERY.PRIVILEGE table.
▪ ECL commands are not affected by UniQuery security.
▪ The UniQuery MODIFY command is not affected by the UniQuery security feature. The security isimposed when a user attempts to SELECT.
▪ A default of OPEN or SECURE affects all UniData accounts that share the same udthome. Youcannot 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 hasALL access to the INVENTORY file and its dictionary, you must consider D_INVENTORY as well. Ifthe system default is OPEN, the user can access D_INVENTORY. Otherwise, if you want the user toaccess 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 inudthome\/sys. If this file does not exist, UniQuery functions as it has previously, with no field-levelsecurity.
Warning: If you create the QUERY.PRIVILEGE file, but do not populate the file with any records,UniData does not allow any user to access any files on the system through UniQuery.
When you install UniData, the UniQuery security is not implemented, and there is no QUERY.PRIVILEGEfile. If you wish to turn on this feature, you must create QUERY.PRIVILEGE and D_QUERY.PRIVILEGEmanually.
Records in the QUERY.PRIVILEGE file grant the SELECT privilege to users or groups of users, at thefile level or the attribute level. Each QUERY.PRIVILEGE record has one attribute. The dictionary of theQUERY.PRIVILEGE file contains four records.
Following is a sample of the dictionary of the QUERY.PRIVILEGE file:
The QUERY.PRIVILEGE file
89
The following table describes each QUERY.PRIVILEGE attribute:
Attributes Description
@ID Data attribute that defines the user or domain and the file for whichyou are setting privileges. If you are setting up a system default, @IDis DEFAULT. Otherwise, @ID must be of the format username*path,domain\ username*path, or PUBLIC*path.
Defines the user or UNIX group and the file for which you aresetting privileges. If you are setting up a system default, @ID isDEFAULT. Otherwise, @ID must be of the format username*path orPUBLIC*path.
PRIV Data attribute that indicates the attributes to which you aregranting privileges, by location. PRIV is a multivalued attribute. Togrant privileges to all attributes in a file, set PRIV to ALL. If you aresetting a system default, set PRIV to OPEN to grant privileges. Torestrict privileges to every attribute in a file, set PRIV to SECURE.
Multivalued; lists the field(s) to which you are granting access bylocation in the data file record. You can grant privileges on all fieldsin a data file by setting PRIV to ALL. If you are setting up a systemdefault, set PRIV to either OPEN or SECURE.
FULLPATH Virtual attribute formula that designates the full path of the fileaffected by PRIV. This formula has the format FIELD(@ID,”*”,2).
The absolute UNIX path of the file on which you are settingUniQuery privileges.
USERNAME Virtual attribute formula that designates the user affected by PRIV.This formula has the format FIELD(@ID,”*”,1).
The UNIX ID of the user (or group) to which you are grantingprivileges.
Note: You can customize the length of the dictionary attributes in the QUERY.PRIVILEGE file. Thelength of @ID should be sufficient to contain the longest UNIX user name and the longest absolutepath for a UniData file on your system. FULLPATH and USERNAME should be long enough to handlethe longest absolute path and longest UNIX user name, respectively.
The following table shows a very simple example of a QUERY.PRIVILEGE file:
Chapter 11: Managing UniData security
90
This QUERY.PRIVILEGE file means:
▪ Except for INVENTORY and CLIENTS, which are in the demo database, all users have privileges toquery 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 usercan 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, everytime a user logs on to UniData, their udt process reads the contents of QUERY.PRIVILEGE and storesthe information for reference. Then, when a user attempts a UniQuery access, UniData checks thestored information, following the following steps:
1. Check for privileges granted to the user’s UNIX groupdomain.
If the user’s UNIX groupdomain has sufficient privileges for the requested access, allow theaccess. 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, proceedto step 3.
3. Check for privileges granted to PUBLIC.
Privileges granted to PUBLIC apply to all system users. If PUBLIC has sufficient privileges for therequested 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 therequested 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 on as the root useran Administrator. Users do not need to log off.
2. Create QUERY.PRIVILEGE
91
2. Create QUERY.PRIVILEGE
Change your working directory to udthome\/sys, and enter udt to start a UniData session. Use theECL CREATE.FILE command as follows:
:WHERE/usr/ud82/sys:CREATE.FILE QUERY.PRIVILEGE 101Create file D_QUERY.PRIVILEGE, modulo/1,blocksize/1024Hash type = 0Create file QUERY.PRIVILEGE, modulo/101,blocksize/1024Hash type = 0Added "@ID", the default record for UniData to DICT QUERY.PRIVILEGE.
:WHERE\UniData73\sys:CREATE.FILE QUERY.PRIVILEGE 101Create file D_QUERY.PRIVILEGE, modulo/1,blocksize/1024Hash type = 0Create file QUERY.PRIVILEGE, modulo/101,blocksize/1024Hash type = 0Added "@ID", the default record for UniData to DICT QUERY.PRIVILEGE.
Make the QUERY.PRIVILEGE file a static hashed file.
3. Set permissions
The QUERY.PRIVILEGE file and its dictionary should be read-only to all users except theAdministratorroot.
Check the UNIX permissions and change them, if necessary, as follows.
4. Edit the dictionary
Use UniEntry, AE, or ED to edit D_QUERY.PRIVILEGE. The dictionary must look like the followingexample:
Chapter 11: Managing UniData security
92
You can customize the format for the dictionary items to specify lengths for the attributes that matchyour 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 theQUERY.PRIVILEGE file, users logging on to UniData access whatever records are present at the timethey log on, which may cause unexpected results.
Use AE, UniEntry, or ED to populate the QUERY.PRIVILEGE file.
93
Chapter 12: Managing UniData filesUniData stores your data in hashed files of several different types in the database. UniData alsosupplies other types of files to support your database, including index files, program files, anddirectory files.
This chapter describes the types of UniData hashed files and explains the commands that are used tomanage them. See UniData and the UNIX file system, on page 18 for information about other file types.
UniData hashed filesHashed files are binary files that cannot be viewed at the operating system level or read by text editorsexternal 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 preciselocation of the data is stored in the header of that group. The goal of hashing is to make searchingfor 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 supportstwo proprietary hashing algorithms (hash type 0 and hash type 1). The hash type determines the datagroup that contains each record.
The most efficient hashing algorithm for a file is the one that provides the best distribution of keysacross the groups in the file. If the distribution is uneven, heavily loaded groups are accessed morefrequently, which results in inefficient disk space use and increased contention for those groups. Thedefault hash type for both static and dynamic files is 0. When you create a file, you can specify hashtype 1, 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 ofdata 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.
Overflow Type Description
Level 1 overflow The amount of space that is required for the data in the groupis larger than the amount of space available. This happens ifthe length of a data record is too long for the block size, or if thenumber of records in the group grows so large that not all ofthe data fits. UniData appends overflow blocks to the originalfile, and the data portions of records are stored in overflow. Thepointers and keys remain in the primary data file; accessing arecord can require two reads, one to determine the address andthe second to read the data in overflow.
Chapter 12: Managing UniData files
94
Overflow Type Description
Level 2 overflow The amount of space required for pointers and keys is larger thanthe total size of the group. This happens if too many records arehashed to the group. UniData creates overflow blocks whichcontain both data and keys. Record access can require multiplereads to determine the location and find the data.
Note: When a group in a static file overflows, the overflow blocks are linked to that specific group.If overflow blocks are freed (by deleting records, for example) they remain linked to the originalgroup and are not available to handle overflow from any other group in the data file. The spaceused by the blocks is not returned to the operating system. Level 1 overflow eventually impactsthe performance of a static hashed file. Level 2 overflow impacts performance earlier and moreseverely, so correct sizing to prevent level 2 overflow is critical.
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 ofstatic 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. Eachgroup 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 datafile is in level 1 overflow.
The following screen shows the structure of the ORDERS file in the UniData demo database:
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
Splitting and merging
95
records are added, UniData adds groups to the data file (dat001) to prevent level 2 overflow and addsblocks to the overflow file (over001) to contain level 1 overflow.
If you specify the OVERFLOW option with the CREATE.FILE command, UniData creates a dynamicfile with an overflow file for each data file. For example, over001 corresponds to dat001, over002corresponds to dat002, and so forth. When the file is cleared, UniData maintains this overflowstructure. For more information about the CREATE.FILE command, see the UniData CommandsReference.
Splitting and merging
When a group in the primary data file reaches level 1 overflow, UniData stores the overflowed data inblocks in the overflow file. Blocks in over001 are linked (internal to UniData) to groups in the primarydata file dat001. When the overflow file runs out of blocks, UniData adds blocks to it. To prevent level 2overflow, UniData splits groups (increasing the modulo of the primary file) whenever the load factor ofan existing group reaches a level called the splitting threshold (or SPLIT.LOAD). The splitting processis 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 allthe 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 (orMERGE.LOAD).
▪ One of the two groups is the last group in the file.
UniData provides three different split/merge types for dynamic files, KEYONLY, KEYDATA, andWHOLEFILE. UniData provides two different split/merge types for dynamic files, KEYONLY andKEYDATA. You can set the split/merge type when you create a dynamic file, and you can change anexisting split/merge type with the CONFIGURE.FILE command or the memresize command. UseFILE.STAT, ANALYZE.FILE, or GROUP.STAT to display the split/merge type.
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 splitinto 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 apair of groups that resulted from a split is under 40% of the size of a single group, the pair areeligible to merge. You can change the splitting threshold for a single KEYONLY file with theCONFIGURE.FILE or memresize commands, and you can change the defaults for all files bychanging the SPLIT_LOAD and MERGE_LOAD parameters in the UniData configuration file (\udthome\include\udtconfig/usr/ud82/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, anddata. By default, the splitting threshold for a group in a KEYDATA dynamic file is 95 percent, so thegroup can split into two when the space occupied by keys, pointers, and data reaches 95 percent ofthe size of the group.
Chapter 12: Managing UniData files
96
By default, the merging threshold for a KEYDATA dynamic file is 40 percent, so if the total load in a pairof groups that resulted from a split is under 40 percent of the size of a single group, the pair are eligibleto merge.
You can change the splitting threshold for a single KEYDATA file with the CONFIGURE.FILEor memresize commands, and you can change the defaults for all files by changing theKEYDATA_SPLIT_LOAD and KEYDATA_MERGE_LOAD parameters in the UniData configuration file(\udthome\include\udtconfig/usr/ud82/include/udtconfig).
Selecting a split/merge type
Use the KEYONLY split/merge type for files whose records differ widely in length (standard deviationfrom average is large). When record lengths vary widely, the KEYONLY split/merge type makes moreefficient use of disk space. Use the guide or FILE.STAT command to determine the record lengthand 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 portionof each record is large with respect to the record ID. For files with these characteristics, the KEYDATAsplit/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 evendistribution of keys in groups in dynamic files. If key distribution in a file is uneven, you shouldconsider tuning the modulo, block size, and split/merge type of the file. If none of these methods iseffective, 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 nothave 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 exceed255. 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 “parttables.” 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 fordynamic 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 canincrease 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 parameterPART_TBL.
Components of a part table
97
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 memresizecommands. Supply the full path of the ASCII file you wish to use as a part table. UniData copiesthe 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 yoursystem. In the following example, the PARTTBL keyword assigns a part table to a new dynamic file:
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. Thedefault parttbl looks like:
% more /usr/ud82/parttbl. 1000%
The following table describes the fields in the part table:
Field Description
Path Name of the file system; the “.” in the default table indicates the filesystem where a UniData dynamic file is created. The “.” may be usedas the first entry in the table; all other entries must be the absoluteUNIX path (for instance, /disk6/files).
Reserved Space Amount of free space (in 512-byte blocks) that UniData should leavein the file system after creating part files there.
Use vi or any other UNIX text editor to create and edit per-file part tables or to modify the default parttable 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:
Chapter 12: Managing UniData files
98
▪ 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 dynamicfile in the directory for another dynamic file. This, in turn, causes failures when users attempt toexecute 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 confusionwhen UniData attempts to check reserved space against available space.
▪ If you move the system default part table, change the value of the configuration parameterPART_TBL.
▪ When you create an ASCII file to use as a per-file part table, remember that UniData places acopy 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 needto edit the copy in each dynamic file to which it is assigned, as well as at the location where youcreated the file.
▪ If you execute the memresize command to change the parameters of a dynamic file, and youspecify the PARTTBL keyword for a file that already has a per-file part table, you will overwrite theexisting 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 datapart file.
Locating the dynamic file directory
The dynamic file directory is located in the UniData account where CREATE.FILE was executed.
The following example illustrates creating a dynamic file in the current account directory:
Locating the part files
99
In the above example, the primary data file (dat001) includes a file header and the three data groupsfor a total of four 1K blocks. The overflow file (over001) includes a 1K file header. Since MAX_FLENGTHis larger than minimum modulo * block size, the primary data file and overflow file each have only one“part.”
Locating the part files
The part files (or UNIX links to them) are located in the dynamic file directory. UniData reserves spacefor part files on the UNIX file system where the dynamic file directory is located (the resident filesystem) 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/ud82/demo/ORDERS, UniData checks the operating system file system tables for the UNIX file system,or device id, where /usr/ud82/demo resides, and then checks the part table for an entry for thatfile system. Depending on the configuration of the system, /usr/ud82/demo might reside in afile system called /usr, or /usr/ud82, or /usr/ud82/demo.
▪ If the part table does not have an entry for that file system, use the reserved space figureassociated 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 thereserved 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:
Chapter 12: Managing UniData files
100
In the preceding example, the primary data file (dat001) includes a file header and the three datagroups for a total of four 1K blocks. The overflow file (over001) includes a 1K file header. SinceMAX_FLENGTH is larger than minimum modulo * block size, the primary data file and overflow fileeach have only one “part.”
The following example shows what happens when there is insufficient space on the resident partitionof the dynamic file. The part table used in the example is one that stipulates a very large reservedspace on the current file system, thereby forcing the part files to another file system:
Notice that the dat001 and over001 files were created in a different partition and are referenced byUNIX links.
Tips and constraints for creating a dynamic file
This section provides information about choosing the optimal modulo and block size for a dynamicfile.
Choosing the initial modulo
If you are creating a dynamic hashed file, selecting an appropriate starting (minimum) modulo iscritical to the future efficiency of the file. You should select a starting modulo based on the expectedfuture size of the file, because subsequent splitting and merging operations are affected by the initialmodulo.
Choosing the block size
101
Starting with a modulo that is very small (for instance, 3) produces inefficient hashing and splitting asthe file grows. Starting with a modulo that is very large produces a file that may initially take up moredisk space than needed, but that impact is more desirable than the slow performance and inefficiencythat results if the starting modulo is too small.
When you create a dynamic file, estimate the initial modulo by using the same procedure forestimating 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 recordlength. We recommend 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 byboth keys and data. If the block size is not large with respect to record size, the file will occupy a largeamount 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 theaverage key length. We recommend that you choose a block size that is at least ten times the averagekey length. Load factor in a KEYONLY file is based on the percentage of the space in each block thatis 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 inefficientdistribution.
When dynamic files expand
When records are added or updated in a dynamic file, a data part file, overflow part file, or index partfile may expand. Whenever a write operation requires additional blocks, the following considerationsdetermine 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 ifthe 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 writewithout expanding into reserved space. For instance, if 10 blocks are needed, and the differencebetween 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 to its UNIXfile system, and then checks the part table for an entry for that file system. For example, ifthe part file is /usr/ud82/demo/ORDERS/dat001, UniData locates the UNIX file systemwhere /usr/ud82/demo/ORDERS resides, and checks the part table for an entry for thatfile system. If there is an entry, UniData takes the reserved space 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 eithercondition is not true, and the part file is an overflow part file, UniData checks all the existing overflowpart files. If one of those part files meets the conditions, that part file is expanded. If no existing partfile can expand, UniData must create a new overflow part file. If the part file is a data part file, UniDatacan expand only the last data part file created. For instance, if the dynamic file directory containsdat001 and dat002, only dat002 can expand.
Chapter 12: Managing UniData files
102
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_FLENGTHOverflow part file The smaller of the following:
▪ The larger of (size of over001) and (current modulo * block size)
▪ MAX_FLENGTHIndex part file The smaller of the following:
▪ The larger of (size of dat001) and (current modulo * block size)
▪ MAX_FLENGTH
UniData searches the partitions listed in the part table for the dynamic file for a partition that meetsthe 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 filedirectory saves the overhead required by a symbolic link.
2. All entries, in order from top to bottom.▪ 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 - reservedspace).
▪ If the amount of free space is 20% or more of the estimated size, creates the new part file atthat 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 filesystem for the part files. To prevent duplicate directory names, UniData assigns a prefix to each. Theprefixes are assigned based on an index in the target file system called .fil_prefix_tbl (a hiddenASCII text file maintained by UniData).
A sample .fil_prefix_tbl follows:
% more .fil_prefix_tblAA:/home/terric/SAMPLEAB:/home/terric/NEWACCT
Management tools for dynamic files
103
AC:/home/terric/NEWACCT/MULTI1
Each entry in .fil_prefix_tbl relates a prefix (AA, AB, and so on) to the path of a parent directoryfor dynamic files. The parent directory can be a UniData account directory or a UniData multilevel filedirectory. Using the sample table, this creates the following directories:
▪ If a dynamic file originated in the account directory named /home/terric/SAMPLE, thedirectory created when the file expands is called AAfilename.
▪ If a dynamic file originated in the account directory named /home/terric/NEWACCT, thedirectory created when that file expands is called ABfilename.
▪ If a dynamic file is a subfile of the multilevel file /home/terric/NEWACCT/MULTI1, thedirectory created when that file expands is called ACfilename.
The following screen shows a directory listing that corresponds to the prefix table from the previousexample:
Warning: Do not edit or remove .fil_prefix_tbl. You will encounter unexpected resultscreating, updating, and deleting dynamic files. If .fil_prefix_tbl is inadvertently removedfrom a target directory, you can execute the system-level fixtbl command in each of yourUniData accounts to rebuild it.
Management tools for dynamic files
UniData supplies three tools for system administrators to manage dynamic files. The tools identify andresolve some of the inconsistencies that result if users manipulate part files at the operating systemlevel 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 fileswhich should be resolved to prevent apparent data loss. The tool also reports an error if a part file isnot found in the correct destination. Execute auditor from the UNIX prompt or use ! to execute auditorfrom the ECL command prompt. Your current working directory must be a UniData account. auditorchecks all the dynamic files that have pointers in the VOC file of the current account.
Chapter 12: Managing UniData files
104
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, butthere 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 adynamic file in the current account. fixtbl can select a new prefix, then move and relink the partfiles 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 byanother directory, fixtbl can create an entry in .fil_prefix_tbl that is consistent with thelinks 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 differentlocation. mvpart sets or resets symbolic links, if needed, and creates or updates a prefix table(.fil_prefix_tbll) 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” bymerging is not necessarily made available for other use. When a group splits, the extra group addedto the dynamic file is assigned to the existing group that split. When a merge occurs, the “freed” groupremains 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 dynamicfile. A certain number are reserved for the groups they were part of, and the remainder of theblocks are available for overflow from any group in the file. The UniData configuration parameterGRP_FREE_BLK defines the maximum number of free blocks that should be kept in the free block listfor a particular group. If more blocks are freed, they are kept in the free block list at the file level.
Refer to UniData configuration parameters, on page 250 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 ECLDELETE command with the ALL option, the file returns to its minimum modulo, and the disk spaceis returned to UNIX. However, if you remove all records from a dynamic file using a select list, the filemay not return to its minimum modulo. Depending on the order in which records are removed, somegroups resulting from earlier splits may not become eligible for merging even though they do notcontain any records.
The following screens show splitting and merging in a dynamic file. The first example shows creating adynamic file with a minimum modulo of 3:
Dynamic files and disk space
105
Notice the following points:
▪ Because the file was created with a block size multiplier of two, the size of each block is 2,048bytes.
▪ 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:
Chapter 12: Managing UniData files
106
The FILE.STAT command shows the following output:
Notice the following points:
▪ The original three groups have split.
▪ Now there are 12 groups in the primary data file, and 10 groups (plus the header group) in theoverflow file.
The following screen shows the results of deleting all records with a select list:
Dynamic files and disk space
107
Notice the following points:
▪ 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 original three groups have split.
▪ Now there are 12 groups in the primary data file, and 10 groups (plus the header group) in theoverflow file.
The final screen shows the results of CLEAR.FILE:
The following example shows the results of deleting all records with a select list:
Chapter 12: Managing UniData files
108
Notice the following points:
▪ Merging has reduced the modulo to 10.
▪ The file size as measured at the operating system level has not changed from the previousexample.
▪ Some groups did not merge, and the groups that were added remain allocated to the file.
The final example shows the results of CLEAR.FILE:
Sequentially hashed files
109
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 storedsequentially based on the primary key. The modulo (number of groups) for a sequentially hashed file isfixed, 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 thestructure 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
The dat001 file is also called the primary data file. As you add records to a sequentially hashed file,UniData hashes the keys, based on information in the gmekey file, to groups in dat001. If your dataoverflows the group (level 1 overflow), UniData writes the overflow data to the over001 file.
Chapter 12: Managing UniData files
110
The over001 file
As you add records to a sequentially hashed file, whenever the space reserved for data in a group inthe primary file gets too full, UniData writes the excess data into blocks in over001. Registers withinUniData track how blocks in over001 are linked to groups in dat001. If over001 gets too large,UniData adds more blocks to it. If the current file system becomes full, or over001 grows larger thana UniData limit, UniData creates an over002 file. If the over002 file resides in a different file systemthan 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 by using the shfbuildcommand.
The gmekey file
Each sequentially hashed file contains a static, read-only file that is called the gmekey file. This fileis read into memory when you open a sequentially hashed file. The gmekey file contains informationabout the type of keys in the file (alphabetic or numeric), and controls which group a record is hashedto when it is written.
You create a sequentially hashed file by converting an existing dynamic or static file with theshfbuild command:
Syntax:
shfbuild [-a |-k] [-n | -t] [-f] [-e empty percent] [-m modulo] [-bblock size multiplier] [-i infile] outfile
The following table describes the shfbuild options.
Parameter Description
-a Only rebuild the last group of the sequentially hashed file. UniData splitsthe last group into groups according to the records in the group. If you usethis option, the outfile should be the name of the sequentially hashed file.Do not specify infile.
-k Build the gmekey file only. If you use this option, outfile should be thename of the sequentially hashed file. Do not specify infile. UniData rebuildsthe gmekey file according to the keys in each group of outfile.
-n/-t Force the outfile to be in numeric or alphabetic order. By default, theorder of outfile is determined by the infile primary key type. If infile is asequentially hashed file, UniData uses the same order in outfile. If infileis not a sequentially hashed file, the order of outfile is determined by thejustification of the @ID of the infile dictionary record. If it is right justified, itis numeric. Otherwise, it is alphabetic.
If you use the -a or the -k option, these options have no effect.-f Force outfile to truncate before it is built.-m Specifies the new modulo of outfile.-e Empty percent. This percent is a number between 0 - 99 which indicates
how much space in the rebuilt groups to reserve. UniData calculates thenew modulo of the file from empty_percent and the number of recordsin the rebuilt groups. If you do not specify -e or -m, UniData rebuilds thesequentially hashed file according to the default empty percent of 20.
-b Specifies the block size of the sequentially hashed file in kilobytes.-i infile Load the contents from infile instead of outfile. infile can be any type of
UniData file.outfile The name of the output file.
File-handling commands
111
To convert an existing file, run the shfbuild command from the system level prompt, as shown inthe following example:
% shfbuild -m 59 SEQUENTIAL175 keys found from SEQUENTIAL.175 records appended to SEQUENTIAL; current modulo is 59.
After you convert a file to a sequentially hashed file, you must manually enter a file pointer in the VOCfile 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".
File-handling commandsUniData includes a variety of commands for you to create and delete UniData files, as well as to obtainstatus information, change file parameters, and diagnose and repair damaged hashed files.
Note: Refer to UniData and the UNIX file system, on page 18 for additional information aboutindex files and index log files.
The following table describes ECL file-handling commands, and indicates the UniData file types theyaffect.
Command Description
CREATE.FILE Creates a UniData file; works for static and dynamic hashed files,dictionary files, DIR files, multilevel files and multilevel directories.
DELETE.FILE Deletes a UniData file; works for static, dynamic, and sequentiallyhashed files, dictionary files, DIR files, multilevel files, and multileveldirectories.
CLEAR.FILE Removes all records from a UniData file; works for static, dynamic, andsequentially hashed files, dictionary files, DIR files, multilevel subfiles,and multilevel subdirectories.
CNAME Changes the name of a UniData file; works for static, dynamic, andsequentially hashed files and DIR files. Does not work for multilevelsubfiles and multilevel subdirectories or dictionary files.
SETFILE Sets a pointer to a UniData file; works for static, dynamic, andsequentially files, DIR files, multilevel files, and multilevel directories.Does not work for dictionary files or for multilevel subfiles orsubdirectories.
RECORD Identifies group where a primary key is hashed, and displays a list ofkeys hashed to that group. Works for static, dynamic, and sequentiallyhashed files and for multilevel subfiles. Does not work for dictionaries,directory files, multilevel directories, or multilevel subdirectories.
Chapter 12: Managing UniData files
112
Command Description
FILE.STAT Displays statistics about a hashed file, including modulo, blocksize, hash type, and record statistics. Works for static, dynamic, andsequentially hashed files, or static or dynamic multilevel subfiles. Doesnot work for dictionaries, 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, or static or dynamic multilevelsubfiles. Does not work for dictionaries, directory or multileveldirectory files, or multilevel subdirectories.
RESIZE Changes the modulo, block size, or hash type of a UniData statichashed file. Works on static hashed files, static hashed multilevelsubfiles, or dynamic files. Does not work on directories, multileveldirectories or subdirectories, or dictionaries.
ANALYZE.FILE Displays statistics, including current and minimum modulo, hashtype, block size, split/merge type, split load, merge load, and recorddistribution for a dynamic file. Works on dynamic and sequentiallyhashed files and dynamic hashed multilevel subfiles only.
CONFIGURE.FILE Changes split/merge type, split load, merge load, part table, orminimum modulo for a dynamic file. Works on dynamic hashed filesand dynamic hashed multilevel subfiles only.
REBUILD.FILE Reconstructs a dynamic file using current settings for split load, mergeload, and minimum modulo. Used after CONFIGURE.FILE. Works ondynamic hashed files and dynamic hashed multilevel subfiles only.
CHECKOVER Checks UniData hashed files for level 2 overflow. Works on all UniDatahashed files and subfiles. Used to check all files in a UniData accountdirectory.
See the UniData Commands Reference for detailed information about the syntax of file-handlingcommands.
The next table describes UniData system-level file-handling commands.
Command Description
auditor Checks all dynamic files in a UniData account to report inconsistenciesbetween symbolic links, part file locations, and file prefix tables.
checkover Checks UniData hashed files for level 2 overflow. Works on all UniDatahashed files and subfiles. Checks all files in a UniData accountdirectory. You can execute the system-level version with UniData shutdown or with UniData running.
dumpgroup Unloads the contents of a damaged group in a hashed file; you canexecute with UniData shut down or with UniData running. Does notwork with EDA files.
fixfile Repairs damaged groups in a file; you can execute with UniData shutdown or with UniData running. Does not work with EDA files.
fixgroup Repairs a damaged group; you can execute with UniData shut down orwith UniData running. Does not work with EDA files.
fixtbl Resolves inconsistencies between symbolic links and file prefix tablesfor all dynamic files in a UniData account. You must execute withUniData shut down.
guide Identifies damaged hashed files or dictionary files. You cannot executeif UniData is shut down. Does not work with EDA files.
File corruption
113
Command Description
guide_ndx Identifies corruption in an index file.memresize Changes the modulo, block size, or hash type of a UniData hashed
file. Works on static or dynamic hashed files and multilevel subfiles.Does not work on sequentially hashed files, directories, multileveldirectories or subdirectories, or dictionaries. This command usesshared memory and disk storage, rather than disk storage alone,as working storage. Although you execute this command from aUNIXsystem-level prompt, you cannot execute it if UniData is shutdown. memresize also converts static files to dynamic files, dynamicfiles to static files, and changes the split/merge type and part table fordynamic files.
mvpart Moves a part file from one location to another, keeping links, location,and file prefix tables consistent. You must execute with UniData shutdown.
shfbuild Converts a static or dynamic file to a sequentially hashed file.
File corruptionFile corruption is damage to the structure of a file. UniData file management tools diagnose andrepair problems that occur if invalid, unreadable, or inconsistent information is written to file or groupheaders. Such invalid information can result in UniData being unable to access part or all of the data inthe 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 datainconsistencies 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 spotson a disk.
▪ Interrupting a write in progress; for example, terminating a UDTelnet Service while users are stilllogged on to the system.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 rarecondition, since UniData prompts the user to reclaim space when this occurs.
Note: Overflowed files are more likely to become corrupted, since multiple I/O operations canbe required to accomplish a single read or write to an overflowed file. An interrupted write canresult in a condition where a primary data block and corresponding overflow blocks are out ofsynch. The increased chance of corruption is particularly significant for files in level 2 overflow.
Preventing file corruption
You can reduce the possibility of file corruption by sizing your files to minimize overflow. Level 1overflow can leave incomplete records in a file, although all the IDs are available. Level 2 overflow
Chapter 12: Managing UniData files
114
can cause more severe data problems because IDs and data can be lost. We strongly recommendthat you monitor and minimize level 2 overflow. Using dynamic files versus static files minimizes level2 overflow, which provides some protection. However, using dynamic files greatly increases level 1overflow, making the risk of file corruption greater than that for static files.
Certain UniData commands carry a direct risk of file corruption, as shown in the following table.
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.
This UniData command first tries to gracefully terminate a process. Ifunsuccessful, deleteuser forces the process to terminate.
stopud -f This syntax of the stopud command does not allow writes tocomplete before logging users off.
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 hashedfiles while UniData is running can damage files. You should always shut UniData down beforeperforming any UNIX-level manipulations on UniData files.Stopping the UniData Telnet Service(UDTelnet) or the UniData Terminal Server (UDSerial) while users are logged on to the system.
▪ Attempting to view/edit a UniData file with a UNIX text, octal, or binary editor can damage the filewhether 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 areaccessing the file during backup may damage the restored file. Any UniData file can be damaged inthis way, but the risk is particularly great for dynamic files.
Note: The file being backed up is not damaged. Danger is only to the file being restored.
▪ Using system-level maintenance tools (for example, online file checking, which is supported undersome UNIX versions) can damage a file, although this is not a common cause of corruption.
UniData detection toolsUniData supplies the following tool for detecting damaged files:
▪ guide — Use the guide command to detect file damage when UniData is running.
guide
guide is a UniData-supplied, system-level utility that provides detailed statistics and suggestions foroptimizing file size and ensuring data integrity.
Note: If you do not want the guide utility to report orphan blocks, set the value of theSUPPRESS_ORPHAN_BLOCK_ERROR to a positive integer.
Syntax
guide [file1, file2,...][-options]
guide
115
Note: You may supply guide with the name of a single UniData file or a series of file namesseparated by commas or spaces. If you do not specify any files, guide processes all files in thecurrent UniData account directory. However, guide does not work with EDA files.
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 advice inthe output. The default filename for the advice information isGUIDE_ADVICE.LIS. You cannot combine the -a and -o options,because UniData assumes the -a option when the -o (output)option is present. You may use the -na option in combination withthe -o option.
-b | -B [filename]
-nb | -NB
(no brief statistics — this is thedefault)
Controls whether UniData produces a file containing a briefsummary of statistical information. The default file name isGUIDE_BRIEF.LIS.
-d1 | -D1 Includes minimum statistics about the file. Does not work with the -ns option.
-d2 | -D2 Includes statistical information helpful in estimating correct filesizing. This is the default. Does not work with the -ns option.
-d3 | -D3 Includes all information reported with -d2, plus additionalinformation about distribution of data sizes. Does not work withthe -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 when the -o(output) option is present, and may not be specified at that time.You may, however, use the -ne option in combination with the -ooption.
-f | -F [filename] Specifies the file that should receive a list of damaged groups. Thedefault file name, if none is specified, is GUIDE_FIXUP.DAT. UniDatacreates this file only if it detects errors.
-ha | -HA Evaluates all hash algorithms (default). Note: the -h option has noeffect if specified for a dynamic file.
-h0 | -H0 Evaluates algorithm 0. Note: the -h option has no effect if specifiedfor a dynamic file.
-h1 | -H1 Evaluates algorithm 1. Note: the -h option has no effect if specifiedfor a dynamic file.
-i | -I [filename] Directs the guide utility to evaluate all of the files in the file namedfilename. GUIDE_INPUT.DAT is the default. The file should becomposed of one file name per line. UniData treats blank lines andlines that begin with an exclamation point as comments.
-l | -L [count] If you specify the -d3 option, the guide utility displays the keys forthe largest records. The key appears in quotes and, if truncated,is followed by an asterisk (*). The -l option controls the number ofrecords that display. The default value is three. Specifying a largenumber of records results in a significantly slower analysis.
Chapter 12: Managing UniData files
116
Option Description
-m | -M
new_modulo
Directs the utility to evaluate the effects of a different modulo uponthe specified file. You must use this option in conjunction with the -h (hash test) option. This option has no effect when specified for adynamic file.
-o | -O [filename] Controls whether output is combined or directed to separate files.If -o is specified, UniData directs all output to the file specifiedby filename. If you do not specify a file name, UniData directs theoutput from guide to “standard out” (usually, your terminal).
-Z num_child_processes Defines the number of concurrent processes to use when analyzingthe file. The default is 4. If the file guide is analyzing has less than100 groups, guide only uses one process.
-p | -P page_length
-np | -NP
(no pagination)
Controls the display of guide output when you specify the -ooption and directs output to the terminal. Specify -np to scroll theoutput past with no pause. Specify -p page-length to pause afterdisplaying each page and prompt with the following message:“Press RETURN to continue...” The following responses areaccepted at the prompt:
• <RETURN> to display the next page.
• “N” to continue with no pauses.
• “Q” to quit the application.
page_length is the number of lines per page in the screen display.The default value is 24.
-r | -R [filename] Specifies whether to produce a reporting file. The filename mustbe the UNIX file specification of a UniData database file, previouslycreated by the CREATE.FILE command. Use this option togenerate file statistics reports using UniQuery. Copy a dictionary forthe report file from udthome\/sys\/D_UDT_GUIDE.
-s | -S count If you specify the -d3 option, the guide utility displays the keys forthe smallest records. UniData displays the key in quotes. If the keyis truncated, it is followed by an asterisk (*). The “-s count” optioncontrols the number of records to appear in sorted order. Thedefault value is three. Large values result in a significantly sloweranalysis.
-s | -S [filename]
-ns | -NS
(no statistics)
Controls whether UniData includes statistical information aboutthe file in the output file. If you do not specify a filename, UniDatauses GUIDE_STATS.LIS. (UniData assumes the -s (statistics) optionwhen the -o (output) option is present, and may not be specified atthat time.) You may use the -ne (no errors) option in combinationwith the -o option.
Output
The guide utility can create five output files. The following table lists these files. You may change thedefault names.
File Description
GUIDE_ADVICE.LIS Displays management advice about files that are poorly sized orcorrupted.
GUIDE_ERRORS.LIS Lists structural errors detected in the files specified.GUIDE_STATS.LIS Lists statistical information about the files specified.
guide
117
File Description
GUIDE_BRIEF.LIS Displays summary information about selected files, includingrecord counts, total size, used size and modulo.
GUIDE_FIXUP.DAT Produces a list of damaged groups that can be used as input forfixfile. You can also use this list to input file names/group numbersfor dumpgroup/fixgroup.
If you do not specify options, UniData selects the default options: -a, -e, -f, and -s, and places theresults in the default files.
The guide utility checks for existing output files. If there are existing output files, guide appendsa six-digit timestamp to the end of the existing file before it creates the current output file. The mostcurrent output files will not have this time stamp. UniData does not overwrite output files generated ina previous analysis. As a result, you may accumulate a large number of files that will need to be purgedperiodically.
Report file
You can use the -r option of guide to create a UniData file containing statistical information aboutyour 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.
The guide utility creates statistical information in filename about the evaluated files. The recordscontain 62 attributes and are keyed by VOC entry name. You can use UniQuery or ECL commands, orwrite UniBasic code, to analyze the data and produce reports.
Example
The following example shows output from guide executed against a directory that contains adamaged file:
Notice that group 1 of TEST.FILE is damaged.
Chapter 12: Managing UniData files
118
Note: guide works only if UniData is running. Although guide works against recoverable files,guide itself is not recoverable. You must reapply file updates and fixes performed by guideduring recovery from a system or media failure.
guide_ndx
As with other UniData file types, an index file could become corrupt due to hardware failures, theinterruption of a write to the index file, or an incomplete write. The guide_ndx utility checks forphysical and logical corruption of an index file.
Syntax
guide_ndx{-x | -X} {1 | 2 | 3}, {index_names, ... | ALL} [-t template |-T template] filename
Description
If an index file is corrupt, UniData displays a runtime error when a UniData process tries to access theindex. 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 statisticsabout the index. If you have a corrupt index, you must rebuild it using the CREATE.INDEX andBUILD.INDEX commands. For more information and creating and building indexes, see UsingUniData.
Note: We recommend deleting the index with the DELETE.INDEX ALL command. Using the ALLoption deletes all alternate key indexes and the index file itself.
Parameters
The following table describes each parameter of the syntax.
Parameter Description
-x{1 | 2 | 3} Determines the type of checking guide_ndx performs:
1 – Perform physical checking
2 – Perform logical checking
3 – Perform physical and logical checkingindex_names The index names you want guide_ndx to check. Separate each index
name with a comma, or enter ALL to check all indexes for the file.-t template The template to use for output files. The default is GUIDE.filename The name of the data file containing the index.
Example
The following example illustrates the contents of the GUIDE_XERROR.LIS file when guide_ndxdetects corruption:
UniData recovery tools
119
The following table describes the column heading that display in output for the X_STATS.LIS file.
Column heading Description
Index name Name of the index.F-type Type of attribute indexed: D for data attribute, V for a virtual attribute.V-type Value code for the attribute. S for single valued, M for multivalued or
multi-subvalued.K-type Type of index: Txt for text, Num for numeric.Nulls “Yes” indicates that empty strings are indexed. “No” indicates that
empty strings are not indexed.Dups “Yes” indicates that duplicate keys are allowed in the alternate key
index. “No” indicates that duplicate keys are not allowed.F-No/VF-expr The attribute location for alternate key indexes that are built on data
attributes (D-type) or the virtual attribute definition for alternate keyindexes that are built on virtual attributes (V-type).
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.
Chapter 12: Managing UniData files
120
▪ fixgroup — Use this command to clear records from a damaged group, and to reload andrebuild the group with the valid records unloaded by dumpgroup.
▪ fixfile — Use fixfile in conjunction with guide. guide provides a FIXUP.DAT file that listscorrupt files and groups. fixfile uses FIXUP.DAT to unload, clear, and rebuild the damagedgroups.
Note: Although dumpgroup, fixgroup, and fixfile work against UniData recoverablefiles, their actions are not recoverable. If you are recovering from a system crash or mediafailure, any file repairs that took place since your last backup are not included in logs orarchives. You should check your files after recovery (using guide) and perform any neededrepairs before users access them.
dumpgroup
The system-level dumpgroup command unloads readable records from a group you specify in aUniData file. If the file was corrupted, dumpgroup unloads complete, valid records, leaving behindany information it cannot read.
Syntax
dumpgroup filename group.no [-doutputfile] [-p]
Parameters
The following table describes each parameter of the dumpgroup syntax.
Parameter Description
filename Specifies the name of the file containing groups to be dumped.group.no Specifies the number of the group to be dumped. The output
from either guide identifies groups that are damaged. Use thisinformation to select groups to process.
[-doutputfile] Specifies the name of a file that contains the readable records fromthe dumped group, in an uneditable form. If you do not specify the -d parameter with an outputfile, the output prints to screen. To loadoutputfile back into the file, use fixgroup. Note:
Note: No space is allowed between -d and outputfile.[-p] Converts nonprinting field markers to printable characters in
editable output file. This option is only valid if -d is used.
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 specifyan output file, UniData places the records in uneditable form, suitable for reloading, into the outputfile. UniData also creates a UNIX directory within your current account for each dumped group. Thedirectory is named FILE_GROUP, where FILE and GROUP are the file name and group number youspecify on the command line. This directory contains an ASCII file for each record, so that you cancheck them for consistency before reloading the damaged file.
fixgroup
121
Warning: When you use the -d option, make sure you name your output file with a name that doesnot already exist in your account name. If you specify a duplicate name, the preexisting file may beoverwritten.
fixgroup
The system level fixgroup command reloads a hashed file group based on a file created by thedumpgroup command.
Syntax
fixgroup filename group.no [-iinputfile] [-k]
Parameters
The following table describes each parameter of the syntax.
Parameter Description
filename Specifies the name of the file to repair.group.no Indicates the identifying number of the damaged group.[-iinputfile] Specifies the name of the file created by dumpgroup. If you do
not specify an input file argument, fixgroup simply clears thespecified group, without reloading it.
Note: No space is allowed between -i and inputfile.[-k] Allows fixgroup to reload the damaged records from
inputfile without zeroing the group first. This option may be useful ifthe group was updated since dumpgroup was executed. However,for best results, do not allow access to a file while it is beingrepaired, and clear the damaged groups rather than using the -koption.
Warning: If you execute fixgroup without an input file argument, UniData clears the damagedgroup. Be sure that you save the readable records with dumpgroup before clearing the group. Ifyou clear the damaged group and you have not saved the readable records, the data in that groupis lost.
The syntax for clearing a group without reloading it is:
fixgroup filename group.no
UniData displays a warning message before clearing the group, as shown in the following example:
%fixgroup INVENTORY 5Fixgroup INVENTORY 5 will make group 5 empty,do you wish to do it ? [y/n]
Chapter 12: Managing UniData files
122
fixfile
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 guideutility. Do not let users access files while fixfile is running because you could lose records.
Syntax
fixfile {-t | {-dfilename | -k | -p | -f}} [-mfilename] [-wdirectory][-ifilename | filename group.no]
Parameters
The following table describes each parameter of the fixfile syntax.
Parameter Description
{-t} Directs all output to the terminal only. Each readable record isdescribed in a new line that includes the record key and the recordlength. All attributes in the record appear on separate lines, each lineindented by two spaces. Special and nonprintable characters aretranslated as follows:
Attribute Mark — New line
Value Mark — “ } ”
Subvalue Mark — “ | ”
Text Mark — “ { ”
Non-printables — “ . ”
The -t and -d parameters are mutually exclusive and cannot be usedtogether.
{-dfilename} A file specification is required. For static files, the readable records aredumped to this file in uneditable format. For dynamic files, this file iscreated, but the actual records are dumped to a file in \temp/tmp.
With the -d option, UniData also writes the records, in readable format,to a directory in your current UniData account. This directory containsan ASCII file for each readable record in the group. The records are in aformat suitable for editing. To repair any file, you need both the -d and -f options.
{-k} If you specify the -k option with the -d option, the damaged groups arenot cleared. This has the effect of dumping the readable records forexamination, but leaving the file corrupt. If you specify the -d and -foption along with the -k option, UniData repairs the file and returns thereadable records to the group. Any unreadable records that were notdumped remain in the file as well.
{-p} If you specify the -p option with the -d option, all nonprintingcharacters and characters with special meaning to UniData aretranslated. This translation applies to the editable ASCII files created bythe -d option. If you do not specify the -p option, only attribute marksare translated.
How fixfile works with static files
123
Parameter Description
{-f} If you specify the -f option with the -d option, UniData clears thedamaged group and restores the records that were dumped back intothe group, creating a fixed file with all readable data restored. You mustspecify the -d option with the -f option.
[-mfilename] UniData writes all error messages and statistics to the file you specify,instead of the terminal.
[-wdirectory] UniData creates the work files that are generated in the directory youspecify.
{-ifilename} UniData uses this file as the source of the names of damaged files andgroups to be repaired. If you do not use this option or the {filenamegroup.no} option, UniData uses the GUIDE_FIXUP.DAT file under thecurrent directory. This option is mutually exclusive with {filenamegroup.no}.
{filename group.no} The file name and group number that contains the corruption. Ifyou do not use this option or the {-ifilename} option, UniData usesthe GUIDE_FIXUP.DAT file under the current directory. This option ismutually exclusive with the {-ifilename} option.
How fixfile works with static files
When you run fixfile with the -t option on a static file, UniData displays the readable records fromthe file and group to the terminal. The group is not cleared or repaired. You can supply the namesof damaged files and groups from the command line or from an input file. The default input file isGUIDE_FIXUP.DAT.
When you run fixfile with -dfilename on a static file, UniData creates:
▪ A NTFSUNIX directory or directories for the files and groups being repaired. If only one groupin a file is damaged, the directory is named FILE_GROUP where FILE is the damaged file (fromGUIDE_FIXUP.DAT) and GROUP is the damaged group. If several groups in a file are damaged,UniData creates a directory named FILE_dir.▫ Each FILE_GROUP directory contains an ASCII file for every readable record in the damaged
group. Each file name is the key for the corresponding UniData record. These records are in aformat suitable for editing.
▫ Each FILE_dir contains a subdirectory for each damaged group in FILE. The name of eachsubdirectory is the group number of the damaged group. Each subdirectory contains anASCII file for every readable record in the damaged group. Each file name is the key for thecorresponding 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 couldread, in uneditable format. UniData uses this file to reload the records into the damaged groupsafter the groups are cleared.
Note: If you specify the -p option, fixfile translates nonprinting characters in the recordswhen it creates the “editable” files. Otherwise, only attribute marks are translated to new lines.
When you run fixfile with the -d and -f options on a static file, UniData reloads the records into thedamaged 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 specifythe -k option, UniData adds the records back, but does not clear any data from the group.
Chapter 12: Managing UniData files
124
Note: It is possible to run fixfile in two steps, one to dump the records for review and thesecond to repair the file. To dump the records only, run fixfile with the -d option, but withoutthe -f option. Unless you specify the -k option, running fixfile with the -dfilename deletes thereadable data from the specified groups when it creates output. To repair the file, run fixfilewith 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 UNIXNTFS directory for each file-group combination being repaired. The directories are namedFILE_GROUP, where FILE is a damaged file (from GUIDE_FIXUP.DAT) and GROUP is a damagedgroup. 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 formatsuitable for editing.
▪ A file containing the records fixfile could read, in uneditable format suitable for reloading intothe group after it has been cleared. This file is located in \temp/tmp (or in the directory identifiedby the TMP environment variable) and is named ud_dp_pid, where pid is the UNIX process id ofthe process that executed fixfile.
Note: If you specify the -p option, fixfile translates nonprinting characters in the recordswhen it creates the editable files. Otherwise, UniData only translates attribute marks to newlines.
When you run fixfile with the -d and -f options on a dynamic file, UniData reads the file youspecify with the -d option on the command line, and also reads the uneditable file of dumped records.UniData then reloads the records from that file into the damaged groups. Unless you specify the -k option, fixfile clears the groups, removing all contents, before reloading the data. Otherwise,UniData adds the records back, but does not clear any data from the group.
Note: You can run fixfile in two steps, one to dump the records for review and the second torepair the file. To dump the records for review, run fixfile with the -d option, but without the-f option. (You do not need to use -k for dynamic files. For dynamic files, running fixfile with -dfilename and not -f does not delete the readable data from the groups you specify when it createsoutput.) To repair the file, run fixfile with both the -d and -f options. If you specify the samefile name with -d in both the review and repair steps, UniData will prompt whether or not to clearthe damaged groups.
Detection and repair examplesThe following example shows a file called TEST.FILE being repaired using guide and fixfile:
# guide TEST.FILE -na -ns# more GUIDE_ERRORS.LISTEST.FILEFile 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 are inconsistentFiles processed: 1
How to use guide
125
Errors encountered: 3# more GUIDE_FIXUP.DATTEST.FILE4## 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 asystem 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 guideagainst nonrecoverable static hashed files at any time, and schedule guide to run on dynamic filesand 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 conditionin a dynamic file, but they do not mean that the file must be fixed immediately. Users can continueto access the file; this will not cause damage. Complete the repair at a convenient time using theprocedure 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
Chapter 12: Managing UniData files
126
Other guide error messages
guide produces many messages besides the one discussed above. If you see error messagespertaining only to static files, or if you see other error messages pertaining to dynamic files, proceed tostep 3.
3. Repair damaged files
Complete the following steps:
1. Back up the damaged file(s)—If time and space permit, we strongly recommend you back up(or simply make a copy of) the damaged files before proceeding. In the event of a system failureduring the repair process, you will be able to restore from the backup copies and repeat theprocedures, rather than attempting to recover a partially-completed repair.
Caution: 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 ordumpgroup/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 readablerecords back into the group.
Tip: We recommend you not use the -k option with fixfile or with fixgroup. The -k option lets you reload the readable records without clearing the group. However, youmay encounter additional errors if you do not clear the group. Use fixfile or fixgroupwithout -k; this procedure automatically clears the group before reloading the readablerecords.
Warning: Be sure no users are accessing your files before repairing damaged groups. Thedumpgroup command does not obtain exclusive access, and fixfile/fixgroup only lockthe file when the records are being written back to a group. Concurrent access to the file couldmake corruption worse.
3. Verify the repair—Rerun guide after the repair is complete to verify that the errors are fixed. Ifthey 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 to the system.
Error messagesThis section lists error messages you may see, and provides information about the meaning of them.UniData generates these messages from the guide command.
File access messages
127
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 did not process the file because it was unable to obtain anexclusive 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 other links.
These indicate that a block is found to be referenced by more than one link, which should not occur.These messages indicate damage.
The xxth block of file (filename) has no link.the xxth block has no link
A block has been found that is not in the global free chain and is not used by any group. This error canbe reported when guide encounters a corrupt block, and is therefore unable to check blocks linkedthrough 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 blockGroup 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 xxGroup xx, block xx key area is corrupted, incorrect key size xxGroup xx, block xx key area is corrupted, data position xx, key
Chapter 12: Managing UniData files
128
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
The offset (link to next disk block) is not a multiple of the block size, or, for a dynamic file, the offsetdoes not indicate an overflow file offset.
Group xx, block xx data area is corrupted, incorrect data position xxwrong 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 offsetof 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 xxoffsets 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 areinconsistentGroup 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
Free block messages
129
The counter that records the number of bytes available in a block does not agree with the actualnumber 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 shouldhave 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 longrecords 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 lastblock is flagged as “ENDLONG.” If the length of a long record does not match header information, or ifany flag in its data blocks is incorrect or the pointer in the chain gets broken, guide reports messageslike the preceding ones.
130
Chapter 13: Managing UniData locksThis chapter outlines file, record, and system resource locking within UniData, describes tools forlisting locks and listing the contents of the wait queue, and describes procedures for releasing locksthat remain set when a process exits UniData.
The global lock managerThe Global Lock Manager (GLM) is an internal software module that is linked into each udt process tomanage logical record locks.
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 that containlinked lists, which contain lock nodes. When a udt process locks a record, it writes the file name,record ID, and lock mode to both the local lock table and the global lock table. When a udt processrequests a lock, UniData first searches the local lock table for that udt to see if that process is holdingthe lock, then the global lock table to see if another udt process is holding the lock.
GLM udtconfig parameters
Four udtconfig parameters exist that control the size of the shared lock table and thememory UniData allocates for each memory request.
N_GLM_GLOBAL_BUCKETThis parameter defines the number of hash buckets system-wide, used to hold the lock namesin shared memory. This setting directly affects performance. Normally, the default value of thisparameter 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 valueshould be the closest prime number to NUSERS * 3.
N_GLM_SELF_BUCKETThis parameter determines the number of hash buckets for the local lock table, and is highlyapplication-dependent. If the application requires a large number of locks in one transaction (morethan 20), you should increase this setting from the default of 23. The setting should be the closestprime number to the maximum number of locks per transaction.
GLM_MEM_SEGSZThis parameter specifies the segment size for each shared memory segment that is required for GLM.The maximum number of segments is 16. Large application environments require a larger size. Thedefault value is 10.
GLM_MEM_SEGSZ must be greater than 4096 and less than GLM_MEM_SEGSZ. The formula fordetermining GLM_MEM_SEGSZ is NUSERS * maximum number of locks per transaction * 512.GLM_MEM_SEGSZ should be a multiple of 4096.
Locking in UniBasic
131
Locking in UniBasicA series of UniBasic commands allow you to set read-only and exclusive locks on UniData files andtheir contents.
How locks work
UniBasic locks are advisory rather than physical, so they inform other users of a file or record that thefile 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 commands thatwrite and delete. Exclusive locks are set by “U” commands, for instance READU, MATREADU, andRECORDLOCKU.
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 that is locked with an L lockcan be accessed for reading by another “L” command, but cannot be accessed by “U” commands.
Writing and deleting
WRITE and DELETE commands run regardless of lock status. WRITEU, WRITEVU, MATWRITEU, andDELETEU retain locks set by previous commands. To prevent multiple updates to records, you shouldprecede 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 file against access bycommands that check locks.
FILEUNLOCK Unlocks a file that was previously locked with the FILELOCK command.MATREADL Assigns the values that are found in successive attributes of a record to
corresponding elements of a matrix, and sets a read-only lock on therecord.
MATREADU Assigns the values that are found in successive attributes of a record tocorresponding elements of a matrix, and sets an exclusive lock on therecord.
MATWRITE Writes successive elements of a matrix to the corresponding attributes ofa record and releases locks previously set on the record.
MATWRITEU Writes successive elements of a matrix to the corresponding attributes ofa record without releasing locks that were previously set on the record.
Chapter 13: Managing UniData locks
132
Command Description
READBCKL Retrieves one record from a B+ tree-based alternate key index and placesa read-only lock on the record. Each subsequent READBCKU retrieves theprevious record in the index.
READBCKU Retrieves one record from a B+ tree-based alternate key index and placesan exclusive lock on the record. Each subsequent READBCKU retrievesthe previous record in the index.
READFWDL Retrieves one record from a B+ tree-based alternate key index and placesa read-only lock on the record. Each subsequent READBCKU retrieves thenext record in the index.
READFWDU Retrieves one record from a B+ tree-based alternate key index and placesan exclusive lock on the record. Each subsequent READBCKU retrievesthe next record in the index.
READL Reads a specified record from a file, assigning the record contents to adynamic array and setting a read-only lock on the record.
READU Reads a specified record from a file, assigning the record contents to adynamic array and setting an exclusive lock on the record.
READVL Reads a specified attribute of a specified record, assigning the attributevalue to a variable and setting a read-only lock on the record.
READVU Reads a specified attribute of a specified record, assigning the attributevalue to a variable and setting an exclusive lock on the record.
RECORDLOCKL Sets a read-only lock on a specified record in a specified file.RECORDLOCKU Sets a read-only lock on a specified record in a specified file.RELEASE Releases record locks without updating records.WRITE Writes an expression to a record, releasing locks that were previously set
by READU, READL, READVU, and MATREADU.WRITEU Writes an expression to a record without releasing any previous locks on
the record.WRITEV Writes an expression to an attribute of a record, releasing previous
update locks.WRITEVU Writes an expression to an attribute of a record without releasing
previous locks on the record.
Resource locksIn both UniData and UniBasic, you can reserve a system resource by setting a semaphore lock on it.
Note: Certain device handling commands (T.ATT, T.DET, LINE.ATT, and LINE.DET) setsemaphore locks.
The following table lists commands for explicitly reserving system resources from the ECL prompt.
Command Description
UNLOCK Releases system resources that are reserved by the LOCKcommand. (These resources are not automatically released whena program terminates.) This command is not needed to releasefile and record locks.
LOCK
(ECL and UniBasic)
Reserves a system resource for exclusive use.
Listing locks
133
Note: Although the LOCK and UNLOCK commands allow you to set and release semaphore locks,UniData does not necessarily use UNIX system-level semaphores to control access to systemresources. The output from LIST.LOCKS and ipcstat may not appear to be consistent, butUniData is functioning correctly.
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 fileand record locks set on the system.
Syntax
LIST.READU [user_number | ALL | FILENAME filename | USERNAME user_name][DETAIL]
Parameters
The following table describes the parameters of the LIST.READU command.
Parameter Description
user_number Displays all locks that are held by the user number you specify.ALL Displays all currently active locks.FILENAME filename Displays all active locks that are associated with the file name you
specify. If the file name does not reside in the current account, nothingis displayed.
USERNAME user_name Displays all active locks that are associated with the user name youspecify.
DETAIL Displays detailed information.
Examples
The following example illustrates the output from the LIST.READU command when you do notspecify any options:
:LIST.READUUNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME DATE4 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:
Chapter 13: Managing UniData locks
134
The next example illustrates the output from the LIST.READU command when you specify a usernumber. The user number can be found in the output from the LIST.QUEUE and LIST.READUcommands under the UNBR column.
:LIST.READU 6739UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME DATE4 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 TIME DATE5 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 TIME DATE4 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:
LIST.READU display
The following table describes the output from the LIST.READU command.
Column heading Description
UNO The sequential number UniData assigns to the udt process that setthe 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 logon 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 with INBR to define the file at the operating system level.
LIST.LOCKS
135
Column heading Description
RECORD_ID The record ID of the locked record.M The type of lock. X indicates an exclusive lock. S indicates a shared
lock.TIME The time the lock was set.DATE The date the lock was set.
LIST.LOCKS
Use the ECL LIST.LOCKS command to display semaphore-type locks that reserve system resourcesfor exclusive use. These locks can be set individually with the LOCK command. They are also set byother ECL commands, including T.ATT.
Syntax
LIST.LOCKS
The following screen shows the LIST.LOCKS command and its output:
:LIST.LOCKSUNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE1 15290 1172ump01 tyv1 semaphor -1 0 65 X 15:14:01 Jun 03:
Note: If you need to clear a semaphore lock that is left set, you need to note the UNBR and thelock number for the lock. In the example, the lock number is 165 for the lock displayed.
LIST.QUEUE
The ECL LIST.QUEUE command displays a list of all processes waiting to get locks. If a process iswaiting for a lock, LIST.QUEUE displays information about the holder of the lock and processes thatare waiting for the lock. Locks are set by each udt process through the general lock manager (GLM)module. LIST.QUEUE displays the internal table that is 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.
Chapter 13: Managing UniData locks
136
Parameter Description
USERNAME user_name Lists all locks the user is waiting for. user_name is the operatingsystem logon name.
FILENAME filename Lists all users that are waiting for locks for the file name youspecify.
user_number Lists all locks for which the user_number is waiting. The usernumber can be found in the UNBR column of the LIST.READUand LIST.QUEUE output.
DETAIL Displays a detailed listing.
The following example illustrates the output from the LIST.QUEUE command when you do notspecify any parameters.
: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 display
137
: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 usernumber:
: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 above examples use the default display. Information about theowner of the lock is listed above the line. Information about processes that are waiting for the lock islisted below the line, which are 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.
Column Heading Description
FILENAME The name of the file that is holding the lock.RECORD_ID The record ID holding the lock.M Type of lock held. X is an exclusive lock, S is a shared lock.OWNER The user name of the owner of the lock.UNBR The process group ID (pid) of the user who set the lock.UNO The sequential number UniData assigns to the udt process for
the owner of the lock.TTY The terminal device of the user that owns the lock.TIME The time the lock was set.DATE The date the lock was set.
Chapter 13: Managing UniData locks
138
The next table describes the LIST.QUEUE display for the processes that are waiting for locks.
Column Heading Description
FILENAME The name of the file for which a lock is requested.RECORD_ID The record ID of the record for which a lock is requested.M The type of lock requested. X is an exclusive lock, S is a shared
lock.WAITING The user name of the process that is waiting for a lock.UNBR The process ID (pid) of the user that is waiting for a lock.UNO The sequential number UniData assigns to the udt process that is
waiting for a lock.TTY The terminal device of the user that is waiting for a lock.TIME The time the lock was requested.DATE The date the lock was requested.
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 youspecify the DETAIL option.
Column heading Description
FILENAME The name of the file for which a lock is held.RECORD_ID The record ID of the record for which a lock is held.M The type of lock held. X is an exclusive lock, S is a shared lock.INBRH The high integer of the i-node of the file that is holding the lock.INBR The low integer of the i-node of the file that is holding the lock.
The i-node of the file that is holding the lock.DNBR Used with the INBR to define the file that is holding the lock at the
operating system level.OWNER The user name of the process that is holding the lock.UNBR The process ID (pid) of the user that is holding a lock.UNO The sequential number UniData assigns to the udt process that is
holding a lock.TTY The terminal device of the user that is holding a lock.TIME The time the lock was set.DATE The date the lock was set.
Commands for clearing locks
139
The next table describes the output for the LIST.QUEUE command with the DETAIL option forprocesses that are waiting for locks.
Column Heading Description
FILENAME The name of the file for which a lock is requested.RECORD_ID The record ID of the record for which a lock is requested.M The type of lock held. X is an exclusive lock, S is a shared lock.INBRH The high integer of the i-node of the file that is holding the lock.INBR The i-node of the file for which a lock is requested.DNBR Used with the INBR to define the file for which a lock is requested
at the operating system level.WAITING The user name of the process that is requesting a lock.UNBR The process ID (pid) of the user that is requesting a lock.UNO The sequential number UniData assigns to the udt process that is
requesting a lock.TTY The terminal device of the user that is requesting a lock.TIME The time the lock was requested.DATE The date the lock was requested.
Commands for clearing locksIf you break out of a process that is running, if a process is killed, or if a system resource is notunlocked by a UniBasic program, locks can remain after they should have been released. If a lockremains set, other users experience difficulty accessing a record, file, or resource. As other processesattempt to access the locked item, message queue congestion can result if the process that set thelock is no longer logged on to the system. The typical manifestations of unneeded locks are:
▪ Users cannot perform expected operations on a file or record. Over a lengthy period, users receivemessages that indicate that the file or record is locked.
▪ Performance suffers, either because the item that is locked is heavily used or because a messagequeue is clogged because of the lock.
▪ Batch jobs that are 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 that areheld by other users.
SUPERCLEAR.LOCKS Command
SUPERCLEAR.LOCKS enables you to release semaphore locks on system resources (such as tapedrives).
Syntax
SUPERCLEAR.LOCKS usrnbr [locknum]
The following table describes each parameter of the syntax.
Chapter 13: Managing UniData locks
140
Parameter Description
usrnbr The UNIX process ID (pid) that holds the lock. This number is UNBRin the LIST.LOCKS display.
[locknum] The number of the locked system resource. If you do not specifylocknum the command clears all locks set by usrnbr.
The following example shows the effects of SUPERCLEAR.LOCKS:
:LIST.LOCKSUNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01 Jun 033 15692 1172ump01 tyv4 semaphor -1 0 66 X 16:27:01 Jun 03::SUPERCLEAR.LOCKS 15692 -1:LIST.LOCKSUNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01 Jun 03:
SUPERRELEASE commandThe SUPERRELEASE command enables you to release locks are set on records.
Syntax
SUPERRELEASE usrnbr [inbr devnum ] [record.id]
The following table describes each parameter of the syntax:
Parameter Description
usrnbr The UNIX process ID (pid) that holds the lock. This number is UNBRin the LIST.LOCKS display.
[inbr devnum] The i-node number and device number for the file that has the lockset. These numbers are INBRH, INBR and DNBR in the LIST.READUdisplay.
[record.id] The identifier for the record to clear. This number is RECORD ID inthe LIST.READU display.
[locknum] The number of the locked system resource. If you do not specifylocknum the command clears all locks set by usrnbr.
Note: If you run SUPERRELEASE and specify only usrnbr, you release all record locks held by theprocess ID corresponding to usrnbr.
The following example shows the effect of SUPERRELEASE:
:LIST.READU
Procedure for clearing locks
141
UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME DATE1 4178 1172 clair ttyp2 INVENTOR 24193 10738 10060 X 13:28:40 Sep 242 4180 1172 clair ttyp1 INVENTOR 24193 10738 10055 X 13:30:20 Sep 24:SUPERRELEASE 4180:LIST.READUUNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME DATE1 4178 1172 clair ttyp2 INVENTOR 24193 10738 10060 X 13:28:40 Sep 24
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 thesystem. Use LIST.QUEUE to identify locks for which processes are waiting. Note locks that meet thefollowing criteria:
▪ They are set on files or records that users cannot currently access.
▪ They have been set for a long period (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 theUniData 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 locknumber. To clear record locks, proceed to step 3. To clear semaphore locks, proceed to step 4.
3. Release record locks
Log on as an administratorroot and use the UniData SUPERRELEASE command to clear recordlocks. If possible, specify only a UNBR to clear all the locks that belong to a process ID. If you havesemaphore locks to clear, proceed to step 4. Otherwise, proceed to step 5.
Warning: Some situations that retain locks can also cause file corruption (for example, a udtprocess is inadvertently killed). Consider checking the file with guide to make certain it is notcorrupted.
4. Clear semaphore locks
Log on as an administratorroot and clear semaphore locks with the SUPERCLEAR.LOCKS command.
Chapter 13: Managing UniData locks
142
5. Check for message queue congestion
Some conditions that cause locks to remain set also cause message queue congestion when otherprocesses attempt to access the locked item.
Refer to Managing ipc facilities, on page 184 for step-by-step instructions for identifying and clearingcongested message queues.
143
Chapter 14: Managing UniData usersThis 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, and to start and stop UniData.
Adding users
Every user needs a login ID
To access UniData on your system, you need a valid UNIX account, including a UNIX logon ID andpassword. In Pick systems, where each login account must be a Pick account, shared login IDs andpasswords are common. In contrast, UniData allows multiple relationships between user login IDs andUniData accounts. A user may have access to more than one UniData account, and many users canaccess a single UniData account by using separate UNIX logon IDs. Therefore, we strongly recommendyou set up a separate UNIX account for each user. We recommend separate logon IDs for the followingreasons:
▪ Since most operating systems impose limits on the number of processes that can be associatedwith one user, using separate logon IDs allows your system to run more processes at one time.
▪ It is easier to identify processes and locks belonging to an individual user, which facilitatestroubleshooting.
▪ Using separate logon IDs allows you to define your users’ responsibilities for protecting theirpasswords and your application data.
Create logon IDs at the UNIX level
No UniData commands or procedures exist for setting up UNIX user accounts. Although the basicprocess for creating a UNIX account is similar across UNIX versions, different system configurationsmay use different utilities or third-party interfaces for the actual mechanics. Refer to your hostoperating system and vendor documentation to determine the correct procedure at your site.
When you set up UNIX login IDS, consider the following factors:
▪ 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: We recommend that if some or all of your users require access to the UNIX shell prompt,or if they are doing development or maintenance programming, their home directory shouldnot be a UniData account that contains production data or programs.
Chapter 14: Managing UniData users
144
Warning: In some configurations, proprietary utilities are in use to automate many of thesteps for adding or deleting a user. Make sure that your utilities are clearly documented andunderstood. If you have a utility that deletes a user’s home directory when that user’s accountis removed, for example, you could suffer data loss if you use 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 permissionsallow differentiation of access between members of a group owner and users who are not members ofthat group.
Refer to UniData and UNIX security, on page 13 and Managing UniData security, on page 75 for moreinformation about groups.
Note: The UNIX commands finger and groups display information about users. Refer to your hostoperating system documentation for information about these commands.
Monitoring user processesFor troubleshooting purposes, it is often necessary to identify and monitor processes that are ownedby a particular UniData user.
UniData commands
UniData includes a group of commands to display a list of current UniData sessions, to display a listof users that are currently logged on to the system, and to display detailed information about processactivity for a specific user, or for all users.
The following table summarizes these UniData commands.
UniData command Description
WHO ECL command that displays a list of users currently logged on to thesystem, including users who are not UniData users.
ECL command; similar to the UNIX who command; displays a list of usersthat are currently logged on to the system, including users who are notUniData users.
LISTUSER ECL command that displays a list of current UniData sessions.
ECL command; displays a list of current UniData sessions.listuser UniData system-level command that you enter at an MS-DOS prompt;
displays the same information as the ECL LISTUSER command.
UniData system-level command; enter at a UNIX prompt; displays thesame information as the ECL LISTUSER command.
udstat UniData system-level command; displays detailed activity statisticsabout a single UniData process or about all UniData processes.
MYSELF ECL command; similar to the UNIX whoami command.
ECL command that displays login ID for the current UniData session.
Removing user processes
145
Note: You do not need to be logged on as an administratorroot to run these commands.
The following screen shows the system response to the WHO, LISTUSER, and listuser commands.
:WHO:WHOrwatson pts/0 Nov 16 18:34 (denkingfish.u2lab.rs.com)rwatson pts/1 Nov 28 10:20 (rxterm.u2lab.rs.com)rwatson pts/2 Dec 12 14:29 (denkingfish.u2lab.rs.com)rwatson pts/3 Nov 28 10:22 (rxterm.u2lab.rs.com)CGustafs pts/4 Jan 04 11:22 (vulture.u2lab.rs.com)bvilensk pts/5 Nov 28 14:26 (tsaixpub.u2lab.rs.com)rwatson pts/6 Dec 15 13:43 (denkingfish.u2lab.rs.com):LISTUSER
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 usernumber), USRNBR (the UNIX pid), UID (the user’s UNIX uid number), and USRNAME. Displaying furtherinformation about a UniData process typically requires the UNIX pid (USRNBR).
Removing user processesUniData includes commands that enable you to stop a user’s udt process if the process is hung, or ifyou need to stop UniData while a user is still logged on to the system. The following table summarizesthese commands.
UniData command Description
stopudt Logs a user out of UniData; a current write is allowed to complete,but subsequent operations for that udt do not take place.stopudt uses the UNIX kill -15 command.
deleteuser First attempts to issue the UNIX kill -15 command. If the commandis not successful in five seconds, force logs a user out of UniDatawith the UNIX kill -9 command; may interrupt a write in progress,potentially causing file corruption.
Chapter 14: Managing UniData users
146
The UNIX kill command enables you to stop a process with various options. Use this command withcaution, since it can cause data inconsistency and file corruption. Refer to your host operating systemdocumentation for information about the kill command.
You can log yourself out using the stopudt command, but you must be logged on as root to log outother users by using stopudt. You must be logged on as root to run 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 substitute fornormal user logout.
Tip: You can use the UniData system-level command udstat to check the activity of a UniDataprocess. If the process shows activity, stopping or deleting it could damage data. See the UniDataCommands Reference for examples of the udstat command. Communicate directly with theowner, if possible, before you stop a udt process, because even if the process seems to be idle, theterminal may be waiting for input and files may be open.
Using TIMEOUT
You can run the ECL TIMEOUT command at the ECL prompt, in a LOGIN paragraph, or in a UniBasicprogram. 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 someimproved security for terminals left idle.
Warning: Be careful with TIMEOUT. Because this command can cause a UniBasic program toterminate at an INPUT statement rather than concluding normally, using TIMEOUT can causeinconsistent data in your database.
147
Chapter 15: Managing printers in UniDataThis chapter explains how UniData interacts with UNIXWindows spooler software and describes howto configure and access printers from within UniData.
UniData and UNIX spoolersAll printing from within UniData is performed by your UNIX system spooler. UniData does not includeits 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 BSDspooling system, which includes the lpd, lpc, and lpr commands, and the ATT spooling system, whichincludes the lp command. The spooling system for any UNIX version is likely to be derived from oneor 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, althoughunderlying processing is accomplished by one or the other type. Refer to your host operating systemdocumentation for information about the spooler on your UNIX system.
Users can specify any UNIX spooler command that is supported on their system by using the ECLcommand SETOSPRINTER, and defining the spooler configuration file.
Configuring the spooler
UniData includes a spooler configuration file, UDTSPOOL.CONFIG, located in udthome/sys. This filecontains information for the interface between the UniData SETPTR command and the UNIX-levelprint commands. The UDTSPOOL.CONFIG file contains interface information for the lp command oneach system. For some systems, UDTSPOOL.CONFIG also contains information for the lpr command.
The following example illustrates the UDTSPOOL.CONFIG file:
Chapter 15: Managing printers in UniData
148
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 commandoptions that correspond to typical SETPTR options. Within each entry, the “DEFAULT” lineindicates options that the spooler should always include.
▪ In the first entry for lp, the lp command is identified as DEFAULT. This identification directs UniDatato use lp as the spooler command unless you specify another command.
You can modify the UDTSPOOL.CONFIG file by using any UNIX text editor. You can add spoolercommands, modify the existing entries, and change the command that is identified as the DEFAULT.
If a particular option is not available with your spooler command, and you do not want UniData todisplay an error message each time you invoke your spooler command, you can specify U_IGNOREnext to the unsupported option. In the following example, the NHEAD option in the lp command hasa value of U_IGNORE. Therefore, UniData ignores the NHEAD option, even if you specify it with theSETPTR or SP.ASSIGN commands:
Enabling and disabling printers
149
Enabling and disabling printers
The PTRENABLE and PTRDISABLE commands issue platform-dependent UNIX commands toenable and disable a printer, respectively. You may add the appropriate UNIX commands to theUDTSPOOL.CONFIG file for your platform, as shown in the following example:
Chapter 15: Managing printers in UniData
150
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"
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/ud82/sys/UDTSPOOL.CONFIG.
Spooling from UniData
Print requests from within UniData are generated by UniBasic commands (PRINT, PRINT ON) and byusing 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 that contains theoutput to be printed. This temporary file is created by default in the /tmp directory. If you definethe UniData configuration parameter TMP, UniData creates the print file in the location that isspecified by TMP. You can override this setting by setting the environment variable TMP at the UNIXprompt before you enter UniData.
Note: If you run SETPTR and set the printer mode to 3 or 6, UniData creates the 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 forthe 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 outputmay not reflect changes that are made to your database after the print request was issued.)
▪ After the output is printed, UniData deletes the temporary file.
UniData printing commands
Note: UniData includes a number of commands that enable you to customize output fromUniBasic programs and UniQuery reports. See the UDT.OPTIONS Commands Reference for acomplete listing of all available options.
Configuring and troubleshooting a printer
151
Command Description
LIMIT Displays the current spooler setting that is used for printing.SETOSPRINTER Selects a UNIX spooler command.SETPTR Defines logical printer units within a UniData session and displays the
current spooler setting.SPOOL Prints the contents of a record to the printer.PTRDISABLE, STOPPTR,or SP.STOPLPTR
Disables a UNIX printer or queue. These commands are equivalent toyour spooling system’s disable command. You must supply a printeror queue ID that is defined to your spooler. Do not supply a UniDatalogical print unit number.
PTRENABLE, STARTPTR,or SP.STARTLPTR
Enables a UNIX printer or queue. The commands are equivalent toyour spooling system’s enable command. You must supply a printeror queue ID that is defined to your spooler. Do not supply a UniDatalogical print unit number.
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 cancel nnn, where
nnn is the job number.SP.OPEN Opens a continuous print job. This command is equivalent to the
UniData SETPTR ,,,,,,OPEN command.SP.STATUS Provides printer and queue information. This command is equivalent
to UNIX lpstat -t.LISTPTR Prints the names of printers and paths of devices that are associated
with them. This command is equivalent to UNIX lpstat -v.LISTPEQS or SP.LISTQ Prints the status of the output request. These commands are
equivalent to UNIX lpstat -o.
Note: See the UniData Commands Reference for the syntax of these ECL commands.
Configuring and troubleshooting a printerIn order for any user to print to a printer from UniData, all the following conditions must be true. Usethese 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 contentsof the file print successfully. For example, assume you have a file that is called textfile and a printer
Chapter 15: Managing printers in UniData
152
that is attached to /dev/tty01; enter cat textfile > /dev/tty01 at the UNIX prompt to test theconnection.
Refer to your host operating system documentation and your printer documentation for informationabout connecting and troubleshooting a printer.
Troubleshooting
▪ Use the UNIX lpstat command to determine if the printer is defined. Check your documentation tolearn which option of lpstat to use.
▪ Attempt to spool a text file to the printer by using the default print command (for example, lp -c -dqueuename textfile). If you added the printer as a member of a device class, spooling to thedevice class sends the job to the first available member of that class, which may not be the desiredprinter.
Note: Refer to your host operating system documentation for information about your spoolingsystem. Because different UNIX versions include different spooling systems, procedures fordefining a printer to a spooler vary.
Spooler definition
You must define the printer to your UNIX spooler. Depending on your spooling system, a printer can bea discrete destination or a member of a device class.
▪ Use the UNIX lpstat command to determine if the printer is defined. Check your documentationto learn which option of lpstat to use.
▪ Attempt to spool a text file to the printer by using the default print command (for example, lp -c -dqueuename textfile). If you added the printer as a member of a device class, spoolingto the device class sends the job to the first available member of that class, which may not be thedesired printer.
Note: Refer to your host operating system documentation for information about your spoolingsystem. Because different UNIX versions include different spooling systems, procedures fordefining 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, orqueue, to an internal print unit in UniData.
Use the ECL SETPTR command for this. See SETPTR, on page 153.
Note: If you do not define a specific printer or queue with SETPTR, UniData directs output fromUniBasic PRINT statements (following PRINTER ON statements), or from UniQuery statementswith the LPTR option, to the default printer or queue on your system.
SETPTR
153
SETPTRThe SETPTR command enables you to define “logical printer units” within a UniData session. Alogical printer unit is a combination of a printer destination, a form type, page dimensions, and moreoptions. By varying form type and options, you can define more than one logical printer unit for asingle physical printer.
With SETPTR, you can define up to 31 logical printer units in a single UniData session. ThroughoutUniData, 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.
Parameter Description
unit Logical printer unit number; internal to UniData; you can map thisunit number to a UNIX printer or queue with the DEST and FORMoptions. Must range from 0 through 254; default is 0.
[width] Number of characters per line; must be within the range 0-256;default is 132.
[length] Number of lines per page; must be within the range 1-32,767 lines;default is 60.
[topmargin] The number of lines to leave blank at the top of each page; must bewithin the range 0-25; default is 3.
[bottommargin] The number of lines to leave blank at the bottom of each page; mustbe within the range 0-25; default is 3.
[mode] Enables more flexibility to direct output; default is 1; see separatetable.
[“spooleroptions”] Enables you to specify desired spooler options as a quoted string,which UniData then passes directly to the UNIX spooler.
[options] Enables you to specify printing options that UniData then interpretsand passes to the UNIX spooler. See separate table.
Note: Users familiar with Pick conventions should be aware that printer unit numbers set withSETPTR are not the same as Pick printer numbers. SETPTR enables you to define logical printerunits, which may be linked to specific printers. UniData printer unit numbers are used with thePRINT ON statement in UniBasic to allow multiple concurrent jobs. Pick printers (forms) arespecified with the DEST option of SP.ASSIGN.
The next table describes modes for SETPTR.
Mode Description
1 Directs output to a line printer only.2 Must be used with DEVICE option; directs output to the serial device
specified by the DEVICE option.3 Directs output to a _HOLD_ file only.6 Directs output to both a _HOLD_ file and a line printer.9 Directs output to a line printer; suppresses display of the _HOLD_
entry name.
Chapter 15: Managing printers in UniData
154
The next table describes options for the SETPTR command.
Option Description
BANNER [string] Modifies the default banner line (which is the UNIX user ID).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_ fileto create unique entry names for jobs that are sent to _HOLD_.
BRIEF Directs UniData not to prompt for verification upon executionof SETPTR.
COPIES n Prints n copies of the print job.DEFER [time] Delays printing until the specified time. Refer to your host
operating system documentation for the correct syntax forspecifying time. You need the documentation for the UNIX atcommand.
DEST unit (or AT unit) Directs output to a specific printer or queue. The unit mustbe a valid destination at your site. Refer to your spoolerdocumentation, and use the UNIX lpstat command forinformation about valid destinations.
DEVICE filename Used with mode 2 only. Directs output to the UNIX devicewhose 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 must be
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.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 the file is
closed by the SP.CLOSE command.
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 logicalprinters by setting the NOCHKLPREQ environment variable. (UniData concatenates DEST and FORMbefore validation, since many logical printers can access a single physical printer or queue.) Onsystems with hundreds of print units that are defined in the UNIX spooler, the UniData validation cantake so much time that it is a processing bottleneck. In such cases, setting NOCHKLPREQ removes thebottleneck. Use the following commands to set NOCHKLPREQ:
Bourne or Korn Shell:
NOCHKLPREQ=1;export NOCHKLPREQ
C shell:
Defining an alternate search path
155
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 printjobs, by specifying invalid DEST/FORM combinations. It is safest to disable checking if you run yourSETPTR commands in a paragraph or a UniBasic program rather than manually, and if you test alloptions before implementing them in production.
Defining an alternate search path
The LPREQ environment variable enables you to provide an alternate search path for DEST/FORMvalidation. UniData automatically searches the default directory for your UNIX environment (forinstance, on an HP-UX system, the directory /usr/spool/lp/request). If you wish to use adifferent directory, use LPREQ.
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 thedefault. The SETPTR command enables you to redefine unit 0 to direct output from different parts ofan application to different physical printers or queues, or to change formatting options. The followingexample 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:
Notice the following points:
▪ Both “laser” and “laserinvoice” must be valid destinations that are defined to your UNIX spooler. Ifyou have defined NOCHKLPREQ, invalid destinations cause print jobs to fail. If you did not defineNOCHKLPREQ, 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 singlephysical 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 canuse this functionality to submit concurrent print jobs from a UniBasic application. One commonimplementation follows:
Chapter 15: Managing printers in UniData
156
▪ 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 byPRINT 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 commandshows 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 canbe a terminal, a serial printer, a tape drive, or a disk file. If writing to an actual device, you must specifythe device special file. If you want to spool to a disk file, you must specify the full path of the file.
Passing spooler options to UNIX
The SETPTR command enables you to use any option that is accepted by your default UNIX spoolercommand, by specifying the options as a quoted string on the SETPTR command line. The followingsample command uses the spooler options for banner title (-t) and for copies (-c) directly, rather thanthe 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.
Decoding a UniData print statement
157
Tip: Use the ECL LIMIT command or the SETPTR command to display the default spoolercommand in your UniData release, and then refer to your host operating system documentationfor supported options for that command.
Decoding a UniData print statementTo research printing problems within UniData, it is sometimes helpful to determine what argumentsUniData is passing to your UNIX spooler. If your system has a C compiler, you can code and compilea C program that functions as a “dummy” spooler. This program interprets UniData commands andreports arguments, but does not actually perform any spooling. By running the dummy programinstead of your default spooler command, you can test UniBasic PRINT statements or UniQueryreports to determine how UniData interprets your printing configuration. Complete the followingsteps 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 that are allowed in paragraph = 60....:SETPTRUnit 0Width 132Length 60Top margin 3Bot margin 3Mode 1Options 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 atthe bottom of the screen.
Chapter 15: Managing printers in UniData
158
2. Create the C program
The following C program, called prtarg.c, captures the arguments that a UniData or UniBasicprinting command sends to your UNIX spooler. Use vi or any UNIX text editor to create the program ina 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 matchesyour default spooler command. In the above example, the spooler command was lp. For some UNIXversions, the command may be different. Use the cc -o command to compile the program, asshown in the next example:
# cc -o /usr/ud82/work/lp prtarg.c# cd /usr/ud82/work# ls -l lp-rwxrwxrwx 1 root sys 16384 Jun 4 10:56 lp#
4. Redefine your path
To run the dummy spooler instead of the UNIX spooler, you need to redefine your execution path sothat UNIX locates the dummy version before the real version. The work directory where the dummyversion 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 runs in place of the default version.
5. Test UniData printing
159
5. Test UniData printing
With your execution path redefined, log on to a UniData account and test printing commands. Thefollowing screen shows sample output from the dummy spooler for a UniQuery report statement thatincludes the LPTR keyword, and from a UniBasic PRINT statement:
:SETPTR 0Unit 0Width 80Length 60Top margin 3Bot margin 3Mode 1
Options are:Destination laserSpooler & 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:
6. Reset your execution path
When you complete a testing session, make sure you reset your execution path so that the actualspooler command runs rather than the dummy spooler program.
160
Chapter 16: Accessing UNIX devicesThis chapter describes UniData commands for identifying and accessing UNIX tape devices. Thischapter also describes commands for reading and writing to other UNIX devices, which you can use fortransferring data and also for debugging UniBasic applications.
UniData tape handling commandsUniData includes a number of ECL and UniBasic commands for reading data from a tape and writingdata to a tape. The following table summarizes these ECL commands.
Command Description
SETTAPE Defines a logical tape unit in UniData; requires root access; mustprecede all other tape commands.
T.ATT Links a logical tape unit to a UniData process; must precede anyreads/writes involving the tape.
T.BAK Moves a tape backward a specified number of files.T.CHK or T.CHECK Reads a tape that is created by T.DUMP and check for damage.T.DET Releases a logical tape unit when a UniData process is finished
with it.T.DUMP Copies the contents of a file or active select list to tape.T.EOD Moves a tape to end of file.T.FWD Moves a tape to the beginning of the next file.T.LOAD Loads records from a tape that is created with T.DUMP.T.RDLBL Reads and displays the first 80 characters of the tape label on a
tape that was 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.
Note: See the UniData Commands Reference for information about ECL commands.
The next table summarizes UniBasic commands for I/O on tape devices.
Command Description
READT Reads the next available record from tape.RESIZET Changes the block size that is 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 a tape.
Note: See the UniBasic Commands Reference for information about these UniBasic commands.
SETTAPE
161
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. Youcan use SETTAPE to relate unit numbers to tape devices or UNIX disk files.
Any user can run SETTAPE unit.no to display the current settings for a tape unit. However, youmust log on as root to define a tape unit or modify settings.
Once you define a tape unit by using SETTAPE, users can access it in any UniData account on yoursystem. 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.
Parameter Description
unit.no Internal UniData tape unit number. Must be within the range 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. The default
value is 4096.
Steps for tape device useFollow these steps to use tape devices from UniData:
1. Define tape units
Log on as root and run the SETTAPE command to define up to 10 tape units for the UniDataenvironment.
The tape unit number must be within the range 0-9. These numbers are logical tape unit numberswithin UniData; the SETTAPE command maps these numbers to UNIX files.
Note: When you define tape units, be sure to define unit 0. Some of the UniData tape handlingcommands 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 textfile udthome/sys/tapeinfo.
2. Attach a tape device
You need to attach a logical tape device to your process before you access it. The T.ATT commandattaches a tape device. Any user can run T.ATT from the ECL prompt or from within a UniBasicprogram. The following example shows typical output from T.ATT:
:T.ATT 7No information for unit 7 yet, ask your system administrator for help.
Chapter 16: Accessing UNIX devices
162
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.
▪ You can run T.ATT repeatedly to change the tape block size and tape length. If you do not specifyBLKSIZE, T.ATT uses the default block size that is specified in SETTAPE.
▪ Only one process can attach a tape unit at any time. You can attach more than one tape unit to asingle 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 onesare attached and which ones are available. The following example shows sample output fromT.STATUS:
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 followingexample shows typical output when a process with tape unit 4 attached runs the ECL T.DUMPcommand:
4. Release the tape device
163
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 thanone device, you need to specify the device to write to or read from. If you have attached only onedevice, UniData accesses the device that 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 properly connectedor if no tape is mounted. The UniData T.ATT and SETTAPE commands do not detect deviceconfiguration problems, so you may be able to define and attach a device, but be unable tocomplete your access to it.
Tip: Because of the differences in Pick® operating systems and manufactured tapes, wesuggest you use the HDR.SUPP keyword when you are using the T.DUMP command, and whenyou are 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 anotherprocess can use it. If you have attached more than one device, you need to release each oneseparately. If you have attached only one, the T.DET command releases it. You can run T.DET fromECL or from within a UniBasic program.
UniData LINE commandsUniData includes a group of commands that enable you to read from and write to UNIX tty-typedevices. These commands are used to define and attach line devices for use by the UniBasic GET andSEND commands. GET and SEND allow UniBasic programs to read data from or write data to serialdevices such as scales or bar code readers.
Chapter 16: Accessing UNIX devices
164
Note: You can use GET and SEND and the LINE commands to communicate with a printer orterminal.
The following table describes the UniData commands.
Command Description
SETLINE Defines a UNIX tty device within UniData; requires root access; mustprecede all other line commands.
LINE.ATT Links a defined device to a UniData process; must precede all reads/writes involving the line.
PROTOCOL Displays or modifies data line transmission characteristics of anattached 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.
Note: See the UniData Commands Reference for detailed information about the UniData LINEcommands.
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. UseLINE.STATUS to verify pointers and determine which lines may be attached to processes. You mustlog on as root to create or modify a pointer. The following example shows an example of SETLINEand LINE.STATUS:
Note: To access a tty device from UniBasic, the device must be assigned a tty number.
2. Attach the line to your process
165
When you run 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.
2. Attach the line to your process
Use the LINE.ATT command, either before you run your UniBasic program or within your UniBasicprogram, to reserve a line for your process. Again, you can use LINE.STATUS to verify the line, asshown below:
Note: Once you attach the line, you can run the ECL PROTOCOL command to define itstransmission characteristics. When you modify these characteristics, be aware that the values youspecify remain in effect until modified again by another PROTOCOL command. You may wish torun PROTOCOL after every LINE.ATT, to ensure that the transmission characteristics are correctfor your application.
3. Access the line
In your UniBasic application, use the GET command to retrieve data from your tty device and theSEND 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 releasethe tty device.
Dual-terminal debugging in UniBasicIf you are debugging a UniBasic application that performs terminal I/O, it is often more efficientto display debugger messages on a separate screen from the application. The following tablesummarizes ECL commands for dual-terminal debugging.
Chapter 16: Accessing UNIX devices
166
Command Description
SETDEBUGLINE Sets a pointer to the terminal or window where you want debuggermessages to display.
DEBUGLINE.ATT Connects to the terminal or window you specify withSETDEBUGLINE.
DEBUGLINE.DET Detaches from the terminal or window to which you are connected.UNSETDEBUGLINE Removes the pointer that you set with SETDEBUGLINE.
You do not need to log on as root to run these commands.
Note: See the UniData Commands Reference for detailed information about the ECL commands fordual-terminal debugging, and see Using the UniBasic Debugger for information about the UniBasicdebugger.
Setting up dual-terminal debuggingComplete the following steps to set up a dual-terminal debugging session.
1. Log on to two terminals (or Windows)
▪ You need to log on to two terminals or windows.
▪ You do not need to log on to UniData on the terminal where you 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 isrunning 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 defined.
4. Conduct the debugging session
The following two screens show dual-terminal debugging. On the first screen, a UniBasic program isrun with the -D option:
:DEBUGLINE.ATT
5. Detach from the display terminal
167
: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 by using DEBUGLINE.ATT, if your debug line is still set.
6. Release the display terminal
At the end of your debugging session, run the ECL UNSETDEBUGLINE command to remove thepointer to the display terminal.
168
Chapter 17: Managing memoryThis chapter describes UniData commands and utilities for configuring, monitoring, andtroubleshooting shared memory. The chapter also lists UniData error messages that are related toshared memory, and presents suggestions for resolving the errors.
The following commands and utilities enable you to monitor the use of shared memory on yoursystem and provide suggestions for configuration and tuning.
UniData monitoring/configuring toolsThe udtconf utility enables you to automatically set all udtconfig parameters, including thoseparameters for shared memory. Although shared memory requirements are highly application andplatform dependent, udtconf can provide suggestions for udtconfig parameters and provideinformation about the actual state of your system.
Syntax
udtconf
You do not have to log on as root to run udtconf, but the utility reads information from theudtconfig file, which is located in /usr/ud82/include, and from the UNIX kernel. If you do notlog on as root, you may not have sufficient access to the kernel, and the results are unreliable.
You should run udtconf with UniData users logged off, and UniData shut down. The one exceptionis to assess the impact of the Recoverable File System (RFS) system buffer. In this case, run udtconffrom a UNIX prompt while UniData is running.
udtconf main display
The following example shows the main screen of the udtconf utility:
Calculating udtconfig parameters
169
To advance to a field displayed on the screen, press Tab. To page down, press Ctrl+D. To page up,press Ctrl+U.
If some of the kernel parameters are not adequate to support the values udtconf calculates, theudtconf utility displays warning messages. Make sure that the kernel parameter for semaphore undostructures, usually semmnu, is adequate to support the number of authorized users before runningudtconf.
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. Althoughudtconf 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 forudtconfig parameters that are dependent upon the value you change. To calculate parameters,enter Ctrl+A.
Checking configuration parameters
Press Ctrl+K to check the UniData configuration parameters against the kernel parameters. If aUniData configuration parameter cannot be supported by a kernel parameter setting, UniDatadisplays a warning message at the bottom of the screen for each conflicting parameter, as shown inthe following example:
When all configuration parameters have been checked, UniData displays the message “Sharedmemory related configuration values are OK!”
Chapter 17: Managing memory
170
Saving configuration parameters
Press Ctrl+V to save the configuration parameters to the udtconfig file, which is located in /usr/ud82/include. If you do not save the parameters, no changes are made to the udtconfigfile.
Recalculating the size of the CTL
Press Ctrl+L from any udtconf screen to recalculate the size of your global control table, CTL. Thistable 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 udtconfigparameter 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 showssample output:
udtconf suggests values assuming that UniData is the only software product on your system. If thatis true, if the current kernel settings for semaphore undo structures, shared memory segments, andso forth, are at least equal to the suggested values, it should not be necessary to rebuild your kernel.If you have more applications that are running, you need to consider the combined effect of UniDataand all other applications when you are evaluating your kernel settings.
Exiting udtconf
To exit the udtconf utility, enter Ctrl+E. If you changed configuration parameters, make sure to savethe changes by using Ctrl+V before you exit the program.
Setting shared memory parameters
171
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 memorythrough shmconf. Although its usability for this purpose is platform-dependent and application-dependent, the utility provides configuration suggestions and information about the actual state ofyour system.
Syntax
shmconf
You do not need to log on as root to run shmconf, but the utility reads information from udtconfigparameters and from the UNIX kernel. If you do not log on as root, you may not have sufficient accessto the kernel, and the results are unreliable.
In general, you should run shmconf with UniData users logged off and UniData shut down. The oneexception is to assess the impact of the RFS system buffer. In this case, run shmconf from the UNIXprompt 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:
Note: Most of the figures that are displayed are current values that are read from UniDataconfiguration parameters. The value of SHMMAX, however, is empirically determined by theshmconf program, which tests to determine the largest shared memory segment available on thesystem.
Chapter 17: Managing memory
172
Tip: If the value of SHMMAX on this screen is significantly smaller than your kernel configuration(see next example), other applications may be reserving shared memory, or you may haveinsufficient swap space.
shmconf: viewing current and suggested settings
To view current and suggested UNIX kernel settings, press Ctrl+P. The following screen shows sampleoutput:
Note: shmconf suggests values assuming that UniData is the only software product on yoursystem. If that is true, if the current kernel settings for semaphore undo structures, shared memorysegments, and so forth, are at least equal to the suggested values, it should not be necessaryto rebuild your kernel. If you have more applications that are running, you need to consider thecombined effect of UniData and all other applications when you evaluate 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 theUniData configuration parameter SHM_MAX_SIZE), UniData will not start.
shmconf: Recalculating other parameters
173
shmconf: Recalculating other parameters
shmconf also enables you to recalculate parameters that are related to shared memory. Press Ctrl+Afrom any screen to do so.
Note: shmconf recalculates parameters, but does not update the udtconfig file unless youspecify 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 memorythat is required for the system buffer. UniData reserves this memory during startup, and it is notavailable to the smm or sbcs daemons. If your system was running close to its limits in terms ofmemory resources without RFS, allocating the system buffer can have a significant impact. Forinstance, you may see an increase in error messages that indicate smm could not create or attach ashared memory segment.
Analyzing UniData configuration parameters
The system-level systest command checks all parameters in the udtconfig file, which is locatedin /usr/ud82/include.
Syntax
systest [-mn] [-sn] [-u] [-f filename] [-v] [c {n|r}]
The following table describes each parameter of the syntax:
Parameter Description
[-mn] Changes memory map display by about n MB. Highly platformdependent. Do not use this parameter unless advised by TechnicalSupport.
[-sn] Changes memory map display by about n MB. Highly platformdependent. Do not use this parameter unless advised by TechnicalSupport.
[-u] Creates or updates the UniData the configuration parametersNFILES and/or SHM_ATT_ADD. Use with extreme caution.
[-f filename] Creates a file name that you specify containing the UniDataconfiguration parameters systest recommends for the number ofauthorized users and platform.
[-v] Displays detailed (verbose) output.[-c {n|r}] Checks current kernel parameter settings against UniData
recommendations. Specify the -cr option to compare againstrecommendations for the Recoverable File System. If you will not beusing recoverable files, specify the -cn option.
Chapter 17: Managing memory
174
Note: The -m and -s options of systest function differently on different platforms and also functiondifferently depending on machine activity. These options help you assess the effects of redefiningmemory addresses on your system. However, different UNIX versions handle memory allocation sodifferently that these options may not produce meaningful output. Do not use them unless advisedby Technical Support.
You must log on as root to run systest. Users do not need to log out of UniData.
The following example shows sample output from the systest command, with no options:
Note: The information that is displayed in the “IPC Facilities Test Results” section reflects currentsettings in your UNIX kernel.
Checking and changing UniData configuration parameters
Complete the following steps to update UniData configuration parameters with new values systestsuggests. You want to do this if, for instance, you upgraded your license for more users or you addedphysical memory to your system.
1. Use the -f filename option of systest to create an output file in the format of the UniDataconfiguration file (/usr/ud82/include/udtconfig).
2. Run the UNIX diff command using the file that was created in step 1 and the udtconfig file todetermine the changes suggested by systest.
3. Save a copy of your udtconfig file, then manually update the production udtconfig file toreflect 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.
Checking kernel parameters
175
The following screen shows typical output from steps 1 and 2:
# systest -f udtconfig.new# diff /usr/ud82/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/ud82/log/log_overflow_dir---> LOG_OVRFLO=
Notice that one of the parameters systest recommends changing is SHM_GNPAGES. If you want tochange this parameter, 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 previous example are not made.systest -u changes only the udtconfig parameters NFILES and SHM_ATT_ADD, if necessary.
Checking kernel parameters
The -c argument for systest checks kernel settings against UniData recommendations. If you are notrunning RFS, use the -n option. Use the -r option are running RFS, as shown below:
Chapter 17: Managing memory
176
Note: The recommended values that are returned by systest are generic UNIX suggestions andmay not be appropriate for your operating system. Kernel configuration varies among UNIXversions. Refer to your host operating system documentation for detailed information about yourUNIX 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 on as root to run sms. See the UniData Commands Reference for detailedinformation about the parameters of the sms command syntax.
sms -h displays the current settings of shared memory-related configuration parameters, as shownin 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 = 1SHM_FIL_CNT = 2048JRNL_BUFSZ = 53248
The following example shows a sample output from the sms command with no options:
sms
177
The following table interprets the example.
Field Description
GCTs (50) The number of shared memory segments the system is configured tosupport. Read from the configuration parameter SHM_GNTBLS.
LCTs (50) The combined number of udt processes the system is configured tosupport at one time. Read from the configuration parameter NUSERS.
11502 The shared memory segment ID for a segment that was created. Thisnumber also appears in the ipcstat display. Note: The “GCT number”is read from left to right, top to bottom. In the example, only GCTnumber 1 is in use.
-1 Indicates a resource that is not currently in use.24230, 24244 UNIX process IDs (pid) for the udt processes currently active.
Tip: Use the sms display along with the output from gstt and lstt to monitor resource availability.Consider increasing SHM_GNTBLS or NUSERS and rebuilding the kernel if needed, when theseutilities indicate your system is consistently running near the limits of resources.
Use the -G option of the sms syntax to display information about the segment that is controlled by aparticular GCT. This option enables you to determine which udt process is using each global page inthe segment. The following screen shows an example:
Chapter 17: Managing memory
178
The following table interprets the results of the example.
Field Description
shmid (11502) The shared memory segment ID.freed_npages (30) The difference between the number of global pages in the segment
and the number of global pages in use. UniData reads the numberof pages in the segment (32) from the udtconfig parameterSHM_GNPAGES.
24230,24230 The UNIX process ID of the udt process that is using each globalpage.
-1 Indicates a resource not currently in use.
Learning about global pages
The gstt command displays information about the use of global pages in shared memory by the smmdaemon.
Syntax
gstt
The following example shows the output from the gstt command:
Learning about local control tables
179
Tip: Use the output from gstt, along with the visual display from sms, to monitor use of sharedmemory segments. If the value of GCTs used is consistently higher than 80%, we recommendincreasing the number of GCTs (SHM_GNTBLS).
Learning about local control tables
The lstt command displays information about local control tables in shared memory. Each localcontrol 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:
Chapter 17: Managing memory
180
Tip: Use the output from lstt, along with the visual display from sms, to monitor use of localcontrol tables. If the value of "LCTs used" is consistently higher than 80%, we recommendincreasing the number of LCTs (NUSERS). Also, if “Total Self-created” is consistently greater thanzero, consider increasing SHM_GPAGESZ or optimizing your application to minimize use of self-created segments.
Use the -l or -L option to display more information about a specific local control table. The followingscreen shows an example:
For more information about the parameters of the lstt syntax, see the UniData CommandsReference.
UNIX monitoring toolsThe UNIX sar, vmstat, swap, and swapinfo commands provide useful information for memoryand 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.
UniData configuration parametersWhen you design your configuration for smm, account for sbcs, the system buffer (if you are usingRFS), and other applications on your system.
UniData and memory, on page 36 lists the UniData configuration parameters that control how smmcreates and assigns memory structures. These parameters are also listed in UniData configurationparameters, on page 250.
UNIX kernel parameters
181
UNIX kernel parameters
UniData and memory, on page 36 describes UNIX kernel parameters that control creation andallocation of shared memory structures. An exhaustive list of such parameters is beyond the scope ofthis manual, since the parameters, their names, and the processes for adjusting them vary for differentUNIX versions. Refer to your host operating system and vendor documentation for information specificto your system.
Note: Depending on the UNIX version, some kernel parameters can be defined either as fixedvalues or by internal calculations that are performed by the system. In some versions, you can tunethe kernel while the system is running, while others require you to reboot to make the changeseffective. Some UNIX versions (AIX, for example) handle kernel configuration dynamically and donot offer the capability to change the parameters directly.
UniData error messages for smmThis section lists error messages that are received when smm is unable to respond to a request formemory resources. These messages are seen by the requesting process, so no central location existsfor them. They may appear when you start UniData or at run time.
Consider the following guidelines when you are troubleshooting error messages:
▪ Always note the full text of the error message, any error numbers that are associated with the text,and when the error occurred.
▪ Check the error logs (smm.errlog and sbcs.errlog) for more 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.MSGfile. 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 that
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 orrebuilding the UNIX kernel. Programming errors or coding structure errors may masquerade asshared memory errors; these errors should be corrected by correcting the software rather thanreconfiguring your system.
▫ If your system has been running smoothly with no recent changes, and you begin to see errormessages, identify and resolve external causes (such as swap space occupied by temporaryfiles) before reconfiguring UniData or rebuilding the UNIX kernel.
▪ Consider the resource needs of other applications that are running on your system. Your systemresources must support UniData and all other applications.
The following table lists error messages, describes their meaning, and offers suggestions for resolvingthem.
Error message Description
Error on attaching CTL (errno=xxx) A process cannot attach CTL (Control Table List). This error is afatal error. You may need to stop UniData and attempt to restartit. Be sure to save all logs and error logs.
Chapter 17: Managing memory
182
Error message Description
Error on attaching shm (xxx, xxx,xxx), errno=xxx
A process cannot attach a shared memory segment. The processasked for a segment larger than the system maximum orexceeded the per-process limit for shared memory segments.Increase UNIX kernel parameters (shmmax, shmmni, andshmseg) and/or increase the UniData configuration parameterSHM_GNTBLS.
Error on creating CTL (errno=xxx) UniData cannot create the CTL. This error happens whenthe size 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), or decreasethe size of CTL by decreasing the configuration parametersSHM_GNTBLS and NUSERS.
Error on creating a sharedmemory segment (size=xxx),errno=xxx
A shared memory segment of the requested size cannot becreated. Typically the requested size is larger than the maximumsize on the system. Adjust the UNIX kernel shmmax and theUniData configuration parameter SHM_MAX_SIZE to increasethe maximum size of a shared memory segment.
Error on forming shared memorykey (errno=xxx)
Some shared memory segments are created by usinginformation in files in the directory /usr/ud82/include.Check to be sure /usr/ud82/include exists; checkpermissions; restore the path from backup if it was removed.
No more GCTs You are out of GCTs (Global Control Tables), which means youalready have as many segments (self-created segments andsmm segments) as your system currently supports. Considerincreasing shmmni in the UNIX kernel, or increasing the UniDataconfiguration parameter SHM_GNTBLS.
No more LCTs You are out of LCTs (Local Control Tables). Consider increasingthe UniData configuration parameter NUSERS. Make sure thekernel parameter semmnu is larger than NUSERS.
No more core You are out of main memory. Check your swap space; checkrecent software changes for inappropriate memory handling;increase swap space or add more physical memory to yoursystem.
No more entries in CI table inLCT-xxx
The CI table in the specified LCT is full. A process used itslimit of local sections. A local section is a local page or severalcontiguous local pages. Consider increasing the UniDataconfiguration parameter SHM_LCINENTS.
No more entries in MI table inLCT-xxx
The MI table in the specified LCT is full. A process used its limitof global pages. Consider increasing the size of a global page(SHM_GPAGESZ) or the number of global pages per process(SHM_LMINENTS).
No more entries in PI table inLCT-xxx
The PI table in the specified LCT is full. Your application hastoo many forked processes. Your application may not bestructured in the correct manner. Consider increasing theUniData configuration parameter SHM_LPINENTS.
No more shared memory ids You are out of shared memory ids. Adjust the UNIX kernelparameter shmmni to increase the limit.
smm can’t get the first GSM errno =22
smm cannot acquire the first shared memory segment to buildthe necessary control tables because shmmax is not largeenough. Increase the kernel parameter shmmax.
UniData error messages for smm
183
Error message Description
Error on malloc a space (size=xxx),errno=xxx
Memory allocation error. The requested size is too large. Installmore physical memory or increase swap space.
184
Chapter 18: Managing ipc facilitiesThis chapter describes commands and procedures that monitor the use of message queues andsemaphores, and describes how to clear message queues and remove queues when necessary tocorrect problems.
This chapter includes instructions for monitoring shared memory use; however, shared memory isdescribed more fully in Managing memory, on page 168.
Message queues, shared memory, and semaphoresThe UniData system-level ipcstat command displays a list of message queues, shared memorysegments, and UNIX system semaphores currently in use on your system. Output from ipcstatresembles that from the UNIX ipcs command, but the ipcstat display also identifies the facilitiesin use by UniData.
Syntax
ipcstat [-s | -m | -q]
The following table describes each parameter of the syntax.
Parameter Description
[-q] Displays information about message queues only.[-m] Displays information about shared memory segments only.[-s] Displays information about UNIX system semaphores only.
Entering ipcstat with no options displays information about queues, semaphores, and sharedmemory segments.
Note: The output from ipcstat provides queue numbers, semaphore numbers, and segmentnumbers. You need this information to research ipc problems. For example, you need the queuenumbers to identify and clear congested message queues.
Tip: The ipcstat output is also useful for troubleshooting situations where UniData has crashed,and restart fails because one or more message queues are left. Use ipcstat to identify thesemessage queues and remove them with the udipcrm command before you restart UniData.
You do not need to log on as root to run ipcstat.
The following example shows sample output from the ipcstat command:
# ipcstatIPC status from /dev/mem as of Thu Jan 5 07:18:18 MST 2012T ID KEY MODE OWNER GROUPMessage Queues:q 0 0x4107001c -Rrw-rw---- root printq -> unknownq 45088769 0xffffffff --rw-rw-rw- root system -> tm R7.3q 45088770 0xffffffff --rw-rw-rw- root system -> udt R7.3q 48234499 0xffffffff --rw-rw-rw- root system -> tm R7.3q 44040196 0xffffffff --rw-rw-rw- root system -> tm R7.3q 45088773 0xffffffff --rw-rw-rw- root system -> udt R7.3q 39845894 0xffffffff --rw-rw-rw- root system -> udt R7.3q 48234503 0xffffffff --rw-rw-rw- root system -> udt R7.3
Message queues, shared memory, and semaphores
185
q 46137352 0xffffffff --rw-rw-rw- root system -> udt R7.3q 40894473 0xffffffff --rw-rw-rw- root system -> udt R7.3q 44040202 0xffffffff -Rrw-rw-rw- root system -> smm R7.3 (request)q 42991627 0xffffffff --rw-rw-rw- root system -> udt R7.3q 44040204 0xffffffff -Rrw-rw-rw- root system -> cm R7.3q 44040205 0xffffffff --rw-rw-rw- root system -> tm R7.3q 42991630 0xffffffff --rw-rw-rw- root system -> smm R7.3 (reply)q 45088783 0xffffffff --rw-rw-rw- root system -> tm R7.3q 44040208 0xffffffff --rw-rw-rw- root system -> tm R7.3q 40894481 0xffffffff --rw-rw-rw- root system -> tm R7.3q 46137362 0xffffffff --rw-rw-rw- root system -> udt R7.3q 41943059 0xffffffff --rw-rw-rw- root system -> udt R7.3q 5242900 0xffffffff --rw-rw-rw- root system -> unknownq 45088789 0xffffffff --rw-rw-rw- root system -> tm R7.3q 50331670 0xffffffff --rw-rw-rw- root system -> udt R7.3q 5242903 0xffffffff --rw-rw-rw- root system -> unknownq 44040216 0xffffffff --rw-rw-rw- root system -> tm R7.3q 39845913 0xffffffff --rw-rw-rw- root system -> sbcs R7.3 (fromsbcs)q 39845914 0xffffffff --rw-rw-rw- root system -> sbcs R7.3 (newversion)q 60817435 0xffffffff --rw-rw-rw- root system -> tm R7.3q 40894492 0xffffffff -Rrw-rw-rw- root system -> sbcs R7.3 (tosbcs)q 53477405 0xffffffff --rw-rw-rw- root system -> sm R7.3q 17825822 0xffffffff --rw-rw-rw- root system -> unknownq 17825823 0xffffffff --rw-rw-rw- root system -> unknownq 50331680 0xffffffff -Rrw-rw-rw- root system -> rm R7.3 (request)q 39845921 0xffffffff --rw-rw-rw- root system -> rm R7.3 (reply)
Shared Memory:m 2 0x78000082 --rw-rw-rw- root system -> unknownm 4194307 0xffffffff --rw-rw---- root system -> unknownm 1048580 0x0100000f --rw------- pconsole system -> unknownm 5 0xffffffff --rw-rw---- root system -> unknownm 1048582 0x0d000ba3 --rw-rw---- root system -> unknownm 93323272 0xffffffff --rw-rw-rw- root system -> unknownm 54530043 0xffffffff --rw-rw-rw- root system -> sm R7.3 (sysbuf)m 55578620 0xffffffff --rw-r--r-- root system -> sbcs R7.3m 57675773 0x45007116 --rw-rw-rw- root system -> smm R7.3 (ctl)m 131076097 0xffffffff --rw-rw-rw- root system -> unknownm 250613762 0xffffffff --rw-rw-rw- root system -> rm R7.3 (ctl)m 229642243 0xffffffff --rw-rw-rw- root system -> smm R7.3 (glm)m 34607108 0x65007116 --rw-rw-rw- root system -> sm R7.3 (ctl)m 24121351 0xffffffff --rw-rw-rw- root system -> smm R7.3 (shmbuf)
Semaphores:s 3145728 0xffffffff --ra------- root system -> unknowns 1 0x62001639 --ra-r--r-- root system -> unknowns 55574530 0xffffffff --ra-ra-ra- root system -> smm R7.3 (latch)s 55574531 0xffffffff --ra-ra-ra- root system -> smm R7.3 (latch)s 32 0x0100000e --ra------- pconsole system -> unknowns 33 0x01000213 --ra------- root system -> unknowns 56623138 0xffffffff --ra-ra-ra- root system -> smm R7.3 (latch)s 13631523 0xffffffff --ra-ra-ra- root system -> unknowns 5242916 0xffffffff --ra-ra-ra- root system -> unknowns 5242917 0xffffffff --ra-ra-ra- root system -> unknowns 53477414 0xffffffff --ra-ra-ra- root system -> smm R7.3 (latch)s 16777255 0xffffffff --ra-ra-ra- root system -> unknowns 54525992 0xffffffff --ra-ra-ra- root system -> smm R7.3 (ctl)s 56623145 0xffffffff --ra-ra-ra- root system -> smm R7.3 (latch)s 20971562 0xffffffff --ra-ra-ra- root system -> unknowns 20971563 0xffffffff --ra-ra-ra- root system -> unknowns 20971564 0xffffffff --ra-ra-ra- root system -> unknowns 20971565 0xffffffff --ra-ra-ra- root system -> unknown
Chapter 18: Managing ipc facilities
186
s 56623150 0xffffffff --ra-ra-ra- root system -> smm R7.3 (super-rls)s 19922991 0xffffffff --ra-ra-ra- root system -> unknowns 82837552 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 20971569 0xffffffff --ra-ra-ra- root system -> unknowns 20971570 0xffffffff --ra-ra-ra- root system -> unknowns 18874419 0xffffffff --ra-ra-ra- root system -> unknowns 18874420 0xffffffff --ra-ra-ra- root system -> unknowns 52428853 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 54526006 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 54526007 0xffffffff --ra-ra-ra- root system -> rm R7.3
(waiting)s 57671736 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 36700217 0xffffffff --ra-ra-ra- root system -> smm R7.3 (smm/sm sync)s 53477434 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 51380283 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 51380284 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 51380285 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 51380286 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 51380287 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)s 45088832 0xffffffff --ra-ra-ra- root system -> rm R7.3 (waiting)#
Note: Resources that are identified as “unknown” do not indicate a problem. These resources arein use by the operating system or by other applications rather than by UniData 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 Starting, stopping, and pausing UniData, on page 58 for examples of these log files.
Note: Occasionally, UniData problems result from another process inadvertently removing oneof the UniData message queues. You can compare the log files with ipcstat output to findout if this is the cause of a hang or system failure. If a queue is removed, the initial list from theappropriate log includes the queue, but ipcstat does not include the queue.
Removing ipc structuresCertain types of system failures cause ipc facilities that are associated with UniData to be left afterUniData was been shut down. This problem can occur if the system crashes or if one of the daemonsis 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 that indicates smm is still running.
▪ Running showud indicates smm is not running.
If you encounter these symptoms, complete the following steps:
1. Check for remaining facilities
187
1. Check for remaining facilities
Enter the UniData ipcstat command at the UNIX prompt. If the output shows structures that areassociated with UniData processes, run showud to see if any UniData daemons are running.
▪ If daemons are running, proceed to step 2.
▪ If ipc facilities exist, but no daemons, proceed to step 3.
▪ If no UniData daemons are running and no ipc facilities, research other causes for the startupfailure.
Tip: Occasionally icpstat fails to complete. You can obtain the information that you need byrunning the UNIX ipcs command and comparing the output with smm.log and sbcs.log toidentify UniData structures.
2. Stop UniData
If showud indicates that none of the UniData daemons is running, proceed to step 3. Otherwise, runthe 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 on as root, and enter the udipcrm command at a UNIX prompt. This command removes all ipcfacilities that are associated with UniData processes. The following screen shows the output fromudipcrm:
# $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 toones that are already gone.
After successfully completing udipcrm, you should be able to restart UniData. Proceed to step 6; youdo not need to complete step 5.
Chapter 18: Managing ipc facilities
188
5. Remove ipc facilities with UNIX ipcrm
The UNIX ipcrm command removes specific ipc facilities by specifying their identifiers. For thisreason, 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 ipcrmcommand. You must log on as root to run it. You need the output from ipcstat to identify theresources to remove. Note the type (column 1 of ipcstat output; must be m, q, or s) and the ID(column 2 of ipcstat output).
The following screen shows an example of ipcstat - q output:
# $UDTBIN/ipcstat -qIPC status from /dev/mem as of Thu Jan 5 07:22:12 MST 2012T ID KEY MODE OWNER GROUPMessage Queues:q 0 0x4107001c -Rrw-rw---- root printq -> unknownq 45088769 0xffffffff --rw-rw-rw- root system -> tm R7.3q 45088770 0xffffffff --rw-rw-rw- root system -> udt R7.3q 48234499 0xffffffff --rw-rw-rw- root system -> tm R7.3q 44040196 0xffffffff --rw-rw-rw- root system -> tm R7.3q 45088773 0xffffffff --rw-rw-rw- root system -> udt R7.3q 39845894 0xffffffff --rw-rw-rw- root system -> udt R7.3q 48234503 0xffffffff --rw-rw-rw- root system -> udt R7.3q 46137352 0xffffffff --rw-rw-rw- root system -> udt R7.3q 40894473 0xffffffff --rw-rw-rw- root system -> udt R7.3q 44040202 0xffffffff -Rrw-rw-rw- root system -> smm R7.3 (request)q 42991627 0xffffffff --rw-rw-rw- root system -> udt R7.3q 44040204 0xffffffff -Rrw-rw-rw- root system -> cm R7.3q 44040205 0xffffffff --rw-rw-rw- root system -> tm R7.3q 42991630 0xffffffff --rw-rw-rw- root system -> smm R7.3 (reply)q 45088783 0xffffffff --rw-rw-rw- root system -> tm R7.3q 44040208 0xffffffff --rw-rw-rw- root system -> tm R7.3q 40894481 0xffffffff --rw-rw-rw- root system -> tm R7.3q 46137362 0xffffffff --rw-rw-rw- root system -> udt R7.3q 41943059 0xffffffff --rw-rw-rw- root system -> udt R7.3q 5242900 0xffffffff --rw-rw-rw- root system -> unknownq 45088789 0xffffffff --rw-rw-rw- root system -> tm R7.3q 50331670 0xffffffff --rw-rw-rw- root system -> udt R7.3q 5242903 0xffffffff --rw-rw-rw- root system -> unknownq 44040216 0xffffffff --rw-rw-rw- root system -> tm R7.3q 39845913 0xffffffff --rw-rw-rw- root system -> sbcs R7.3 (fromsbcs)q 39845914 0xffffffff --rw-rw-rw- root system -> sbcs R7.3 (newversion)q 60817435 0xffffffff --rw-rw-rw- root system -> tm R7.3q 40894492 0xffffffff -Rrw-rw-rw- root system -> sbcs R7.3 (tosbcs)q 53477405 0xffffffff --rw-rw-rw- root system -> sm R7.3q 17825822 0xffffffff --rw-rw-rw- root system -> unknownq 17825823 0xffffffff --rw-rw-rw- root system -> unknownq 50331680 0xffffffff -Rrw-rw-rw- root system -> rm R7.3 (request)q 39845921 0xffffffff --rw-rw-rw- root system -> rm R7.3 (reply)#
Warning: Exercise extreme caution when removing ipc resources. Removing the wrong ones willcause problems elsewhere on the system.
6. Restart UniData
189
6. Restart UniData
Once you remove the ipc facilities that were left over, you should be able to restart UniData with thestartud command. UniData should restart normally.
Note: If UniData will not start, repeat steps 1 through 6. If UniData still will not start, the problemis unrelated to ipc facilities. Examine the error logs in udtbin (smm.errlog and sbcs.errlog)and resolve all indicated error conditions.
190
Chapter 19: Managing cataloged programsThis chapter describes the behavior of global, direct, and local cataloging for UniBasic programs. Italso describes how to create an alternate global catalog space by using the newhome command.
UniBasic source and compiled programsUniData stores UniBasic source code in DIR-type files in the UniData account where the source isdeveloped. The default location for storing UniBasic source code files is the BP file, which UniDatacreates as an empty file when you create a UniData account. Developers store UniBasic source codefiles 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 compiledcode in the same DIR file where the source code resides. The compiled code is a record whose name isthe same as the source record, prefixed with an underscore.
See the UniData Commands Reference and Developing UniBasic Applications for information about theBASIC 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 sourcefiles.
Tip: Use the ECL RUN command to run a compiled program. Refer to the UniData CommandsReference and Developing UniBasic Applications for information about the RUN command.
Cataloging UniBasic programsCataloging UniBasic programs simplifies program execution and can improve efficiency of systemresource use by allowing multiple users to access a single copy of a compiled program from sharedmemory. Use the ECL CATALOG command to catalog one or more UniBasic programs.
Direct cataloging
191
Note: See the UniData Commands Reference and Developing UniBasic Applications for informationabout 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 wascompiled and cataloged.
▪ The VOC file in the account contains a pointer to the compiled code in the program file. Users in thesame account can run 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 recatalogthe code if they recompile.
▪ When a user runs a directly cataloged program, UniData loads a copy of the program into theaddress 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 wascataloged, as well as in the program file. CTLG is a DIR-type UniData file, and each record is acompiled UniBasic program.
▪ The VOC file in the account contains a pointer to the compiled program in the CTLG. Users in thesame account can run the program by entering the program name at the ECL prompt.
▪ Developers must recatalog a program after it is recompiled to place a new copy of the compiledcode into the CTLG.
▪ When a user runs a locally cataloged program, UniData loads a copy of the program into theaddress space of the user.
Global cataloging
Points to remember about global cataloging are:
▪ If you run the CATALOG command without specifying local or direct cataloging, your program isglobally cataloged.
▪ Compiled code is located in a system-wide global catalog. The default global catalog isudthome\/sys\/CTLG.
▪ Developers must recatalog a program after it is recompiled it to place a new copy of the compiledcode into the global catalog.
Chapter 19: Managing cataloged programs
192
Note: A UniData installation can have more than one global catalog space. The environmentvariable UDTHOME determines which global catalog space a particular UniData sessionaccesses. See Creating an alternate global catalog space, on page 199 for more informationabout creating multiple global catalog spaces.
▪ A system-wide global catalog is a DIR-type file, with 26 subdirectories named a through z. Compiledcode is located in the subdirectory corresponding to the first letter of the program name. Compiledprograms that begin with nonalphabetic characters are stored in a subdirectory named X. Thecataloged program name can be the same as the source and object, or you can specify a differentname when you run CATALOG.
Tip: If you are using global cataloging, consider your program naming conventions. Since thecompiled code is placed in subdirectories according to name, you may have an unbalancedsituation if many your program names begin with the same letter (for instance, a general ledgerapplication where all the files begin with “gl”).
▪ A globally cataloged program is available to users in all UniData accounts.▫ When you run a globally cataloged program, the shared basic code server (sbcs) checks to see
if a copy exists in the shared memory it controls.
▫ If so, sbcs notifies the udt process which shared memory segment to attach to access thatcopy.
▫ If not, sbcs loads a copy into one of its shared memory segments for the user to run.
▪ The sbcs processdaemon handles any object file that is located in the udthome\/sys\/CTLGfile system, regardless of how the program is accessed.
▪ The sbcs processdaemon can manage up to 20 shared memory segments for globally catalogedprograms. The size of each segment is determined by the SBCS_SHM_SIZE parameter in theUniData configuration file (\udthome\include\udtconfig/usr/ud82/include/udtconfig). The default value for SBCS_SHM_SIZE is 1,048,576 bytes (1 MB), which is set whenyou install UniData. If this size is insufficient, users encounter runtime errors. You can increase thesegment size if you do not exceed the configuration parameter SHM_MAX_SIZE.
▪ For operating systems that 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 rangefrom 4 - 8 MB.
▪ Refer to UniData configuration parameters, on page 250 for more information aboutSBCS_SHM_SIZE and SHM_MAX_SIZE.
Managing global catalogsUniData provides a group of files and commands that manage global catalogs. These files andcommands 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
193
Contents of a global catalog
UniData maintains two files that store contents of a global catalog. The global catalog table, calledCTLGTB, 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:
The _MAP_ file also contains information about the contents of a global catalog. In addition to theinformation in CTLGTB, _MAP_ includes the size of each compiled program, the date it was cataloged,and the last date it was run. The _MAP_ file is not dynamically maintained by UniData. The ECL MAPcommand 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:
Chapter 19: Managing cataloged programs
194
By default, the CTLGTB file and the _MAP_ file are located in the same directory as the global catalog:udthome/\sys.
Tip: The CTLGTB file and the _MAP_ file are UniData hashed files. You can display records in thesefiles with standard ECL and UniQuery commands to determine if particular programs are in theglobal catalog.
Verifying a program version
The VCATALOG command checks the date/time stamp of a UniBasic source file against the compiledprogram in the global catalog. If the UniBasic source file was modified after the program wascataloged, the program does not verify.
Syntax
VCATALOG filename catalog.name program.name
The following table describes each parameter of the syntax.
Parameter Description
filename Name of the file that contain the program (BP, for instance).
Activating newly cataloged programs and subroutines
195
Parameter Description
catalog.name Name given to the program when you run CATALOG. Forexample, the command CATALOG BP TRIAL TEST creates aglobal catalog entry named TRIAL from a program called TEST.So catalog.name is TRIAL.
program.name Name of the program source file. In the example in the previousrow of this table, program.name is TEST.
Note: If catalog.name and program.name are the same, you need only supply the name once.
The following example shows output from VCATALOG:
:VCATALOG BP TESTProgram 'TEST' does not verify.:CATALOG BP TEST/usr/ud82/sys/CTLG/t/TEST has been cataloged, do you want to overwrite?(Y/N)Y:VCATALOG BP TESTProgram 'TEST' does not verify.:BASIC BP TEST
Compiling Unibasic: BP/TEST in mode 'u'.compilation finished:CATALOG BP TEST/usr/ud82/sys/CTLG/t/TEST has been cataloged, do you want to overwrite?(Y/N) Y:VCATALOG BP TESTProgram 'TEST' verifies.:
:VCATALOG BP TESTProgram 'TEST' does not verify.:CATALOG BP TESTC:\UniData73\sys\CTLG\t\TEST has been cataloged, do you want to overwrite?(Y/N)Y:VCATALOG BP TESTProgram 'TEST' does not verify.:BASIC BP TESTCompiling Unibasic: BP/TEST in mode 'u'.compilation finished:CATALOG BP TEST\UniData73\sys\CTLG\t\TEST has been cataloged, do you want to overwrite?(Y/N) Y:VCATALOG BP TESTProgram 'TEST' verifies.:
In the example, notice that recataloging the program did not make the program verify. This resultindicates that the source code was changed, but was not recompiled or recataloged. After the sourcecode was recompiled and recataloged, the program verified successfully.
For more information about the VCATALOG command, see the UniData Commands Reference.
Activating newly cataloged programs and subroutines
This section describes how to activate newly cataloged programs and subroutines.
Main programsWhen you globally catalog a UniBasic main program, UniData:
Chapter 19: Managing cataloged programs
196
▪ Copies the new compiled code into the global catalog.
▪ If a version of the program exists in shared memory, marks that version as obsolete.
The users already running the main program continue to run the previous version. Users that runthe program after the new version is cataloged get the new version. Once all users exit the previousversion, UniData removes the copy of that version from shared memory.
Note: A user that runs a main program continues to run that version until it completes.
SubroutinesIf a subroutine is recataloged while the main program is running, users will not run the newly-cataloged subroutine until the next time they run the main program. This behavior preventsinconsistent execution of a subroutine during one execution of the main program. Under certaincircumstances, however, a user or system administrator can override the default behavior. Overridesare dangerous in a production environment, but may be useful in a development or test environment.
NEWVERSION keywordThe NEWVERSION keyword for the CATALOG command enables a user that is logged on as rootanAdministrator to dynamically replace a globally cataloged subroutine. If a subroutine is cataloged withNEWVERSION, any user that execute the main program accesses the new version of the subroutinewith the next CALL or EXECUTE of the subroutine, rather than waiting until the main programcompletes.
Consider the following sequence of events:
1. A user runs the main program MAIN.2. MAIN calls a subroutine that is 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 isused for both calls (step 2 and step 4). With the next execution of MAIN, the newly cataloged SUBR isused.
If SUBR is recataloged after step 1, with the NEWVERSION keyword, then there are three possibleresults:
▪ CATALOG happens after step 1 but before step 2. In this case, the newly cataloged SUBR getsaccessed in both step 2 and step 4.
▪ CATALOG happens after step 2, but before step 4. In this case, the prior version of SUBR getsaccessed 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 step4. With the next execution of MAIN, the newly cataloged SUBR is accessed.
Warning: Using the NEWVERSION keyword to CATALOG a subroutine can produce inconsistentresults for users who are currently running the main program. For example, the number ofarguments could change.
The following sample CATALOG command shows the syntax that includes the NEWVERSION keyword:
:CATALOG BP SUBR NEWVERSION/usr/ud82/sys/CTLG/s/SUBR has been cataloged, do you want to overwrite?(Y/N) Y:
:CATALOG BP SUBR NEWVERSION
newversion system-level command
197
\UniData73\sys\CTLG\s\SUBR has been cataloged, do you want to overwrite?(Y/N) Y:
newversion system-level commandThe UniData system-level command newversion enables a user that is logged on as rootanAdministrator to dynamically replace a cataloged subroutine (just as the NEWVERSION keyword does),but limits the behavior to a selected user or users.
Syntax
newversion path userno...
The following table describes each parameter of the syntax.
Parameter Description
path Absolute path of the cataloged subroutine.userno... UNIX pProcess ID (pid) for a user who should access the new
subroutine dynamically. You can specify more than one userno;separate the numbers with spaces.
The following screen shows an example of the newversion command:
In the example, the newly cataloged subroutine is dynamically available to cgustafso, the owner ofuser number 7560. If cgustafso is running a main program that calls a subroutine, the next call tothe subroutine accesses the newly cataloged version. For all users other than cgustafso, the defaultbehavior remains in effect. The newly cataloged subroutine is activated with the next execution ofthe main program, not the next subroutine call. Notice that, in the example, the subroutine is globallycataloged; this command works with locally or directly cataloged routines as well.
In the example, the newly cataloged subroutine is dynamically available to user02, the owner of pid10846. If user02 is executing a main program that calls a subroutine, the next call to the subroutineaccesses the newly cataloged version. For all users other than user02, the default behavior remainsin 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; thiscommand works with locally or directly cataloged routines as well.
NEWPCODE commandThe ECL NEWPCODE command dynamically activates a cataloged subroutine. This command is usefulif a developer uses a UniBasic shell program to modify, recompile, recatalog, and retest a UniBasicprogram without exiting to ECL.
Chapter 19: Managing cataloged programs
198
Syntax
NEWPCODE path
path is the absolute path of a cataloged subroutine. The following example shows one use of theNEWPCODE command executed in a UniBasic program:
* PROGRAM MAINPROG* NEWPCODE EXAMPLEEXECUTE "MAINPROG2"EXECUTE "BASIC BP MAINPROG2"EXECUTE "CATALOG BP MAINPROG2 DIRECT"EXECUTE "NEWPCODE /usr/ud82/sys/CTLG/m/MAINPROG2"EXECUTE "MAINPROG2"END
* PROGRAM MAINPROG* NEWPCODE EXAMPLEEXECUTE "MAINPROG2"EXECUTE "BASIC BP MAINPROG2"EXECUTE "CATALOG BP MAINPROG2 DIRECT"EXECUTE "NEWPCODE \UniData73\sys\CTLG\m\MAINPROG2"EXECUTE "MAINPROG2"END
In the example, a user executing MAINPROG accesses the current version of MAINPROG2 in the firststatement. Including the NEWPCODE command before the next execution of MAINPROG2 causes theprogram to access the newest version. (In the example, MAINPROG2 was recompiled and recatalogedafter the first step, so the next execution accesses the newly cataloged MAINPROG2.)
Tip: If you are developing programs with the AE editor, the N option of the FI command equatesto the NEWPCODE command. For example, FIBCFN compiles a program and catalogs it (locally)with NEWPCODE. You need to use F (force) in conjunction with the N option. Refer to the onlinehelp for the AE editor or Developing UniBasic Applications for more information.
Note: The NEWPCODE command is effective only in the udt session where it is executed. AlthoughNEWPCODE is an ECL command, a user cannot affect a different user or even a different windowwith NEWPCODE.
Listing programs in useThe UniData system-level sbcsprogs command enables any user with access to a UNIX shell promptto display a list of globally cataloged programs that are currently in use, with counters for the numberof processes currently accessing each one.
# sbcsprogs [-f<path> | -p<pid>]
If you specify the -f option with the path to a globally cataloged program, sbcsprogs returns all theudtnos that have that program attached, as shown in the following example:
<bronco-73 109> sbcsprogs -f/bronco3/ud82/sys/CTLG/p/P1
Program Name Reference Count Obsolete
/bronco3/ud82/sys/CTLG/p/P1 1 0PID:545004/bronco3/ud82/sys/CTLG/p/P1 1 1
Creating an alternate global catalog space
199
PID:991428
If you specify the -p option with a pid, sbcsprogs returns all objects attached to that pid, as shownin the following example:
<bronco-73 113> sbcsprogs -p545004
Programs Referenced by process 545004Program Name Reference Count Obsolete
/bronco3/ud82/sys/CTLG/p/P1 1 0/bronco3/ud82/sys/CTLG/p/P2 2 0
The following example illustrates the output from sbcsprogs if you do not specify any options:
# sbcsprogsProgram Name Reference Count/usr/ud82/sys/CTLG/a/AE 2/usr/ud82/sys/CTLG/a/AE_ICOM1 1/usr/ud82/sys/CTLG/a/AE_AE 2/usr/ud82/sys/CTLG/a/AE_UPS 1
Program Name Reference Count\UniData73\sys\CTLG\a\AE 2\UniData73\sys\CTLG\a\AE_ICOM1 1\UniData73\sys\CTLG\a\AE_AE 2\UniData73\sys\CTLG\a\AE_UPS 1
In the example, two users are executing AE, and two are executing AE_AE. The sbcs daemonmaintains the counter, incrementing it as users executerun a program and decreasing it as userscomplete execution. When the counter for a routine reaches zero, sbcs removes the copy of thecompiled program from shared memory, making the space available for other programs as needed.
Tip: If you run sbcsprogs regularly throughout your processing cycle, you can learn whichprograms are used most heavily. This information is useful if you are troubleshooting anapplication 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 inaccurately high, causing excessmemory to remain held. Stopping and restarting UniData resets the counter and releases memory.
Creating an alternate global catalog spaceThe system-level newhome command creates a new UniData account containing an alternate globalcatalog 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 thesubdirectory sys, which contains the following files and directories:
Chapter 19: Managing cataloged programs
200
Procedure for creating an alternate global catalog space
201
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 homedirectory, 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:
1. Change to the new account directory
At the operating system prompt, change to the directory in which you intend to locate the newUniData account, as in the following example:
C:\UniData73>cd \UniData73\claireg
Chapter 19: Managing cataloged programs
202
# cd /home/claireg
2. Execute newhome
Execute the newhome command, indicating the path to the new account. In this example, a newUNIX directory, testenv, will be created under \UniData73\claireg/home/claireg. (If theudtbin 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 bythe ! 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.
:!newhome testenvCreating new udt home \UniData73\claireg\testenv ...Unidata has created the new home account. This account contains only the include and sys directory with Unidata's cataloged programs. To access your new home account, you must reset the UDTHOME environment variable or change the value in your registry.
3. Modify VOC entries for users
Decide which UniData accounts should access the new global catalog space. For each account, modifythe VOC entry for CTLGTB. The entry should point to the new global catalog space, as shown in thefollowing example.
Notice that this example uses a soft pointer to @UDTHOME. This ensures that the VOC always points tothe correct catalog space. Refer to UniData and the UNIX file system, on page 18 for information aboutsetting 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.*--:
:AE VOC CTLGTBTop of "CTLGTB" in "VOC", 3 lines, 45 characters.*--: P001: F002: @UDTHOME\sys\CTLGTB003: @UDTHOME\sys\D_CTLGTBBottom.*--:
4. Modify UDTHOME for users
203
You do not need to log on as root an Administrator to edit the VOC entries; however, you need writepermissions 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 alternateglobal catalog space. The value of UDTHOME defined during a particular UniData session determinesthe global catalog space a user accesses.
Note: Even if the VOC file of an account is set up to point to the alternate global catalog (CTLGTB),a user whose UDTHOME is set to the default value accesses the default global catalog space.
You can modify the UDTHOME variable in a user’s .login or .profile. Simply use vi or any UNIX texteditor to change the variable setting. The user must then log out and log back on to make the changeeffective.
Users with access to a UNIX shell prompt can reset the UDTHOME environment variable with thesetenv command. The value set at the UNIX prompt overrides the .login or .profile:
% printenv UDTHOME/disk1/ud82% setenv UDTHOME /home/carolw/demo/testenv% udtUniData Release 8.1.2 Build: (6054)© Rocket Software, Inc. 1985-2015.All rights reserved.
Current UniData home is /home/carolw/demo/testenv/.Current working directory is /home/carolw/demo.
5. Copy application programs
After resetting UDTHOME to point to the new space, start UniData from an account that hasaccess to the site-specific programs that you want to access from the new account, and recatalogthose programs. Because you have reset the UDTHOME environment variable, UniData places therecataloged programs in the new space.
You can also use the following series of UNIX commands to copy all globally cataloged programs to thenew catalog space. Be sure to replace original_udthome and new_udthome with the paths to your oldand 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 thesbcsprogs command when two global catalog spaces are used:
% sbcsprogsProgram Name Reference Count... 1/home/carolw/demo/testenv/sys/CTLG/a/AE/home/carolw/demo/testenv/sys/CTLG/a/AE_UPS 1/disk1/ud82/sys/CTLG/a/AE 1/disk1/ud82/sys/CTLG/a/AE_ICOM1 1
Chapter 19: Managing cataloged programs
204
/disk1/ud82/sys/CTLG/a/AE_UPS 1...%
% sbcsprogsProgram Name Reference Count... 1\UniData73\testenv\sys\CTLG\a\AE\UniData73\testenv\sys\CTLG\a\AE_UPS 1\disk1\ud82\sys\CTLG\a\AE 1\disk1\ud82\sys\CTLG\a\AE_ICOM1 1\disk1\ud82\sys\CTLG\a\AE_UPS 1...%
Notice that AE is running twice, but that the two copies are cataloged in different global catalogspaces.
Procedure for using an alternate global catalog space
Once you have created an alternate global catalog space using the newhome command, complete thefollowing steps for each separate UniObjects, ODBC, and JDBC connection:
1. Modify the ud_database file to include a defined alias name that points to the correctUDTHOME to ensure that the alternate global catalog space is used.
The following example illustrates an entry for “demo_newhome” that points to the newhomepath.
DATABASE=demo_newhome UDTHOME=C:\newhome\catalogspace UDTACCT=C:\U2\ud82\demo TRACE_LEVEL=0
You should select this path as an alternative catalog space before you start a UniData session.2. Before you start a UniData session, set the UDTHOME environment variable. For information
about setting environment variables, see Setting an Environment Variable, on page 20.
Note: Executing SETENV within a connection does not change the default UDTHOME for auser, and the user will still access the default global catalog space.
3. You can specify a specific UDTHOME for telnet users using the U2 Extensible Administration tool.For more information, see Configuring user profiles.
205
Chapter 20: CallBasic, CALLC, and makeudtUniData provides the makeudt tool and the UniBasic CALLC command for linking C routines intoUniData, and the CallBasic tool for linking UniData into C programs. This chapter describes commandsand procedures for using these tools.
Note: See the UniBasic Commands Reference and Developing UniBasic Applications for informationabout the syntax and use of the CALLC command.
Linking C routines into UniData
Overview
Many applications use C functions for purposes like environment definition, security, or low-level datatransfers (similar to the UniBasic GET and SEND functions). UniData allows you to build a customizedversion of the UniData “kernel” (the udt executable, located in udtbin) that includes C functionsdeveloped at your site. Once you build the customized udt, you can access the C functions fromwithin a UniBasic application using CALLC commands.
You can also create a UniData executable with links to C programs so that they are accessible throughInterCall, UniObjects, or UniObjects for Java.
Note: When you use CALLC, your C functions are executed by a udt process. They are not visibleto 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 basecompiler 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 andcfuncdef are installed into the directory udthome/work. You create a file called cfuncdef_userthat contains definitions for your site-specific C functions, and you may need to customize themake 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 executethe makeudt or makeudapi commands, these commands are automatically executed. If you usethe make utility, you need to execute them manually.
Note: Refer to your host operating system documentation and your hardware vendor if youhave questions about your C development environment.
Chapter 20: CallBasic, CALLC, and makeudt
206
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 havebeen removed. You can run makeudt to generate a nonstripped binary to facilitate debugging.
Tip: Rebuilding udt is often unnecessary for researching problems. Do not undertake this stepunless you are advised to do so by Technical Support.
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 separatefrom production. In this way, you can conduct tests without disrupting user activity, and replace theproduction udt only when you are satisfied with the functionality.
makeudtSyntax
makeudt [-n nfa]
makeudt is a UniData system-level command that builds a new UniData executable (udt). Thecommand builds the executable using the following:
▪ base.mk—This make file is located in udthome/work. This file is a template that UniData usesto create a second make file called new.mk. Then UniData uses new.mk to create the new udtexecutable.
▪ cfuncdef—This function definition file is also located in udthome/work. It contains definitionsfor 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 linkinto UniData. You need to create this file.
▪ UniData Libraries—When you install UniData, you are prompted for the path where you want tolocate these.
The following table describes the option of the makeudt syntax.
Option Description
-n nfa Use this option only if you are not using UniData OFS/NFA. Thisoption allows makeudt to use “dummy” libraries rather thannetwork libraries NFA requires. Software development environmentsmay or may not include the network libraries; if yours does notinclude these, and you do not use the -n nfa option, makeudt fails.
Note: It is best to log on as root to execute makeudt. UniData may be up and running, and usersmay be logged on to the system. If users are logged on, the makeudt command may or may notallow you to overwrite the production udt, depending on your UNIX version. Some versions displayan error message and exit, while others prompt whether you wish to overwrite the production udt.
File examples
207
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 will likely fail.Always start with the base.mk file released with your UniData release.
The following example shows a base.mk file for UniData on an AIX system:
Chapter 20: CallBasic, CALLC, and makeudt
208
cfuncdef example
209
cfuncdef example
The following sample is a cfuncdef file, also from an AIX system. Notice that, in this instance, thereare no C functions specified:
Warning: Do not copy the sample cfuncdef file onto your system. If you do, makeudt can fail.Always start with the cfuncdef file released with your UniData release.
If C functions were specified, there would be entries under $$FUN, and there might also be entriesunder $$OBJ and $$LIB.
Creating cfuncdef_user
Although makeudt recognizes the cfuncdef_user file, UniData does not include this file atinstallation. You can create this file from the cfuncdef file by completing the following steps:
Chapter 20: CallBasic, CALLC, and makeudt
210
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 thatappear under the lines beginning with $$FUN, $$OBJ, and $$LIB. This step gives you a file that hasthe format information included for the function definitions, but does not contain references toany UniData routines.
3. Add Local C Functions to cfuncdef_user
Use vi or any UNIX text editor to add references to site-specific C routines you are linking intoUniData. Follow the format specified in the file.
Steps for linking in C functionsComplete the following steps to rebuild your udt executable or to build a udapi_slaveexecutable.
1. Make backup copies of files
Log in to your system as root; save and verify a copy of your current udt, your base.mk, andyour 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 ofcfuncdef_user as well.In the example, the UNIX cmp command verifies the udt executable. The UNIX diff commandverifies 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 rebuildingthe 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 thefollowing:
▪ The C functions should reside in the work directory, along with the makefile and thefunction 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).3. Edit cfuncdef_user
Add information about your C functions to the cfuncdef_user text file. Use vi or any otherUNIX 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.
Steps for linking in C functions
211
The cfuncdef file contains definitions for only UniData-developed C functions that may bepart of your UniData release. UniData overwrites the cfuncdef file whenever you install a newUniData version. If you placed your own function definitions there, you will lose them with eachnew install. UniData does not overwrite the cfuncdef_user file at installation, so your sitespecific definitions are preserved.The naming convention for UniData functions is U_funcname(). To avoid errors, choose adifferent 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 on toUniData, 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 youwish, but if you are ready to update production with makeudt or makeudapi, users should belogged out of UniData.If your changes are not fully tested, you may prefer not to overwrite the production udt. SeeSteps for setting up a development environment, on page 213 in this chapter.
5. Execute makeudt or makeudapi
The following screen shows sample output from the makeudt command:
The new udt has replaced the previous version in udtbin.The next screen shows sample output from the makeudapi command:
Chapter 20: CallBasic, CALLC, and makeudt
212
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 yournext regularly-scheduled backup, you need a copy of this new executable to restore your systemto its current state. If you do not make a backup copy, and you restore from prior backups, youwill 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 thatis helpful if you are using a debugging tool to research a problem. However, including thisinformation increases the size of the executable, and may result in noticeably slowed responsefor users. Consider using the UNIX strip command to remove the symbol table information todecrease 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 strippingexecutables.
8. Allow users to log on to the system
All users who log on at this point will access the new version of the udt or udapi_slaveexecutable.If you want to execute makeudt or makeudapi and not overwrite the production udt, modifybase.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 (forinstance, udt.test) instead of udt.
Steps for setting up a development environment
213
Steps for setting up a development environmentDuring application development and testing, it may be necessary to rebuild the UniData kernelnumerous times to test changes to C functions. You can use the make files provided by UniData tobuild 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 thecontents of the default udthome/work to the new directory. You can use the make files, and soon, 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) untilyour changes are ready for production.
4. Execute gencdef, genfunc, and genefs
If you have made any changes to cfuncdef or to cfuncdef_user, you need to execute theUniData system-level commands genefs, gencdef, and genfunc to update working filesthat the make utility requires. Use the following steps, but be certain that your current workingdirectory is the new work space:
You must log on as root to execute these commands, and you must execute them in the ordershown in the example. If you do not execute these commands, and you have changed yourfunction definition files, make can fail.
5. Edit the new.mk file.
Chapter 20: CallBasic, CALLC, and makeudt
214
You can change the name of the output executable to provide clarity. In the following lines from asample 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 newwork 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 workarea, 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 overwritesthe new.mk file that you updated in step 5. Also, for development, it is safest not to usemakeudt until all your changes are ready for production. The following screen shows how to usemake:
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
Accessing UniData from a C program
215
Users can test the executable simply by specifying the full path when invoking it. The user’sudthome and udtbin should not be changed from their ordinary settings. The following screenshows an example:
# cd $UDTHOME/demo# /usr/user01/work/new_testUniData Release 8.1.2 Build: (6054)© Rocket Software, Inc. 1985-2015.All rights reserved.Current UniData home is /disk1/ud82/.Current working directory is /users/ud82/demo.::!psPID TTY TIME COMMAND12393 ttyv1 0:00 new_test10660 ttyv1 0:00 csh10746 ttyv1 0:00 sh12398 ttyv1 0:00 sh12399 ttyv1 0:00 ps10659 ttyv1 0:03 rlogind
Notice that the UNIX ps command displays the name of the test executable. You can have severaldifferent 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 bycalling UniBasic subroutines from a C program. The CallBasic API is particularly useful for applicationslike automated processes that gather data and then write the data into a UniData database. The mainbody of the application may be written in C, and the application uses a UniBasic subroutine, calledthrough CallBasic, to write the data into UniData hashed files in correct format.
Note: When you use CallBasic, your UniBasic routines are called from an external program.UniBasic and UniData are invisible to the users of the external program.
Requirements
The components required to use the CallBasic API are:
▪ Development environment—Your system should have a full software development kit. (A basecompiler is not sufficient). You need network libraries if you are using NFA.
Consult your host operating system documentation and your hardware vendor if you havequestions 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 installedinto the directory udthome/work. Use this makefile as a template to build your application, withUniData linked into it.
The examples in this section are developed using udthome/work as a workspace. You can create aseparate workspace by creating a new directory and copying all the files from udthome/work into it.Then complete the steps in your own workspace.
Chapter 20: CallBasic, CALLC, and makeudt
216
How CallBasic works
The CallBasic API includes three functions:
▪ udtcallbasic_init( )—This function initializes UniData and CallBasic. It serves the purposeof opening a “UniData session” for your C application. Your C program must execute this functiononce and only once.
▪ U_callbas( )—This function calls a UniBasic subroutine, passing arguments, and places theresults in a pointer to the return value. You may execute this function numerous times in your Capplication, each time you want to call a UniBasic subroutine.
▪ udtcallbasic_done( )—This function clears all UniData-related temporary files and otherresources, and ends the interface between the C application and UniData. You must execute thisfunction once in your C application. You must also include this function in any error exits in yourapplication that may be taken after udtcallbasic_init().
See Developing UniBasic Applications for a detailed description of the CallBasic functions and theirrequirements.
C program exampleThe following C program, called sample.c, illustrates the components required for CallBasic:
C program example
217
Notice the following points about sample.c:
Chapter 20: CallBasic, CALLC, and makeudt
218
Header files
You must include setjmp.h for the error handler, and you must include the UniData header file /usr/ud82/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 takenbefore 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 dumpcore.
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 thesubroutine:
if (sts == 0){
free(rtn);
Notice that we free the memory if the function completes successfully; UniData frees the memory ifthe function fails.
Ending CallBasic
The last step in the C program is:
/* Close everything properly */
udtcallbasic_done(sts);
UniBasic subroutine example
219
Remember that this function closes the UniData session for the C program, closing all UniDatatemporary 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 therequirements 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 tothe 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 maybe globally, directly, or locally cataloged. However, if you catalog the routine directly or locally, youmust execute the C program from the UniData account where the subroutine is cataloged. Regardlesshow you catalog the UniBasic subroutine, you must execute the C program from a valid UniDataaccount.
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-compliantsyntax, and others do not. Consult the documentation supplied with your C compiler for specificcoding requirements for your system.The C program should be located in the same directory as the makefile. By default, this isudthome/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 thesample 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
Chapter 20: CallBasic, CALLC, and makeudt
220
#
See C program example, on page 216 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. Thefollowing example shows compiling and directly cataloging the sample subroutine EXAMPLE inthe 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 arethoroughly tested.
3. Make a copy of the makefile template
The template, released by default into udthome/work, is called callbas.mk. When you copyit, 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.mkon your system as a starting point; do not attempt to use the examples in this document.
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 amakefile that will build your C program, with udt linked into it, forming an executable whosename you choose. There are additional steps required so that the make is successful. Follow thesequence below:a. Correct references for UniData libraries
Locate a line in your make file that looks like this:
libpath = -L/disk3/srcman/alpha/ud_73_020715_4088/bin/lib
Notice that the path does not match your production system. It contains a UniData internalnaming convention. You need to change this to reflect the actual location of your UniDatalibraries. The following example uses the default location:libpath = -L/usr/ud82/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:
Steps for CallBasic
221
NEWOBJS = callbas.ocallbas.o
is a default object name released with the template. Change this to match your C routine, asshown 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 yourcompiled 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 asshown below:sample: $(NEWOBJS) $(OBJS)
Note: As shown in the examples, it is simplest to maintain naming consistency betweenyour C program, its .o file, and your new executable.
d. Check your workMake certain that you have replaced all occurrences of callbas with the name of yourprogram.
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 theexamples) and then add about 20% overhead, since the executable will not be stripped. Makesure you have enough space available in your work area.Use the UNIX make utility, as shown in the following screen:
# make -f sample.mkcc -Wl,-a,archive sample.o funchead.o interfunc.o callcf.o efs_init.o \
-L/usr/ud82/bin/lib -lapidummy -lshare -ludsql -ludmach -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 on as root to execute the make utility. You do need to havewrite permissions at the directory level in your work area. Refer to your host operating systemdocumentation for information about the make utility.
6. Produce a stripped executable (Optional)
The make utility produces an executable that contains symbol table information that is helpfulif you are using a debugging tool to research a problem. However, including this informationincreases 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
Chapter 20: CallBasic, CALLC, and makeudt
222
size and improve performance. The following screen shows the results of stripping the sampleexecutable:
# 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 yourhost operating system documentation for information about debugging and symbol tables.
223
Chapter 21: General troubleshootingThis chapter outlines several problems that you may encounter running UniData, and offerssuggestions to research and resolve them. The chapter also describes a number of UniData systemmessages, along with explanations of their causes.
Crashes and restart problemsThis section presents suggestions for handling situations where UniData stops running entirely, orwhere you cannot start UniData.
UniData crashes
Symptoms: System appears to be “hung”; one or more terminals may display the message Killed orudt dead.
Suggestions:
1. Check to make sure your hardware and operating system is running. Hardware or powerproblems 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. When it runs out of swap space, the AIXoperating system kills processes.
3. Check to see if UniData is still running. Run the showud command to check the status of theUniData daemons. If the UniData daemons are still running, proceed to UniData is hung, on page224. Otherwise, proceed to step 4.
4. Check the UniData logs and error logs. These logs are located in udtbin. Consider printing themin case they are needed to research a crash.
5. Identify and resolve problems that are revealed in the logs.
The following chapters might be useful for this step:▪ Managing UniData files, on page 93
▪ Managing memory, on page 168
▪ Managing ipc facilities, on page 1846. When all identified problems have been resolved, log on as root and run startud. If UniData
does not start, proceed to UniData cannot start, on page 223. Otherwise, resume normaloperations.
Note: UNIX system crashes may result in data inconsistencies or file corruption, dependingon the activity at the time of the crash. Examine your data files with guide after you startUniData. If you are using the Recoverable File System (RFS), more factors must be considered.For more information, see Administering the Recoverable File System.
UniData cannot start
Symptoms: startud does not complete normally. Error messages may or may not appear in thewindow where you run startud.
Chapter 21: General troubleshooting
224
Suggestions:
1. Make sure your UNIX environment is running correctly. Check UNIX system logs for error andwarning conditions. Identify and resolve external problems.
2. Check the UniData log files in udtbin. Consider printing them in case they are needed to solve aproblem.
3. Check for indications of shared memory problems. (For example, if smm is unable to create theCTL segment, UniData will not start). If messages exist in the smm.errlog, review Managingmemory, on page 168 for suggestions to solve the problem.
4. Check the status of UniData ipc facilities by logging on as root and running ipcstat. If ipcstructures were not properly cleaned up after a crash, follow the procedures that are described inManaging ipc facilities, on page 184 to clear the structures.
If ipcstat hangs, use the UNIX ipcs command.5. Log on as root and run startud to restart UniData.
If you are using RFS, more factors must be considered. For more information, see Administeringthe Recoverable File System.
Response problems in UniData
UniData consistently slow
Symptoms: The system is consistently sluggish whenever UniData is running and users are logged on.
Suggestions: Refer to Performance monitoring and tuning, on page 228.
UniData is hung
Symptoms: The system has been performing acceptably, but the response slows. One to all terminalsmay appear hung.
Suggestions:
1. Run the UNIX ps command. Look for processes with large and rapidly growing cpu time. Explorethese processes; kill them if appropriate.
2. Run showud at a UNIX prompt to make certain all UniData daemons are running.3. Check the UniData logs on 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 Managing UniData locks, on page 130 for procedures to identifyand clear unneeded locks.
5. Identify and resolve message queue problems by using the procedures that are described inManaging ipc facilities, on page 184.
6. If the response is still slow, or if steps 1 - 3 did not reveal the problem, check your system toidentify and resolve unusual load conditions. The UniData listuser, sbcsprogs, andudtmon programs, and the UNIX uptime, vmstat, and ps commands may provide helpfulinformation.
Error messagesError messages that are seen in UniData applications may originate from the following:
Common error messages
225
▪ the application
▪ UniData
▪ UniBasic
▪ one of the layered products
▪ the operating system
▪ combined sources
The following table shows typical formats for error messages.
Format Source
In /usr/ud82/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 disk space, resize failed. UniData error message. Many error messages in UniDatacan be found in the file that is identified by the VOC pointerENGLISH.MSG, which is a UniData hashed file. Use ECLESEARCH or UniQuery to search for messages in this file. Ifyou have localized UniData to run in your local language, seeUniData International for the name of your message file.
msgrcv failed. errno=36 UniData error message that includes the UNIX error number.Translate the error number for helpful troubleshootinginformation.
Common error messages
This section describes common UniData error messages.
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 Commands Reference 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 thecommand.
▫ BASICTYPE is set to P when it should be U or vice versa; try changing BASICTYPE and reenter thecommand.
Chapter 21: General troubleshooting
226
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 theVOC file.
▫ command is a UniBasic program that is not globally cataloged; determine how it should becataloged; make necessary corrections; instruct users appropriately. See Managing catalogedprograms, on page 190 for further information.
cannot open abcdef
▪ Occurrence—This error is a UNIX-level error that occurs when a process is attempting to open a filethat is called abcdef.
▪ Causes—This error can be caused by either of the following:▫ The file abcdef does not exist; check the file name and path and try again.
Note: Some UNIX commands return the message “no such file or directory” for a file thatdoes not exist, while others return “cannot open.”
▫ The user that receives the error does not have sufficient permissions to run the file. See UniDataand UNIX security, on page 13 and Managing UniData security, on page 75 for more information.
Note: Some UNIX commands return the message cannot open filename: Permissiondenied and others simply return Permission denied.
[100004]
▪ Occurrence—A number of users are logged on to UniData. When an additional user tries loggingon, [100004] displays on the terminal.
▪ Cause—You are out of semaphore undo structures in the UNIX kernel. Use the UniData kpcommand to display kernel settings; the parameter semmnu should be set to three times thenumber of users that are licensed on your system. You need to rebuild your UNIX kernel.
[100000]
▪ Occurrence—A number of users are logged on to 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/ud82/include/udtconfig, determines the number of local control tables UniData uses.Each local control table tracks information for a single UniData user process. This parametercannot exceed the kernel parameter semmnu. Set NUSERS to the number of authorized UniDatausers + number of authorized UniData users / 4.
Virtual field too big
227
Virtual field too big
▪ Occurrence—This message displays after you run a UniQuery statement.
▪ Cause—You created a formula in a virtual attribute that, when evaluated by UniQuery, creates astack of C routines that is bigger than the default. The limit that is exceeded is not the number ofcharacters in the formula itself, but an internal limit. Set the environment variable VFIELDSIZE to anumber greater than 300 (the default) to resolve this problem. Try setting VFIELDSIZE to 400. Thelarger VFIELDSIZE is, the more memory your process requires.
Record is too long. Ask Unidata to extend the U_MAXEXTRA.
▪ Occurrence—This message occurs while you are loading records from tape into a UniData hashedfile with T.LOAD. When the message occurs, T.LOAD quits, leaving a partial restore.
▪ Cause—T.LOAD encountered a record that is too large to process. You can remake the T.DUMPtape with a larger block size, or you can load the tape into a DIR-type file rather than a UniDatahashed file. Once you load it into the DIR file, you can use the ECL COPY command to copy therecords into a hashed file. If you run T.LOAD to load a file into a directory, make sure your UNIX filesystem 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 UniBasicprogram.
▪ Cause—The sbcs daemon is out of memory to store globally cataloged programs. sbcs canmanage up to 20 shared memory segments, and the size of each is determined by the UniDataconfiguration parameter SBCS_SHM_SIZE (1 MB by default). However, some UNIX versions (AIX, forexample) limit the number of shared memory segments to 10, which limits the memory availablefor sbcs. You can resolve this situation by resetting SBCS_SHM_SIZE. Values from 4 - 8 MB areappropriate for AIX systems.
228
Chapter 22: Performance monitoring and tuningThis chapter outlines factors that can affect UniData performance on your UNIX platform, lists genericUNIX tools for monitoring components of your system, and describes UniData-specific procedures formonitoring performance.
UNIX performance considerationsOptimizing performance for any application on a UNIX platform may involve tuning and balancingamong 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 workstationsthat 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 many featuresto increase I/O efficiency, optimizing configuration andimplementing disk striping (if available) may improveperformance.
Virtual Memory Subsystem Not a performance factor in most cases; If memory isinsufficient, UniData processes usually fail.
Process Scheduling Subsystem Not a significant performance factor if you consider elementaryscheduling factors.
Network Subsystem May be a significant performance factor because of impacts onI/O performance
UNIX performance monitoringMonitor your performance regularly to develop baseline expectations throughout your application’sprocessing cycle. The performance history of your system provides information that you can use toimplement new procedures (such as scheduling certain jobs to run off-hours or purchasing moreresources) as well as to identify problems quickly to minimize downtime.
Tip: Consider setting up a cron job to gather performance statistics at scheduled intervals. Referto your host operating system documentation for information about the cron command.
Tools
The following table lists UNIX commands useful for performance monitoring and describesinformation available from each.
Tips
229
UNIX Command Description
uptime Displays number of users and average system load (number ofprocesses 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.
Note: Command names, syntax, and options for performance monitoring tools differ among UNIXversions. Refer to your host operating system documentation for information specific to yoursystem.
Tip: Menu-driven performance monitoring toolkits are available from several vendors.
Tips
The following section lists suggestions for improving performance.
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 that is associated with processes that are paging or swapped may indicatememory shortages. Poor performance that is associated with processes that are blocked for I/O mayindicate disk I/O problems.
iostat
Results that may indicate I/O problems include: CPU in system state more than 50% consistently; CPUhas 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, andprogram coding efficiency.
Database design considerations
▪ Structure your database so that records do not exceed a size limit of 4 K.
▪ When possible, avoid long, multivalued, variable-length records.
Chapter 22: Performance monitoring and tuning
230
▪ 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. Considerthis factor when you create indexes. The more indexes that are created for a file, the longer an updatetakes.
When the maximum key length allocated is too small to contain the attributes that are being indexed,index overflows occur. 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. Considerrunning LIST.INDEX periodically. See Using UniData for information about alternate key indexes.
Sizing static hashed files
If UniData hashed files are allowed to overflow, performance suffers. Level 2 overflow, which occurswhen primary keys outgrow the block, has a particularly serious performance impact. Level 1overflow, which occurs when data overflows the block, eventually affects performance as well.
For information about file sizing commands, refer to Sizing dynamic hashed files, on page 230 and tothe UniData Commands Reference and Using UniData.
Tip: Consider using cron to run the UniData system-level checkover command in each of yourUniData account directories at regular intervals. Use the output to resize 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 aminimum modulo. Splitting prevents level 2 overflow conditions because a group splits wheneverthe percentage occupied by keys exceeds a preset value. Merging supports efficient access to the filebecause maintaining the file at a low modulo makes searches faster.
For information about dynamic file sizing commands, refer to Managing UniData files, on page 93 andto the UniData Commands Reference.
UniBasic coding tips
The efficiency of your UniBasic application has a significant impact on UniData performance. Use thefollowing guidelines when designing and coding.
Use modular programming
231
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.
▪ When appropriate, use GOSUB instead of external CALLs; use CALL when multiple programsaccess 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.
▪ when you are extracting data sequentially from a string, use LOOP and REMOVE.
▪ 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
▪ When you are accessing small strings and variables, use dynamic arrays.
▪ When you are handling a large number of attributes and delimited strings, use dimensioned arrays.
Use the correct READ in each situation
▪ When you are accessing small records, and the data you want is near the beginning of each record,use READ.
▪ If your intention is to get only one attribute, use READV.
▪ 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.
Chapter 22: Performance monitoring and tuning
232
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 forUniBasic programs, internal subroutines, and program calls. You can use these profiles to identifysections of your UniBasic application that are called most frequently, and then focus optimizationefforts 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 inthe profile reports.
2. Run the programs with -G
To profile a UniBasic program, run the program with the -G option. See Developing UniBasicApplications 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 run. Output files arecalled profile.pid and profile.elapse.pid where pid is the process ID of the user’s UniDataprocess.
The following screen shows a sample profile for a UniBasic program:
3. Review the profile output
233
In this example, the main program is called MAIN_PROG. It has three internal functions, namedSUBRA, 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 thebottom section presents detail. The following table describes the fields in the top section of a UniBasicProfile display. There is one line for each function of the program.
Field Description
%time Percentage of the total run time that is used by the program orsubroutine.
cumsecs Running sum of seconds for this program or subroutine and allcalled programs and subroutines that are 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.
UniData sorts program functions by execution time, and assigns an index to each function for easeof reporting. For each index, UniData computes information about functions that call, or are calledby, the function corresponding to the index. The detail section of a profile contains this information,which is grouped by index. The next table describes the fields in the detail section.
Chapter 22: Performance monitoring and tuning
234
Field Description
index An identifying number that is assigned by UniData to the programor subroutine. UniData assigns the indexes in descending orderof execution time. The index in column 1 identifies the routine ofinterest for the group of data (the current index function).
%time Percentage of the total program runtime that is used by theprogram or subroutine and its descendants.
self Time that is spent by the program or subroutine either calling, orbeing called by, the program or subroutine that is identified by thecurrent index.
Descendants Execution time for descendants of this program or subroutine.called Line contents differ according to the line of the subsection you are
reading:
called/total—lines above the index analyze parents; lists numberof times this index is called by the parent that is listed in the namefield.
called+self—line that contains the index; lists number of times theroutine is called and the number of times it calls itself.
called/total—lines below the index number analyze children anddescendants; lists number of times this index calls the child that islisted in the name field.
name Name of the program or subroutine analyzed in this row of thereport subsection.
index Index value that is assigned to the program or subroutine that islisted in the name field.
The following screen shows one group of data, which is selected from the sample UniBasic profile:
This subset of the report contains data relative to the internal SUBRA, which is identified by indexnumber 2. “Parent” functions, or functions that call SUBRA, are listed above it; “descendants,” orfunctions that are 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 bySUBRA. The function is called once by the main program, BP/MAIN_PROG.
UniData performance monitoring: udtmonThe UniData Monitor Utility, udtmon, enables you to monitor various characteristics at the systemlevel. Many of these characteristics can impact performance. Invoke the UniData Monitor Utility byentering the UniData system-level command udtmon at a UNIX prompt.
UniData performance monitoring: udtmon
235
Note: You do not need to log in as root to run udtmon.
The following screen shows the main UniData Monitoring menu.
Select Display to produce a second menu as shown in the following example.
You can select either a text display or a graphic display. The following two screens show theappearance of a graphic display and a text display, respectively:
Chapter 22: Performance monitoring and tuning
236
Note: In Graphic mode, Display provides a series of lines that reflect the current numberof operations that are covered by the display. You can configure this display by using theConfiguration menu. By default, 10 operations per second produces a full-width display.
Note: In text mode,Display provides five columns of numerical data that reflect the current,average, minimum, maximum, and total number of operations that are covered by the displaysince Monitor/Profile was started. Data is reported in operations per second. The default displayinterval is 3 seconds; you can modify the interval by using the Timer option of the Display menu.
Selecting Display from the Display menu produces a list of characteristics you can monitor. Thescreen looks like the following example:
udtmon: UniData user statistics
237
Note: When you highlight an option on the menu, a brief description displays at the bottom of thescreen.
udtmon: UniData user statistics
When you select UniData User from the Display menu, the following screen appears:
Chapter 22: Performance monitoring and tuning
238
udtmon: file I/O statistics
When you select File I/O from the Display menu, the following screen appears:
The following table describes the fields in the File I/O display, and indicates considerations forperformance.
Field Description
File Open Number of file opens at the operating system level, from UniBasic OPENcommands. On UNIX, if the average value in this field is more than 10(opens per second), performance may suffer. Consider opening files innamed common, and using pointers for subsequent access.
File Close Number of file closes at the operating system level, from UniBasicCLOSE commands.
Temp File Close When requests for file opens exceed the limit of open files per process,UniData temporarily closes the least recently accessed open file. Ifthe average value in this field is consistently more than zero, considerincreasing the kernel parameter that defines the number of open filesper process, and increase the UniData configuration parameter NFILES.
Record Read Number of records that are read by UniData commands (other thanUniQuery). For most applications, Record Read is greater than RecordWrite.
Record Write Number of records that are written by UniData commands (other thanUniQuery).
Record Delete Number of records that are deleted by UniBasic commands (other thanUniQuery).
Level 1 Overflow Number of operations (reads, writes, and deletes) to records in level1 overflow blocks. Compute the total activity by adding Record Read,Record Write, and Record Delete. If you are using only static files andLevel 1 Overflow is more than 10% of the total activity, use guide toanalyze your files and resize them appropriately.
udtmon: program control statistics
239
Field Description
Level 2 Overflow Number of operations (reads, writes, and deletes) to records in level2 overflow. If Level 2 Overflow is more than 2% of total activity, usecheckover or guide to identify files in level 2 overflow and resizethem appropriately.
udtmon: program control statistics
Selecting Program Control from the Display menu produces a screen similar to the followingexample:
The following table describes the fields in the Program Control display, and indicates performanceconsiderations.
Field Description
Local Call Number of calls to locally cataloged UniBasic programs. Locallycataloged UniBasic programs involve heavy I/O activity andincreased memory demand, because each local call loads a copyof the executable in memory. In a development environment,using locally cataloged programs may be normal. In a productionenvironment, if more than 5% of calls are to locally catalogedprograms, examine your application and globally catalogprograms for more efficient memory use.
Global Call Number of calls to globally cataloged UniBasic programs. In aproduction environment, this number should be much higherthan Local Call. If a program is globally cataloged, users share asingle copy of the object code in memory, which reduces bothmemory requirements and physical I/O load.
CALLC Call Number of calls to an external C function, from UniBasic CALLCstatements.
CHAIN Call Number of UniBasic CHAIN statements run.
Chapter 22: Performance monitoring and tuning
240
Field Description
GOSUB Call Number of UniBasic GOSUB commands run.LOOP and GOTO Number of UniBasic LOOP or GOTO commands run.EXECUTE Call Number of external UniData command executions (from
UniBasic EXECUTE commands).PCPERFORM Call Number of PCPERFORM statements, which run shell or host
operating system tasks. If PCPERFORM call is more than 5%of the total activity, analyze your application and considerreplacing PCPERFORM logic with C routines.
SLEEP Number of UniBasic SLEEP command executions. A suddenincrease in this number may indicate that a number of users areattempting to get a lock on a record.
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 the following table.
Field Description
COUNT Number of dynamic array counts, from COUNT command.DELETE Number of dynamic array deletions, from DEL command.EXTRACT Number of dynamic array data extractions, from EXTRACT
command.FIELD Number of dynamic array string extractions, from FIELD command.FIND Number of dynamic array finds, from FIND command.INDEX Number of dynamic array substring indexes, from INDEX command.INSERT Number of dynamic array inserts, from INS command.LOCATE Number of dynamic array locations, from LOCATE command.
udtmon: lock statistics
241
Field Description
MATCHFIELD Number of dynamic array substring matches, from MATCHFIELDcommand.
MATPARSE Number of dynamic array matrix parses, from MATPARSEcommand.
REMOVE Number of dynamic array element removals, from REMOVEcommand.
REPLACE Number of dynamic array replacements, from REPLACE command.
udtmon: lock statistics
The following table describes the fields of the Lock Statistics display, and indicates performanceconsiderations:
Field Display
Record Lock Number of user-level record locks set by commands such as READLand READU.
Record Unlock Number of user-level locks that are released by commands such asRELEASE.
Semaphore Lock Number of user-level resource locks set by commands such as LOCKand T.ATT.
Semaphore Unlock Number of user-level resource locks released by commands such asT.DET or UNLOCK.
Shared Group Lock UniData-level shared lock on an entire group.Excl. Group Lock UniData-level exclusive lock on an entire group. For most
applications, the number of shared group locks exceeds the numberof exclusive group locks. If the number of exclusive group locks isgreater than the number of shared group locks, one or more files maybe overflowed. Identify these locks with guide.
Shared Index Lock UniData-level shared lock on an index.Excl. Index Lock UniData-level exclusive lock on an index. For most applications, the
number of shared index locks exceeds the number of exclusive indexlocks. If the number of exclusive index locks is larger than the numberof shared index locks, one or more index files may be overflowed.Identify these locks with LIST.INDEX.
End-of-File Lock UniData-level lock that is required when UniData extends a file byadding overflow groups or by splitting a dynamic file. If this numberis consistently greater than zero, and the Dynamic File statistics donot show splitting and merging, one or more files overflowed. Identifythese and resize them for improved performance.
Lock Failure Number of times a process attempts to get a user-level lock and failsbecause the record is already locked. If performance is suffering,analyze your application for improper lock handling.
GLM Lock Request Number of times a udt process checks the global lock manager toget a lock.
GLM Lock Failure Number of times a udt process attempts to get a lock from the globallock manager and fails because the record is already locked.
Chapter 22: Performance monitoring and tuning
242
Note: In some circumstances, this screen may indicate that more records are being unlocked thanare being locked. This is a function of how UniData gathers the statistics and does not indicate aproblem.
udtmon: sequential I/O statistics
Selecting Sequential I/O displays statistics for I/O operations on sequential files. The following screenshows 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.OSREAD Number of UniBasic OSREAD executions.OSWRITE Number of UniBasic OSWRITE executions.COMO Write Number of writes to a COMO file.
udtmon: data conversion statistics
Selecting Data Conversion Statistics from the Display menu produces a screen similar to thefollowing example.
udtmon: index statistics
243
The information displayed on the screen provides an overview of a UniBasic application in terms ofdata handling. The following table describes the actions that are counted in the Data ConversionStatistics display:
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 internal
format.OCONV Converting strings from UniData internal format to an external format.SEQ Determining the numeric value of an ASCII character.
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.
Chapter 22: Performance monitoring and tuning
244
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+ treestructure, and a node is analogous to a block in a hashed file.
Node Write Number of index node writes.Node Merge Number of times two nodes merge; this merge takes place when
entries in one or both nodes decrease.Node Split Number of times an index node splits; this split happens when
entries in the original node increase. An unusual amount of split/merge/reuse activity indicates that one or more indexes are notproperly sized. Use the ECL LIST.INDEX command to identifythese indexes, and then run DELETE.INDEX...ALL, andCREATE and BUILD the indexes with a longer key length.
Node Reuse Number of times a node that is previously freed by a node mergeis used for a node split.
Log Read Number of reads from an index log file; these occur when an indexthat was disabled is reenabled and updated with the contents ofthe index log.
Log Write Number of writes to an index log file. These occur while an indexis disabled, as UniData tracks changes by recording them in theindex 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.
udtmon: Mglm performance
245
Note: Notice in the sampleIndex Statistics display the number of Overflow Reads and OverflowWrites indicates that one or more index may be improperly sized.
udtmon: Mglm performance
When you select Mglm Performance, the following screen displays.
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 the specifiedtime 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 specified time
interval. This type of locking is the most frequently used, andreflects I/O performance.
Mglm Upgrade Number of upgrade locking operation in the specified timeinterval. If no index related operations occur, this number maybe 0.
Mglm Downgrade Number of downgrade locking operations in the specified timeinterval.
Mglm Release Number of release locking operations in the specified timeinterval.
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 the
specified time interval. This number should be low.
Chapter 22: Performance monitoring and tuning
246
Field Description
Toggle Rate Toggle Failure / Total Latch. This rate should be low. Ifthe number 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 + Mglm Upgrade
+ Mglm Downgrade). This number is used to check I/Operformance and should be low.
247
Chapter 23: Account-based licensingThis chapter describes how to use UniData’s account-based licensing system.
Using account-based licensing, the number of purchased licenses can be divided to different accountsor group of accounts. These account groups are referred to as logical account IDs. The number oflicenses can be configured to allocate to each logical account ID, and then UniData will automaticallymanage the licenses consumed based on the defined configuration.
At the current UniData version, if device licensing connections are in use, multiple logical account-based licensing groups cannot connect from the same client machine. This restriction does not applyto installations that do not have device licensing enabled.
Note: Account-based licensing does not support device licensing across multiple account groups.
Managing the license configurationTo define the license configuration, create a text file called acct_licn.def in the $UDTHOME/include directory on Windows or the usr/ud82/include directory on UNIX/Linux. The followingexample illustrates the format of this file:
Note: UniData treats any line beginning with “#” as a comment.
The Licn Account ID column of the acct_licn.def file defines the logical account ID, whichcan contain any number of accounts. In the above example, the demo-acct ID contains the C:\disk1\u2demo1 and C:\disk1\uddemo2 accounts. The fully qualified path must be specifiedfor each account.
The Seats/DB column specifies the number of regular licenses assigned to the account ID.
The Seats/CNPL column specifies the number of connection pooling licenses assigned to the accountID.
The Account Description column can contain any information you want to add about the account IDs.
The total number of seats specified for Seats/DB and Seats/CNPL cannot exceed the total number oflicenses purchased. If the sum of logical account database seats is less than the number of purchasedlicenses, the remaining licenses will be used by the Default group. The Default group is a catch-all thatis composed of all accounts not explicitly specified in a logical account ID group.
Note: When connecting to UniData through one of the database tools, the tool connects to theUniData demo account by default.
Chapter 23: Account-based licensing
248
Managing account-based licensing with listuser -a
You can use the listuser -a command with one of the following parameters to manage account-based licensing:
▪ check
▪ list
▪ reload
Verifying the acct_licn.def file
Use the listuser -a check command to check the syntax of the acct_licn.def file andreport any errors.
If a syntax error exists in the acct_licn.def file, UniData ignores all definitions in the file and startsUniData as if there was no acct_licn.def file.
Note: Make sure there is no leading space before the account ID.
The following example illustrates using the listuser -a check command to verify theacct_licn.def file:
[root@den-vm-t19 include]# listuser -a checkChecking "/usr/ud82/include/acct_licn.def" ......Everything is OK.
Listing the acct_licn.def file
Use the listuser -a list command to list the contents of the acct_licn.def file, as shownin the following example:
Reloading the acct_licn.def file
If you make changes to the acct_licn.def file, you must reload the file for the changes to takeeffect. The next example shows how to reload the file using the listuser -a reload command:
Reloading the acct_licn.def file
249
Note: If reloading the acct_licn.def encounters an error, UniData does not replace thecurrent configuration.
If you change the number of licenses allocated to an account and the number of users currently loggedon exceeds that number, UniData displays an error. Users need to log out of the account until the limitis not exceeded before UniData loads the new configuration.
250
Appendix A: UniData configuration parametersThis appendix lists the names and descriptions for all UniData configuration parameters.
Refer to Configuring your UniData system, on page 48 for additional information about modifying yourudtconfig file.
The following tables describe the configuration parameters that are placed in the udtconfig filelocated in \udthome\include at the time of installation. They are system-dependent and shouldnot be changed.
Parameter Description
LOCKFIFO The locking sequence of processes in the system. This parametershould not be changed.
SYS_PV Type of P/V operations used for the Recoverable File System (RFS)only. Determined at installation; platform dependent. Do not changeunless instructed by Technical Support.
The following parameters may be changed to suit your environment:
Parameter Description
NFILES Number of physical files that can be opened at the operating systemlevel at one time in a UniData session. This limit is for both udt andtm processes; the name of the corresponding kernel parameter variesamong UNIXOS versions.
NUSERS Limit for number of UniData user processes (such as udt andPHANTOM) that can run at the same time.
WRITE_TO_CONSOLE Switch for turning on and off messaging to your console. Must begreater than zero for messages to display at console.
TMP Path of a UNIX directory for storing intermediate work files. Defaultis \U2\ud82\temp on UniData for Windows Platforms or /tmp/ onUniData for UNIX. When changing this parameter on UniData for UNIX,do not forget the trailing “/.”.
NVLMARK Specifies a character to print to represent the null value. The ASCIIcharacter that represents the null value is nonprinting.
FCNTL_ON Used with UniData Physical Lock Manager. If a UNIX platform supportstest-n-set instruction, SYS_PV is set to 3 and FCNTL_ON is set to 0. If aUNIX platform does not support test-n-set instruction, SYS_PV is setto 2 and FCNTL_ON is set to 1. Do not change this parameter unlessinstructed to do so by Technical Support.
TOGGLE_NAP_TIME If FCNTL_ON is set to 0, the length of time (in milliseconds) that aprocess waits to access a shared memory address held by anotherprocess. This parameter has no effect if FCNTL_ON is set to 1. Do notchange unless instructed to do so by Technical Support.
TOGGLE_NAP_TIME_NS If FCNTL_ON is set to 0, the length of time (in nanoseconds) that aprocess waits to access a shared memory address held by anotherprocess. On UniData for UNIX, this parameter is used together withTOGGLE_NAP_TIME. On UniData for Windows, this parameter is notused. Do not change this parameter unless instructed by RocketSoftware.
NULL_FLAG Toggles null value handling on and off. If 0, null value handling is off.Must be greater than 0 for null value handling to be in effect.
UniData configuration parameters
251
Parameter Description
QUOTED_IDENTIFIER When the value of QUOTED_IDENTIFIER is 1, identifiers can bedelimited by double quotation marks, and literals must thenbe delimited by single quotation marks. When the value ofQUOTED_IDENTIFIER is 0, identifiers cannot be quoted, and literalscan be delimited by either single or double quotation marks.
N_FILESYS Maximum number of UNIX file systems allowed. If you have more than200 UNIX file systems, increase to your number of file systems.
N_GLM_GLOBAL_BUCKET The number of hash buckets system-wide, used to hold the locknames 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 yourapplication intensively accesses specific files, you can increase thisparameter. The default value is the closest prime number to NUSERS* 3.
N_GLM_SELF_BUCKET The number of hash buckets for the per-process locking table. Thisparameter is highly application dependent. If the application requiresa large number of locks in one transaction (more than 20), you shouldincrease this setting to the closest prime number to the maximumnumber of locks per transaction.
GLM_MEM_ALLOC Defines the number of lock nodes allocated for each memory request,and is highly application dependent. If your application requiresa large number of locks in one transaction, this setting should beincreased to the maximum number of locks per transaction *2.
GLM_MEM_SEGSZ The segment size for each shared memory segment required forthe lock manager. The maximum number of segments is 16. Largeapplication environments require a larger size. Each udt will registerthe lock names it is locking in its per-process locking table. This tableis also organized as a hashed table.
BGINPUTTIMEOUT The number of seconds a background or phantom process waitsbefore timing out. Before the timeout expires, a process may usethe UNIX tandem or the UniData for Windows Platforms TANDEMcommand to attach to the process.
LB_FLAG For nonrecoverable files, turn Transaction Processing on or offby changing the value of this parameter. If you set the valueto 0, Transaction Processing is off for nonrecoverable files andTP semantics are ignored. If you set the value to 1, TransactionProcessing is on.
Note: If RFS is on, the LB_FLAG has no effect on recoverable files. Youcannot turn off transaction processing for recoverable files if RFS isenabled.
USE_DF The USE_DF parameter enables you to choose how UniData loads theshared memory table. Beginning in UniData 7.2, the smm daemon nolonger forked a df process to create the entries in the shared memorytable, as it had in prior releases. Now, UniData loads the sharedmemory table by reading the mount table.
If you set the value of USE_DF to 0, UniData loads the shared memorytable by reading the mount table. This is the default setting.
If you set the value of USE_DF to 1, the smm process forks a df processto load the shared memory table.
Appendix A: UniData configuration parameters
252
Parameter Description
USE_DF Determines whether UniData reads the mount table or forks a dfprocess when you execute the sms -F command.
0 – UniData loads the shared memory table by reading the mounttable.
1 – UniData forks a df process to load the shared memory table.NFA_COMPAT_FLAG Determines if you can access an NFA file on UniData 7.2 or greater
from a version of UniData prior to 7.2. If the value of this parameter is0, the default, you cannot access an NFA file on UniData 7.2 or greaterfrom a version of UniData prior to 7.2. If this value is set to 1, you canaccess an NFA file on UniData 7.2 or greater from an earlier version ofUniData, but the file cannot be encrypted.
UDT_SPLIT_POLICY Determines if a dynamic file splits when an existing record is rewrittento the file without any changes. If the value of this parameter is set to1, rewriting an existing record to an overloaded group only triggers asplit if the record length changes. If the value of this parameter is setto 0, any update to an existing record in a dynamic file group that wasalready over the defined split load triggers a split for the file.
DEFAULT_HASH_TYPE The udtconfig parameter DEFAULT_HASH_TYPE was introduced at8.1.0. The value can be 0, 1, or 3. The default value for creating a newfile is TYPE is 3. If the hash type is not specified, then the value of theudtconfig parameter DEFAULT_HASH_TYPE will be used.
Old files will not be automatically resized to the value specified inDEFAULT_HASH_TYPE. Instead, they will remain in their current hashtype. Any change in type must be specified using the RESIZE orMEMRESIZE commands.
SINGLE_SAVEDLIST By default at UniData 8.1.0 and later, the saved list is stored asone item in the SAVEDLISTS directory. You may see a performanceimprovement during a DELETE.LIST operation, due to fewer filesbeing involved. This behavior can be returned to the original behaviorin UniData 7.3.x and earlier by setting the udtconfig parameterSINGLE_SAVEDLIST from 1 (default) to 0.
With SINGLE_SAVEDLIST set to 0, or using UniData 7.3.x or earlier, asaved list that exceeds approximately 34,810 characters on UniDatafor UNIX or 29,408 on UniData for Windows platforms is saved inmultiple parts. Each part has an extension to the specified saved listname, beginning at 000 and incrementing sequentially (001, 002, andso forth).
HTTP_DEFAULT_VERSION Specifies default HTTP version. The version defaults to 1.1. Validvalues are 1.0 and 1.1.
SSL_PROTOCOLS Specifies the protocols allowed using SSL connections. The allowedprotocols are: SSLv3, TLSv1, TLSv1,1 TLSv1,2. The valid delimiters are:comma(,), and the plus sign (+). Invalid protocols will be ignored. Ifthe parameter is not specified, or the resultant string is empty, thenTLSv1+TLSv1.1+TLSv1.2 will be the default.
UniData configuration parameters
253
Parameter Description
SSL_OPTIONS Specifies additional options that will be set for SSLconnections. The valid options are: TLS_FALLBACK_SCSV, andNO_TLS_FALLBACK_SCSV. The valid delimiters are: comma(,), and theplus sign (+). Invalid options will be ignored. If the parameter is notspecified, or the resultant string is empty, then TLS_FALLBACK_SCSVwill be the default. When TLS_FALLBACK_SCSV is specified, protocoldowngrade will not be allowed during the SSL session handshake,preventing the POODLE attack.
The following parameter is related to internationalization.
Parameter Description
UDT_LANGGRP The language group ID used to distinguish language groups that usesimilar special characters. UDT_LANGGRP is composed of the recordmark, escape sequence mark, and the null value mark. The default is255/192/129.
ZERO_CHAR The character you want to use to represent CHAR(0). See OSREAD,OSBREAD, READT in the UniBasic Commands Reference for moreinformation.
The following table describes shared memory related parameters. These parameters may be changedto suit your environment.
Parameter Description
SBCS_SHM_SIZE Size, in bytes, of shared memory segments created by sbcs to storeglobally cataloged programs. sbcs can attach a maximum of 20segments system-wide. Runtime errors result if a user attempts toload a new global program that exceeds this limit.
SHM_MAX_SIZE Current kernel setting for maximum size (in bytes) of a sharedmemory segment. This parameter is set at installation; if you increasethe kernel parameter shmmax, you need to increase SHM_MAX_SIZEto the same value as well.
SHM_ATT_ADD Starting address for shared memory attachment. Set at installation;do not change this unless instructed by Technical Support.
SHM_LBA Alignment size, in bytes, for shared memory attachment. Set atinstallation; do not change.
SHM_MIN_NATT The minimum number of shared memory segments that should bekept attached to a process.
SHM_GNTBLS Number of GCTs (global control tables) in CTL. Each shared memorysegment is associated with a GCT. The GCT registers the use of globalpages in its associated shared memory segment. Cannot exceed thekernel parameter shmmni.
SHM_GNPAGES Number of global pages in a shared memory segment.SHM_GPAGESZ Size of each global page, in 512-byte units.SHM_LPINENTS Number of entries in the PI table of a LCT, which is the number of
processes allowed in a process group. It is set to 10 within the system,regardless of the udtconfig setting.
SHM_LMINENTS Number of entries in the MI table of a LCT, which means the number ofglobal pages or self-created dynamic segments that can be attachedby a process. Cannot exceed 255.
Appendix A: UniData configuration parameters
254
Parameter Description
SHM_LCINENTS The number of entries in the CI table of each LCT, which is the numberof local pages that can be attached by a process. SHM_LCINENTSmust be greater than or equal to SHM_SHM_LMINENTS. Cannotexceed 255.
SHM_LPAGESZ Size, in 512-byte blocks, of each local page in a global page. A globalpage is divided into local pages, so SHM_GPAGESZ must be a multipleof SHM_LPAGESZ.
SHM_FREEPCT Percentage of freed global pages in an active global shared memorysegment that UniData keeps in the global shared memory pool.smm checks the current percentage; if the percentage is less thanSHM_FREEPCT, smm creates a new shared segment.
SHM_NFREES The number of inactive shared memory segments that UniData keepsin the system. smm checks the current number of inactive segments;if the number is larger than SHM_NFREES, smm returns some inactiveglobal shared segments to UNIX.
The following table describes size limitation parameters.
Parameter Description
AVG_TUPLE_LEN Number of local pages that matches the average length of recordsin your applications. Specifies the length of a buffer kept by udt forholding 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 bufferof this size for intermediate results. We recommend you set thisparameter so the buffer is one-quarter to one-half the size of a globalpage.
MAX_OBJ_SIZE Maximum size, in bytes, of object programs that can be loaded intoshared memory. Object programs larger than this size are loaded intothe user’s address space instead of shared memory.
MIN_MEMORY_TEMP The minimum number of local pages that should be kept fortemporary buffers in a process group. Determined at installation.
STATIC_GROWTH_WARN_TABLE_SIZE
The number of table elements in the Static Growth Warn table.UniData uses this table to track the last time a warning was issuedindicating a file was larger than the threshold. When no unusedelements are present in the table, UniData uses the oldest elementfor a new static file. If the file is nonrecoverable, UniData writesthe information to the udt.errlog file. If the file is recoverable,UniData writes the information to the sm.log file
STATIC_GROWTH_WARN_SIZE
The threshold value for the static file size, expressed in bytes. Ifthe file is nonrecoverable, UniData writes the information to theudt.errlog file. If the file is recoverable, UniData writes theinformation to the sm.log file
STATIC_GROWTH_WARN_INTERVAL
The time interval, expressed in seconds, to warn when a static file islarger than the threshold. If the file is nonrecoverable, UniData writesthe information to the udt.errlog file. If the file is recoverable,UniData writes the information to the sm.log file
The following table describes parameters related to dynamic files.
UniData configuration parameters
255
Parameter Description
GRP_FREE_BLK Pertains to dynamic files only; the number of free blocks kept in thefree block list at the group level. If more blocks are freed, they arekept at the file level.
SHM_FIL_CNT Maximum number of dynamic files that can be open concurrently,systemwide.
SPLIT_LOAD Default loading factor option (percent) at which a group in a dynamicfile using the KEYONLY option splits. Splitting occurs when thepercentage of space in a group occupied by keys and pointers reachesthe split load. The ECL CONFIGURE.FILE command overrides thisfor individual files.
MERGE_LOAD Default loading factor (percent) at which a group pair in a dynamicfile using the KEYONLY option merges. A group pair is eligible formerging when the sum of the percentages of space occupied bykeys and pointers in both groups is less than MERGE_LOAD. TheCONFIGURE.FILE command lets users override this for individualfiles.
KEYDATA_SPLIT_ LOAD Default loading factor (percent) at which a group in a dynamic fileusing the KEYDATA option splits. Splitting occurs when the percentageof space in a group occupied by keys and pointers reaches the splitload. The ECL CONFIGURE.FILE command overrides this forindividual files.
KEYDATA_MERGE_LOAD Default loading factor (percent) at which a group pair in a dynamicfile using the KEYDATA option merges. A group pair is eligible formerging when the sum of the percentages of space occupied by keysand pointers in both groups is less than KEYDATA_MERGE_LOAD. TheCONFIGURE.FILE command overrides this for individual files.
MAX_FLENGTH Upper size limit, in bytes, of each partition file (dat00x) of a dynamicfile. When a part file reaches this size, UniData does not add furtherblocks to it, but creates another part file using the part table. Thedefault value is 1073741824 bytes (1 GB). Must be greater than 32768bytes (32 KB) and less than 2147467264 bytes (2 GB-16KB).
PART_TBL Path of a UNIX text file that directs UniData where to create dynamicfile part files.
DEFAULT_SPLIT _STYLE This is the default split style for a dynamic file. The valid values are 1(KEYONLY), 2 (KEYDATA), or 3 (WHOLEFILE). The default value for thisparameter is 3, meaning that the new whole file split style will be thedefault.
WHOLEFILE_ SPLIT_LOAD This is the default split load for a whole file split style dynamic file.The value must be > 0 and <= 100 (can be 100; in such a case, no splitwill occur, which would tell the system not to split). The default valueis 75.
WHOLEFILE_ MERGE_LOAD This is the default merge load for a whole file split style dynamic file.The value must be >=0 and < WHOLEFILE_SPLIT_LOAD (can be 0; insuch a case, no merge will occur). The default value is 40.
The following parameter is for NFA server.
Parameter Description
EFS_LCKTIME Used by the NFA Server to specify the maximum time to wait for alock.
Appendix A: UniData configuration parameters
256
Parameter Description
TSTIMEOUT Used by the udtts executable to specify the maximum number ofseconds to wait for input from client about device information. Ifthe information is not provided, UniData starts without the deviceinformation.
NFA_CONVERT_CHAR If this value is set to 1, UniData converts marks in a stream of data tohost-specific marks.
NFA_COMPAT_FLAG Determines if you can access an NFA file on UniData 7.2 or greaterfrom a version of UniData prior to 7.2. If the value of this parameter is0, the default, you cannot access an NFA file on UniData 7.2 or greaterfrom a version of UniData prior to 7.2. If this value is set to 1, you canaccess an NFA file on UniData 7.2 or greater from an earlier version ofUniData, but the file cannot be encrypted.
The following table describes parameters related to journaling:
Parameter Description
JRNL_MAX_PROCS Maximum number of journal processes per journal path.JRNL_MAX_FILES Maximum number of journal files allowed per journal process.
The following table describes UniBasic file-related parameters.
Parameter Description
MAX_OPEN_FILE Maximum number of hashed files that can be opened by UniBasicOPEN statements, per udt process. Includes recoverable andnonrecoverable, static, dynamic, and sequentially hashed files; eachdynamic file counts as one file.
MAX_OPEN_SEQF Maximum number of sequential files that can be opened at one timeby UniBasic OPENSEQ statements, per udt process.
MAX_OPEN_OSF Maximum number of UNIX sequential files that can be opened at onetime by UniBasic OSOPEN statements, per udt process.
MAX_DSFILES Maximum number of nonrecoverable dynamic part files (dat00x,over00x) a UniData process can open with UniBasic OPEN statementsor ECL commands. Each dynamic file has at least two part files.
DEFAULT_HASH_ TYPE This is the default hash type for the hashed file to be created. Thevalid values are 0, 1, or 3. The default value for this parameter is 3,meaning that the new UniData hash function will be the default.
The following table describes parameters related to UniBasic.
Parameter Description
MAX_CAPT_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITHCAPTURING or MDPERFORM WITH CAPTURING clauses. Individualusers can set an environment variable that overrides theconfiguration parameter.
MAX_RETN_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITHRETURNING or MDPERFORM WITH RETURNING clauses. Individualusers can set an environment variable that overrides theconfiguration parameter.
UniData configuration parameters
257
Parameter Description
COMPACTOR_POLICY Used to guide BASIC memory compactor to do compaction for BASICstrings.
0 — compact when program is finished
1 — compact when EXECUTE (another BASIC pgm) is completed
2 — compact when EXECUTE (another BASIC program) or CALL iscompleted
VARMEM_PCT The percentage of free memory that should be kept in the first globalpage for UniBasic variables after compacting. If the actual percentageis less than this value, UniData keeps one free global page. Otherwise,UniData returns all free global pages to UNIX.
The following parameter is used in semaphore operations.
Parameter Description
NSEM_PSET Number of semaphores per semaphore set.
The following table describes index-related parameters.
Parameter Description
SETINDEX_BUFFER_ KEYS Controls whether READFWD and READBCK statements use a bufferingmechanism. Default value is 0 (buffering off). Individual environmentvariable overrides udtconfig setting; BUFFER.KEYS keyword in theSETINDEX statement overrides either.
SETINDEX_VALIDATE_KEY Controls whether READFWD and READBCK statements validate akey value just read. Default value is 0 (no validation). Individualenvironment variable overrides udtconfig setting. VALIDATE.KEYkeyword in the SETINDEX statement overrides either.
The following parameter is used with the UniData physical lock manager.
Parameter Description
MGLM_BUCKET_SIZE Number of nodes per bucket. If this parameter is inadequate for anapplication, UniData displays an out of memory message is.
UPL_LOGGING Determines if UPL performs logging. If this parameter is set to 0, UPLdoes not perform any logging. If this value is set to 1, UPL performslogging.
The following parameters affect the UniData _HOLD_ file.
Parameter Description
MAX_NEXT_HOLD_DIGITS Enables you to specify the number of digits used for the next _HOLD_file number, found in the NEXT.HOLD record of D__HOLD.
CHECK_HOLD_EXIST Determines if UniData checks for the existence of a _HOLD_ file priorto unconditionally removing it when you specify the BANNER UNIQUEoption with the SETPTR command.
The following parameter is used to turn the Recoverable File System off and on.
Parameter Description
SB_FLAG Toggles system buffer on and off. If zero, system buffer is off. Must begreater than zero for RFS.
Appendix A: UniData configuration parameters
258
Parameter Description
SB_PAGE_SZ Specifies the size of the system buffer page. Valid values are 1 through16, where 1 specifies 1K, 2 specifies 2K, and so forth. The default valueis 1.
The following parameters are related to open files with the Recoverable File System.
Parameter Description
BPF_NFILES Per-process logical limit for total number of recoverable files thatcan be opened with UniBasic OPEN statements at one time. If morerecoverable files are opened, UniData closes files and then reopensthem, causing heavy overhead. This parameter cannot exceed N_AFT.
N_PARTFILE System-wide total number of recoverable dynamic part files thatcan be open at one time. This limit includes files opened by ECL andUniBasic. Each dynamic file has at least two part files, so opening adynamic file means opening at least two part files. Even if more thanone user opens the same dynamic file, each part file is counted oncetoward the total.
The following parameters are related to the active file table (AFT) used with the RFS.
Parameter Description
N_AFT System-wide limit on the number of recoverable files and indexesthat can be open at one time. This is the number of slots in the systembuffer AFT. Parameter is like MAX_OPEN_FILES but pertains only torecoverable files. A dynamic file counts as one file. Even if more thanone user opens the same file, it is only counted 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 multilevel files. Used
for RFS only.N_TMAFT_BUCKET Number of hash buckets in each tm process’s active file table (TMAFT).
Used for RFS only.
The following table describes parameters related to the archiving feature of RFS.
Parameter Description
ARCH_FLAG Toggles archiving function on and off for RFS. Must be greater than 0for archiving.
N_ARCH The number of archive files.ARCHIVE_TO_TAPE Switch for turning on automatic save of archive files to backup.
Changing the value to 1 turns on this feature.ARCH_WRITE_SZ Size, in bytes, of blocks for the archive process to write from the log
files to the archive files. Default is zero, meaning each write is oneblock. If set to a nonzero value, must be a multiple of the log/archiveblock size.
The following parameters are used for the system buffer in the RFS.
UniData configuration parameters
259
Parameter Description
N_BIG Number of block index groups. This parameter determines the sizeof an index table for accessing the RFS system buffer. If you enlargeN_PUT, you should enlarge N_BIG as well. Must be a prime number.
N_PUT Number of 1,024-byte pages in the system buffer. The size of thebuffer cannot exceed SHMMAX. Sometimes the default value of N_PUTmust be decreased in order to complete a UniData installation.
The following table describes parameters used for message queues with the Recoverable File System.
Parameter Description
N_PGQ Number of message queues for tm processes to send messages toudt processes. Calculated by installation; one queue for every fourlicenses.
N_TMQ Number of message queues for udt processes to send messages totm processes. Calculated by installation; one queue for every fourlicenses.
The following table describes the parameter related to the IPC mechanism between the udt and tmprocesses on Windows platforms only.
Parameter Description
UDT_TM_IPC On UniData for UNIX, the udt and tm processes communicate usingmessage queues. Since message queues are not available on Windowsplatforms, UniData provides three options for the communicationbetween the udt and tm processes:
▪ UDT_TM_IPC=1 – UniData uses its own message queues tocommunicate between the udt and tm processes. If you changethe value of the N_PGQ or N_TMQ udtconfig parameters, you mustalso change the value of the MSGMNI configuration parameter.The value of MSGMNI should be 12+N_PGQ+N_TMQ.
▪ UDT_TM_IPC=2 – UniData uses named pipes as thecommunication mechanism between the udt and tm processes.Each udt process creates two named pipes, one for the udt processto write and the tm process to read, and one for the tm process towrite and the udt process to read.
▪ UDT_TM_IPC=3 – UniData uses memory-mapped files and eventsto communicate between the udt and tm processes. Each udtprocess creates 2K memory-mapped files when it starts.
The default value for the UDT_TM_IPC udtconfig parameter is 3
The following table describes parameters related to the before image and after image log files usedwith RFS.
Parameter Description
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.
Appendix A: UniData configuration parameters
260
Parameter Description
AIMG_MIN_BLKS Minimum number of blocks required in the after image buffer beforethe system flushes the blocks to the after image logs. Block size is setin the log configuration table.
BIMG_MIN_BLKS Minimum number of blocks required in the before image buffer beforethe system flushes the blocks to the before image logs. Block size isset in the log configuration table.
AIMG_FLUSH_BLKS Number of blocks that are flushed to the after image logs from theafter image buffer at one time.
BIMG_FLUSH_BLKS Number of blocks that are flushed to the before image logs from thebefore image buffer at one time.
RFS_DUMP_DIR Defines where UniData stores the rfs.dump file when you executethe s_stat -s command. The default value is UDTHOME\bin, withUniData storing the rfs.dump file in the UDTBIN directory.Thedefault value is an empty string, with UniData storing the rfs.dumpfile in the $UDTBIN directory. If the path you specify is invalid whenUniData starts, UniData writes the rfs.dump file to the $UDTBINdirectory, and prints a message to the sm.log.
RFS_DUMP_HISTORY Specifies how many rfs.dump files to preserve when you executethe s_stat -s command.
The default value is 1. With this value, UniData creates the rfs.dumpfile in the directory you specify with the RFS_DUMP_DIR parameter.
If this value is set to a positive integer, for example 4, the rfs.dumpfiles will be named rfs.dump1, rfs.dump2, rfs.dump3,and rfs.dump4. The s_stat -s command uses the first availablerfs.dump file. If all rfs.dump files are full, s_stat -s reuses theoldest rfs.dump.file.
If this value is set to 0, all rfs.dump files are preserved and namedrfs.dump1, rfs.dump2, and so forth.
The following table describes the parameters that determine flushing intervals for RFS.
Parameter Description
CHKPNT_TIME Checkpoint interval: number of seconds between flushes of thesystem buffer to disk.
GRPCMT_TIME Interval, in seconds, between flushes to the after image log set.LOG_OVRFLO Path to the directory where UniData creates log overflow files.
The following table describes the parameters related to the sync daemon.
Parameter Description
N_SYNC Determines how many sync daemons UniData should start.SYNC_TIME Defines the number of seconds the sync daemon should wait before
scanning the Block Index Group to flush dirty pages.
The following table describes Windows platform message queue parameters.
Parameter Description
MSGMNI The maximum number of message queues available for UniDatasystem-wide.
MSGMAX The maximum size of a message.
UniData configuration parameters
261
Parameter Description
MSGTQL The maximum number of messages allowed system-wide.MSGTX The default text size of a message per node.
The following table describes the parameter related to the century pivot date.
Parameter Description
CENTURY_PIVOT Determines the century pivot date. Default is 1930.
The following table describes the parameters related to U2 Data Replication.
Parameter Description
REP_FLAG The REP_FLAG parameter turns U2 Data Replication on or off. If youchoose to install UniData with the replication system, UniData setsthe REP_FLAG to 1.
If this value is 0, U2 Data Replication is off. If this value is a positiveinteger, it is on.
TCA_SIZE The maximum number of entries in the Transaction Control Area(TCA). TCA is only used when there is more than one replication groupconfigured, and there are transactions across replication groups. Thedefault value is 2048.
If you are not using transaction processing, this parameter isirrelevant. If you are using transaction processing, set the value ofTCA_SIZE to at least the number of users on the system.
MAX_LRF_FILESIZE he maximum log reserve file size, in bytes. The default value is1,073,741,824 (1 GB). The maximum value is 2,147,483,136.
N_REP_OPEN_FILE he maximum number of open replication log files for a udt or tmprocess. The default value is 8.
MAX_REP_DISTRIB Reserved for internal use.MAX_REP_SHMSZ The maximum shared memory buffer segment size. The default value
is 1,073,741,824 (1 GB).REP_LOG_PATH The full path to the location of the replication log file.UDR_CONVERT_CHAR When this value is set to 1, if the publishing system and the
subscribing system have a different I18N group, UniData convertsmarks and SQLNULL marks to those on the local machine on the datapassed between the two systems. The default value is 0.
REP_CP_TIMEOUT Specifies the cm daemon timeout interval for replication atcheckpoint. The default value is 200 seconds. If this value is set to 0the cm daemon will not time out.
The following table describes the parameters related to Euro processing.
Parameter Description
CONVERT_EURO Turns Euro conversion on or off. If this flag is set to 0, UniData doesnot perform conversion. If this flag is set to 1, UniData performsconversion.
SYSTEM_EURO The configurable system Euro encoding. On UNIX systems, the defaultis CHAR(164). On Windows Platforms, the default is CHAR(128).
TERM_EURO Sets the terminal system Euro Code. On UNIX systems, the default isCHAR(164). On Windows Platforms, the default is CHAR(128).
Appendix A: UniData configuration parameters
262
The following table describes the udtconfig parameter that determines if a dynamic file splits if anexisting record is updated.
Parameter Description
UDT_SPLIT_POLICY Determines if a dynamic file splits when an existing record is rewrittento the file without any changes.
If the value of this parameter is set to 1, rewriting an existing record toan overloaded group only triggers a split if the record length changes.If the value of this parameter is set to 0, any update to an existingrecord in a dynamic file group that was already over the defined splitload triggers a split for the file.
Starting at UniData 8.1 and UniVerse 11.3, you can configure system wide SSL connection behaviorswith two new udtconfig/uvconfig parameters: SSL_PROTOCOLS and SSL_OPTIONS. Followingindustry trend, SSLv3 is turned off by default.
263
Appendix B: Environment variables for UniDataThis appendix lists environment variables that can be set at the UNIX level to customize a UniDataenvironment. Users with access to the UNIX prompt can set them before entering UniData to affect aparticular UniData session. System administrators can also set them in a .login or .profile for one ormore users to establish defaults for some or all users.
The following table lists environment variables in alphabetical order.
Environment variable Description
ALLOW_DBPAUSE_ OSBWRITE When this environment variable is set to 1, an OSBWRITE processis successful even if dbpause if active. If the environment variableis set to 0, an OSBWRITE process pauses.
BACKUP_CNTL_FILE Used by the Recoverable File System (RFS); specifies a pathwhere the udt.control.file can be automaticallybacked up at checkpoint time. If this variable is not defined,udt.control.file is not backed up. Valid on UniData forUNIX only.
CSTACKSZ Establishes the maximum number of commands in the ECLcommand stack. Each stack entry can hold a 2720 charactercommand. The default is 49.
Note: If you change CSTACKSZ for your changes to take effect,you must restart UniData.
INIT_BREAKOFF
[0 | 1]
Enables/disables break key prior to invoking UniData. IfINIT_BREAKOFF is not set, the break key is enabled by default.
LPREQ Identifies an alternate spooler directory. Must be a full pathending in “/”.Valid on UniData for UNIX only.
MAX_CAPT_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITHCAPTURING or MDPERFORM WITH CAPTURING clauses. Thisenvironment variable overrides the configuration parameter inthe udtconfig file.
MAX_RETN_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITHRETURNING or MDPERFORM WITH RETURNING clauses. Thisenvironment variable overrides the configuration parameter inthe udtconfig file.
MAX_TRANS_FIELD Number of TRANS fields that can be kept concurrently; defaultvalue is 12; must not be greater than 64.
MAX_TRANS_REL Number of TRANS files that can be open concurrently; defaultvalue is 32; must not be greater than 32.
NFA_LOG_DIR Used by NFA; name of a UNIX directory where UniData createsNFA client-side. If this variable is not defined, the logs are createdin /tmp\temp.
NFA_LOG_LEVEL Used by NFA; debug level for NFA client processes. May be aninteger 0-10; level 0 logs only fatal errors, and level 10 logs alltraffic and many internal functions. The default is level 0.
NOCHKLPREQ Bypasses UNIX printer verification; useful for large systems withhundreds of printers defined. Valid on UniData for UNIX only.
Appendix B: Environment variables for UniData
264
Environment variable Description
PHANTOM_WAIT The PHANTOM_WAIT environment variable specifies the numberof seconds to wait before populating the CAPTURING variable andreturning to the main program. If you set this value to 0, there isno delay before populating the CAPTURING variable.
SETINDEX_ BUFFER_ KEYS Controls whether READFWD and READBCK statements usea buffering mechanism. Default value is 0 (buffering off).Individual environment variable overrides udtconfig setting;BUFFER.KEYS keyword in the SETINDEX statement overrides both.
SETINDEX_ VALIDATE_KEY Controls whether READFWD and READBCK statements validatea key value just read against the record. Default value is 0(no validation). Individual environment variable overridesudtconfig setting; VALIDATE.KEY keyword in the SETINDEXstatement overrides both.
SGLISTNUM Size of token stack for XREF, in UENTRY. Default is 500.SQL_TMP_MODULO Number of temporary files used by UniData SQL for an equal
join operation. Default is 7; if this is set to a number less than 7,UniData SQL uses the default. No upper limit. Must be set beforeentering udt/SQL, or before starting UniServer.
SUPPRESS_ORPHAN_BLOCK_ERROR
Determines if the guide utility reports orphan blocks. Orphanblocks could exist in both the primary file and the overflowfiles. guide reports these errors in the GUIDE_ERRORS.LISfile. If you want to suppress these messages, set the value ofSUPPRESS_ORPHAN_BLOCK_ERROR to a positive integer.
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\temp when additionalwork space is needed by UniData. Must be a directory path endingwith /\.
UDT_EDIT Identifies the path of the UNIX text editor UniData invokeswhen users execute the ECL ED command. The default is vi. Thisvariable cannot be set to AE.
UDT_INTERNAL1 Determines the number of sleep milliseconds for SYSTEM(14). Thedefault value is 15. Valid values are 0 to 500. If this environmentvariable is not set, SYSTEM(14) sleeps for 15 milliseconds if thereis no data in the input pipe. If it is set to 0, SYSTEM(14) returns thenumber of characters in the typeahead buffer without sleeping.
UDT_SAVELIST Allows you to specify a default list name for each UniData user.Set in the user’s .login or .profile. Users can also specify a listname when executing the SAVE.LIST command.
UDT_SELECTSIZE Size of a buffer used to keep select list in memory. If a select listis larger then the size of this buffer, UniData writes it to a file. IfUDT_SELECTSIZE is not defined, the system uses a buffer size of10 KB.
UDTBIN Location of UniData executables.UDTERRLOG_LEVEL Determines the logs to which file open errors are written. If the
value of this environment variable is equal to or greater than2, UniData writes file open errors to the udt.errlog, andon Windows platforms, to the Windows event log. Otherwise,UniData does not log file open errors.
UDTHOME Location of the UniData home directory, which containsdirectories including sys, demo, lib, work, sybase, and include.
Environment variables for UniData
265
Environment variable Description
VFIELDSIZE Increases the size for the stack of C routines used to processformulas created in virtual fields. Default is 300. Define a largernumber if users see “virtual field too big” errors in UniQuery.
VOC_READONLY If set to a nonzero number, allows UniData to run with read-onlyaccess to the VOC file.
VVTERMCAP The UNIX path of the vvtermcap file needed to run the UniDatacommands UENTRY, shmconf, and confprod. This variable isnot necessary if UDTBIN is defined.
266
Appendix C: Configuring SSL for Telnet
Server side configuration:To enable SSL for Telnet on UniData, you will need to edit four different files on the database server.The first two are system files named services and inetd.conf. Both of these files reside under the /etc directory on the unix server. Use vi or another suitable text editor to make the changes describedbelow.
Add the following line in /etc/services:
telnets 992/tcp
Where “telnets” is the service name. This can be any name of your choosing. 992 is the standard portnumber used for secure telnet servers and tcp is the protocol name for the service.
Add the following line in /etc/inetd.conf.
telnets stream tcp nowait root UDTBIN_PATH/udtelnetd udtelnetd [-dN] [-o dir]
Where telnets is the telnet service name you specified in /etc/services and UDTBIN_PATH is thepath to the UniData bin directory. Udtelnetd is the UniData secured telnet server and it takes thefollowing options.
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 recorded.The 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 settingis /tmp.
There are two new files introduced into the unishared directory on the server that you need to befamiliar with, udtelnetd and .udscrfile. They are located on the database server, under /unishared/unitelnet. You can determine the location of the unishared directory by typingcat /.unishared. The two files are listed below.
udtelnetd.conf - This is the UniData telnet server configuration file and has the following format:
security_context_record_id password
Where security_context_record_id and password are the security context record ID and password usedto get security context in a pre-generated security file (defined in .udscrfile). This security contextrecord id is system-wide, which is managed on a per-machine basis rather than a per-user basis.
.udscrfile - This is the security file containing the path to the security context file. For moreinformation on the Security Context File, refer to the Developing UniBasic Reference manual.
