Rocket UniData

Administering UniData on Windows and UNIX

Platforms
Version 8.2.1

July 2017
UDT-821-ADMIN-2
Notices
Edition
Publication date: July 2017
Book number: UDT-821-ADMIN-2
Product version: Version 8.2.1

Copyright
© Rocket Software, Inc. or its affiliates 1985-2017. All Rights Reserved.

Trademarks
Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go
to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document
may 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 of
individuals, companies, brands, and products. All of these names are fictitious and any similarity to
the 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 with
the terms of such license.

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

2
Corporate information
Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,
and compliance; database servers and tools; business information and analytics; and application
development, integration, and modernization.
Website: www.rocketsoftware.com
Rocket Global Headquarters
77 4th Avenue, Suite 100
Waltham, MA 02451-1468
USA
To contact Rocket Software by telephone for any reason, including obtaining pre-sales information
and technical support, use one of the following telephone numbers.

Country Toll-free telephone number

United States 1-855-577-4323
Australia 1-800-823-405
Belgium 0800-266-65
Canada 1-855-577-4323
China 400-120-9242
France 08-05-08-05-62
Germany 0800-180-0882
Italy 800-878-295
Japan 0800-170-5464
Netherlands 0-800-022-2961
New Zealand 0800-003210
South Africa 0-800-980-818
United Kingdom 0800-520-0439

Contacting Technical Support

The Rocket Community is the primary method of obtaining support. If you have current support and
maintenance agreements with Rocket Software, you can access the Rocket Community and report
a problem, download an update, or read answers to FAQs. To log in to the Rocket Community or to
request 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 telephone
numbers that are listed above or send an email to [email protected].

3
Contents
Notices................................................................................................................................................................................... 2
Corporate information......................................................................................................................................................... 3
Chapter 1: Introduction......................................................................................................................................................15
Audience.................................................................................................................................................................. 15
IPv6 support............................................................................................................................................................ 15
Excluded commands.............................................................................................................................................. 16
Reserved characters............................................................................................................................................... 16
Case sensitivity....................................................................................................................................................... 16
File names................................................................................................................................................... 17
Record names............................................................................................................................................. 17
Index files and index log files.................................................................................................................... 17
SAVEDLISTS file...........................................................................................................................................18
PHANTOM command.............................................................................................................................................. 18
Dynamic files...........................................................................................................................................................18
Deleting files............................................................................................................................................................18
PCPERFORM command.......................................................................................................................................... 19
Shell command differences................................................................................................................................... 19
Use of semicolon.................................................................................................................................................... 20
Terminal devices.....................................................................................................................................................20
Tape devices........................................................................................................................................................... 20
Printing in UniData................................................................................................................................................. 20
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX...................................................... 22
UniData migration tools.........................................................................................................................................22
NTMIGRATE file........................................................................................................................................... 22
NT_SCOUT................................................................................................................................................... 23
NT_CATALOG_MAP......................................................................................................................................24
TAR2FTP.......................................................................................................................................................25
convcode, convdata, convidx.................................................................................................................... 26
NT_UPDATE_PATHS....................................................................................................................................27
NT_RECATALOGGER....................................................................................................................................27
SQL_UNIX_2_NT..........................................................................................................................................27
Special considerations for UniData SQL............................................................................................................... 28
Migrating schema and dictionaries........................................................................................................... 28
Migrating privilege tables...........................................................................................................................28
Process overview.................................................................................................................................................... 30
Copying the NTMIGRATE file......................................................................................................................30
Running the migration tools......................................................................................................................31
Moving the programs to the Windows machine.......................................................................................34
Chapter 3: Managing the UDTelnet and UDSerial services..............................................................................................40
Introduction.............................................................................................................................................................40
Requirements for the services................................................................................................................... 40
UDTelnet service features.......................................................................................................................... 41
UDSerial service features........................................................................................................................... 42
Security............................................................................................................................................43
Terminal emulation........................................................................................................................ 43
Logging............................................................................................................................................ 43
Integration with UniData telnet service........................................................................................44
Managing Windows UDTelnet sessions (Windows only)...................................................................................... 44
Modifying the UDTelnet session parameters............................................................................................44
Starting, stopping, and pausing the UDTelnet server..............................................................................46

4
 Contents

Adding, updating, or deleting UDTelnet users......................................................................................... 46

Managing Windows UDSerial sessions (Windows only)....................................................................................... 48
Configuring SSL for Telnet..................................................................................................................................... 48
Chapter 4: UniData and background processes...............................................................................................................50
Daemons and services............................................................................................................................................50
Principal UniData daemons or services................................................................................................................ 50
Shared basic code server (sbcs)................................................................................................................ 50
Shared memory manager (smm).............................................................................................................. 51
Clean up (cleanupd)................................................................................................................................... 52
UniRPC (unirpcd)........................................................................................................................................ 52
sync daemon (UNIX only)...........................................................................................................................52
Monitoring UniData daemons or services.............................................................................................................52
The udt.errlog file....................................................................................................................................... 53
Chapter 5: UniData and memory.......................................................................................................................................55
Shared memory on Windows or UNIX platforms................................................................................................. 55
UniData and shared memory.................................................................................................................................55
smm and shared memory..........................................................................................................................56
Control table list (CTL)................................................................................................................... 56
Creating and assigning memory structures..................................................................................59
Displaying parameter settings.......................................................................................................60
Learning about global pages..................................................................................................................... 61
Learning about local control tables.......................................................................................................... 61
sbcs and shared memory...........................................................................................................................62
Self-created segments................................................................................................................................62
UniData and the UNIX kernel (UNIX only).................................................................................................63
Chapter 6: Configuring your UniData system................................................................................................................... 64
Configuration procedure........................................................................................................................................ 64
Identify disk requirements......................................................................................................................... 65
Identify memory requirements..................................................................................................................65
Verify version compatibilities.................................................................................................................... 66
Check/reset the UNIX kernel or Windows system-level parameters....................................................... 66
Check/reset UniData configuration parameters.......................................................................................67
Define peripherals within UniData............................................................................................................ 72
Create UniData accounts........................................................................................................................... 72
Add UNIX and Windows users....................................................................................................................72
Set environment variables......................................................................................................................... 73
Setting UDTHOME and UDTBIN..................................................................................................... 73
Setting PATH................................................................................................................................... 74
Setting additional environment variables.................................................................................... 74
Review UniData security............................................................................................................................ 74
Convert data files....................................................................................................................................... 75
Perform makeudt (UNIX only)................................................................................................................... 75
Review backup procedures........................................................................................................................75
Chapter 7: Starting, stopping, and pausing UniData....................................................................................................... 77
Normal operation................................................................................................................................................... 77
UniData log files..........................................................................................................................................77
Starting UniData with startud................................................................................................................... 79
Stopping UniData with stopud.................................................................................................................. 80
Pausing UniData..................................................................................................................................................... 80
The dbpause command............................................................................................................................. 80
The dbpause_status command................................................................................................................. 82
Resuming processing..................................................................................................................................82
Additional commands............................................................................................................................................ 83
Listing processes with showud (UNIX only)..............................................................................................83

5
 Contents

Stopping a user process with stopudt...................................................................................................... 84

Stopping a user process with deleteuser................................................................................................. 85
Displaying IPC facilities with ipcstat (Windows only).............................................................................. 86
Removing IPC structures with udipcrm (UNIX only)................................................................................ 87
Stopping UniData with stopud -f...............................................................................................................87
Chapter 8: Managing UniData accounts........................................................................................................................... 89
About UniData accounts........................................................................................................................................ 89
Creating a UniData account...................................................................................................................................89
Saving and restoring accounts (UNIX only).......................................................................................................... 92
Deleting an account............................................................................................................................................... 93
Clearing space in UniData accounts..................................................................................................................... 93
CLEAR.ACCOUNT......................................................................................................................................... 93
Chapter 9: Managing UniData security............................................................................................................................. 95
Customizing a VOC file........................................................................................................................................... 95
Customizing UniData..............................................................................................................................................96
Customizing permissions on UNIX........................................................................................................................ 97
Customizing permissions on Windows................................................................................................................. 99
Remote items........................................................................................................................................................ 100
The SETFILE command........................................................................................................................................ 101
LOGIN and LOGOUT paragraphs......................................................................................................................... 101
Creating a login paragraph for UniData ODBC connections..................................................................104
Creating a login paragraph for UniObjects connections....................................................................... 104
UniData SQL privileges.........................................................................................................................................105
Field-level security for UniQuery......................................................................................................................... 106
Points to remember about field-level security.......................................................................................106
The QUERY.PRIVILEGE file........................................................................................................................106
UniQuery processing.................................................................................................................... 108
Turning on field-level security................................................................................................................. 109
UniData and UNIX security...................................................................................................................................110
UNIX file permissions................................................................................................................................110
Additional UNIX access modes................................................................................................................ 111
UNIX umask............................................................................................................................................... 112
UniData for UNIX default permissions.................................................................................................... 113
UniData for UNIX processes and root..................................................................................................... 114
Logins and groups on UNIX..................................................................................................................... 114
Adding a UNIX user.......................................................................................................................114
Use separate logon IDs................................................................................................................ 114
User groups................................................................................................................................... 115
Home directories.......................................................................................................................... 115
Startup scripts...............................................................................................................................116
Chapter 10: Managing UniData files................................................................................................................................117
UniData hashed files............................................................................................................................................ 117
Static hashed files................................................................................................................................................ 117
Dynamic hashed files........................................................................................................................................... 118
Dynamic files and overflow......................................................................................................................118
Splitting and merging...................................................................................................................119
WHOLEFILE type (Windows only)................................................................................................ 119
KEYONLY type............................................................................................................................... 120
KEYDATA type................................................................................................................................120
Selecting a split/merge type........................................................................................................120
Dynamic files and hash type........................................................................................................120
Dynamic files, part files, and part tables (UNIX only)............................................................................ 120
Location of part tables (UNIX only).............................................................................................121
Components of a part table (UNIX only).....................................................................................121
Part table tips and constraints (UNIX only)................................................................................ 122

6
 Contents

When dynamic files are created.............................................................................................................. 122

Estimating the size of the file...................................................................................................... 122
Locating the dynamic file directory............................................................................................ 122
Locating the part files (UNIX only).............................................................................................. 123
Tips and constraints for creating a dynamic file....................................................................................124
Choosing the initial modulo........................................................................................................ 124
Choosing the block size............................................................................................................... 125
When dynamic files expand (UNIX only)................................................................................................. 125
Determining whether a new part file Is needed (UNIX only)..................................................... 125
Locating space for a new part file (UNIX only)........................................................................... 126
How part files are stored (UNIX only)..................................................................................................... 126
Management tools for dynamic files (UNIX only)...................................................................................127
auditor........................................................................................................................................... 128
fixtbl............................................................................................................................................... 128
mvpart........................................................................................................................................... 128
Dynamic files and disk space.................................................................................................................. 128
Sequentially hashed files......................................................................................................................... 135
The dat001 file.............................................................................................................................. 136
The over001 file............................................................................................................................ 136
The gmekey file.............................................................................................................................136
DIR-type files (Windows only)..................................................................................................................137
Multilevel files (MULTIFILES) (Windows only)............................................................................. 138
Multilevel directory files (Windows only).................................................................................... 139
Index files and index log files (Windows only)........................................................................................140
Index-related files for a static hashed file (Windows only)........................................................ 140
Index-related files for a dynamic hashed file (Windows only)...................................................141
File-handling commands......................................................................................................................................142
File corruption.......................................................................................................................................................144
Preventing file corruption........................................................................................................................ 144
UniData detection tools....................................................................................................................................... 145
guide.......................................................................................................................................................... 145
Using guide....................................................................................................................................148
guide_ndx.................................................................................................................................................. 149
UniData recovery tools.........................................................................................................................................151
dumpgroup................................................................................................................................................152
fixgroup......................................................................................................................................................153
fixfile...........................................................................................................................................................154
How fixfile works with static files................................................................................................155
How fixfile works with dynamic files...........................................................................................156
Detection and repair examples........................................................................................................................... 157
Error messages......................................................................................................................................................160
File access messages................................................................................................................................161
Block usage messages..............................................................................................................................161
Group header messages...........................................................................................................................161
Header key messages...............................................................................................................................161
Other header messages........................................................................................................................... 162
Free block messages................................................................................................................................ 162
Long record messages..............................................................................................................................163
Dynamic file messages............................................................................................................................. 163
Chapter 11: Managing UniData locks.............................................................................................................................. 164
The global lock manager..................................................................................................................................... 164
Locking in UniBasic.............................................................................................................................................. 165
Locking commands...................................................................................................................................165
Resource locks...................................................................................................................................................... 166
Listing locks...........................................................................................................................................................167
LIST.READU................................................................................................................................................167

7
 Contents

LIST.LOCKS................................................................................................................................................ 168
LIST.QUEUE............................................................................................................................................... 169
Clearing locks........................................................................................................................................................172
SUPERCLEAR.LOCKS command...............................................................................................................172
SUPERRELEASE command....................................................................................................................... 173
Clearing locks............................................................................................................................................174
Chapter 12: Managing UniData users..............................................................................................................................176
Adding Windows users......................................................................................................................................... 176
User groups............................................................................................................................................... 176
Home directories...................................................................................................................................... 177
UDTADMIN_GROUP registry key.............................................................................................................. 177
UDTADMIN_GROUP registry key overview.................................................................................. 177
Creating the UDTADMIN_GROUP registry key............................................................................ 178
Logon scripts.............................................................................................................................................178
Adding UNIX users................................................................................................................................................ 179
Create logon IDs at the UNIX level.......................................................................................................... 179
Assign users to groups............................................................................................................................. 180
Monitoring user processes................................................................................................................................... 180
Stopping user processes...................................................................................................................................... 181
Using TIMEOUT......................................................................................................................................... 182
Chapter 13: Managing printers in UniData..................................................................................................................... 183
Managing printers on Windows........................................................................................................................... 183
Configuring and troubleshooting a Printer.............................................................................................183
Physical configuration..................................................................................................................183
Troubleshooting............................................................................................................................184
Definition in Windows platforms................................................................................................. 184
Network print device....................................................................................................................184
Local printer..................................................................................................................................184
Definition in UniData....................................................................................................................184
Default printers............................................................................................................................. 185
Spooling from UniData.............................................................................................................................185
UniData for Windows platforms specifics...................................................................................185
Creating a local printer................................................................................................................ 186
Creating a form.............................................................................................................................187
Defining a printer unit in UniData........................................................................................................... 188
Examples....................................................................................................................................... 190
Printing to the _HOLD_ file..........................................................................................................193
Selecting a spooler mode............................................................................................................ 194
RAW Mode..................................................................................................................................... 194
WINDOW Mode.............................................................................................................................. 194
Redefining the default UniData print unit.................................................................................. 196
Submitting concurrent print jobs................................................................................................196
UniData printing commands....................................................................................................................196
Managing printers on UNIX.................................................................................................................................. 197
UniData and UNIX spoolers..................................................................................................................... 198
Configuring the spooler................................................................................................................198
Enabling and disabling printers.................................................................................................. 200
SETOSPRINTER Command...........................................................................................................201
Spooling from UniData.................................................................................................................201
UniData printing commands....................................................................................................................201
Configuring and troubleshooting a printer.............................................................................................202
Physical connection......................................................................................................................202
Troubleshooting............................................................................................................................203
Spooler definition......................................................................................................................... 203
Definition in UniData....................................................................................................................203

8
 Contents

SETPTR...................................................................................................................................................... 203
Environment variables............................................................................................................................. 205
Disabling printer validation......................................................................................................... 205
Defining an alternate search path...............................................................................................206
Examples................................................................................................................................................... 206
Redefining the default UniData print unit.................................................................................. 206
Submitting concurrent print jobs................................................................................................206
Printing to a UNIX device.............................................................................................................207
Passing spooler options to UNIX................................................................................................. 207
Decoding a UniData print statement...................................................................................................... 208
1. Determine your default spooler command............................................................................ 208
2. Create the C program...............................................................................................................208
3. Compile the C program............................................................................................................209
4. Redefine your path...................................................................................................................209
5. Test UniData printing............................................................................................................... 209
6. Reset your execution path.......................................................................................................210
Chapter 14: Managing cataloged programs................................................................................................................... 211
UniBasic source and compiled programs........................................................................................................... 211
UniBasic compiled programs...................................................................................................................211
Cataloging UniBasic programs............................................................................................................................ 211
Direct cataloging.......................................................................................................................................212
Local cataloging........................................................................................................................................212
Global cataloging......................................................................................................................................212
Managing global catalogs.................................................................................................................................... 214
Contents of a global catalog................................................................................................................... 214
Verifying a program version.....................................................................................................................215
Activating newly cataloged programs and subroutines........................................................................ 216
Main programs.............................................................................................................................. 216
Subroutines................................................................................................................................... 217
NEWVERSION keyword................................................................................................................. 217
newversion system-level command............................................................................................217
NEWPCODE command..................................................................................................................219
Listing programs in use........................................................................................................................................219
Creating an alternate global catalog space........................................................................................................220
Files and directories created by newhome.............................................................................................220
Creating an alternate global catalog space............................................................................................222
Using an alternate global catalog space................................................................................................ 224
Chapter 15: Account-based licensing..............................................................................................................................226
Managing the license configuration.................................................................................................................... 226
Managing account-based licensing with listuser -a............................................................................... 227
Verifying the acct_licn.def file..................................................................................................... 227
Listing the acct_licn.def file.........................................................................................................227
Reloading the acct_licn.def file................................................................................................... 228
Chapter 16: Managing and using tape devices (Windows only).................................................................................... 229
UniData tape handling commands..................................................................................................................... 229
SETTAPE.................................................................................................................................................... 230
Steps for tape device use.....................................................................................................................................231
1. Define tape units.................................................................................................................................. 231
2. Attach a Tape Device............................................................................................................................231
3. Read from, or write to, the tape device..............................................................................................232
4. Release the tape device....................................................................................................................... 233
Chapter 17: CallC and CallBasic (Windows only)........................................................................................................... 234
Dynamic Link Libraries (DLLs) and UniData....................................................................................................... 234
Calling external routines from UniData.............................................................................................................. 234

9
 Contents

Requirements for CALLC.......................................................................................................................... 234

Steps for CALLC........................................................................................................................................ 235
CALLC and UDT.OPTIONS 88................................................................................................................... 235
CALLC syntax and data types.................................................................................................................. 236
E type VOC entries.................................................................................................................................... 236
Examples................................................................................................................................................... 237
CALLC example programs.................................................................................................................................... 238
C example..................................................................................................................................................238
C++ example..............................................................................................................................................241
Pascal style example................................................................................................................................ 244
Accessing UniData from an external program....................................................................................................246
Requirements............................................................................................................................................ 246
How CallBasic works................................................................................................................................ 246
Examples................................................................................................................................................... 247
CallBasic example 1......................................................................................................................247
CallBasic example 2......................................................................................................................247
Sample programs................................................................................................................................................. 247
C program example.................................................................................................................................. 247
Calling a UniBasic subroutine: U_callbas................................................................................... 250
Freeing memory............................................................................................................................250
Calling a UniBasic subroutine: udtcallbasic............................................................................... 250
Freeing memory............................................................................................................................251
Ending CallBasic........................................................................................................................... 251
UniBasic subroutine example.................................................................................................................. 251
Steps for CallBasic................................................................................................................................................ 252
1. Code and compile the application program...................................................................................... 252
2. Code, compile, and catalog the UniBasic subroutine........................................................................253
3. Use the new executable.......................................................................................................................253
Chapter 18: Monitoring and tuning UniData (Windows only)........................................................................................255
Monitoring your Windows system....................................................................................................................... 255
UniData performance factors.............................................................................................................................. 255
Database design considerations..............................................................................................................255
Using alternate key indexes.....................................................................................................................255
Sizing static hashed files..........................................................................................................................256
Sizing dynamic hashed files.....................................................................................................................256
UniBasic coding tips................................................................................................................................. 256
Use modular programming..........................................................................................................256
Use efficient commands...............................................................................................................256
Use dynamic arrays and matrices appropriately....................................................................... 257
Use the correct READ in each situation...................................................................................... 257
Manage locks carefully.................................................................................................................257
UniBasic profiling..................................................................................................................................................257
1. Compile the programs with -G............................................................................................................ 257
2. Run the programs with -G................................................................................................................... 258
3. Review the profile output.................................................................................................................... 258
UniData performance monitoring....................................................................................................................... 260
UniData user statistics............................................................................................................................. 261
UniData file I/O statistics......................................................................................................................... 262
UniData dynamic file statistics................................................................................................................ 264
UniData index statistics........................................................................................................................... 265
UniData program control statistics......................................................................................................... 266
UniData dynamic array statistics............................................................................................................ 268
UniData lock statistics..............................................................................................................................269
UniData sequential I/O statistics.............................................................................................................271
UniData data conversion statistics..........................................................................................................273
ECL process monitoring commands................................................................................................................... 274

10
 Contents

Examples............................................................................................................................................................... 275
Chapter 19: Accessing UNIX devices (UNIX only)............................................................................................................277
UniData tape handling commands..................................................................................................................... 277
SETTAPE.................................................................................................................................................................278
Steps for tape device use.....................................................................................................................................278
1. Define tape units.................................................................................................................................. 278
2. Attach a tape device.............................................................................................................................278
3. Read from or write to the tape device................................................................................................279
4. Release the tape device....................................................................................................................... 280
UniData LINE commands..................................................................................................................................... 280
Communicating with GET and SEND.................................................................................................................. 281
1. Define a tty device in UniData.............................................................................................................281
2. Attach the line to your process........................................................................................................... 282
3. Access the line...................................................................................................................................... 282
4. Release the line.................................................................................................................................... 282
Dual-terminal debugging in UniBasic................................................................................................................. 282
Setting up dual-terminal debugging................................................................................................................... 283
1. Log on to two terminals (or Windows)............................................................................................... 283
2. Set a pointer to the display terminal..................................................................................................283
3. Connect to the display terminal..........................................................................................................283
4. Conduct the debugging session.......................................................................................................... 283
5. Detach from the display terminal....................................................................................................... 284
6. Release the display terminal............................................................................................................... 284
Chapter 20: Managing memory (UNIX only)................................................................................................................... 285
UniData monitoring/configuring tools................................................................................................................ 285
udtconf main display................................................................................................................................285
Calculating udtconfig parameters...........................................................................................................286
Checking configuration parameters........................................................................................................286
Saving configuration parameters............................................................................................................ 287
Recalculating the size of the CTL............................................................................................................ 287
Viewing current and suggested settings................................................................................................. 287
Exiting udtconf..........................................................................................................................................287
Setting shared memory parameters................................................................................................................... 288
shmconf: main display............................................................................................................................. 288
shmconf: viewing current and suggested settings.................................................................................289
shmconf: Recalculating the size of CTL.................................................................................................. 289
shmconf: Recalculating other parameters............................................................................................. 289
Shared memory and the Recoverable File System................................................................................ 290
Analyzing UniData configuration parameters........................................................................................ 290
Checking and changing UniData configuration parameters................................................................. 291
Checking kernel parameters....................................................................................................................292
sms............................................................................................................................................................. 292
Learning about global pages................................................................................................................... 294
Learning about local control tables........................................................................................................ 295
UNIX monitoring tools..........................................................................................................................................296
UniData configuration parameters......................................................................................................................296
UNIX kernel parameters........................................................................................................................... 297
UniData error messages for smm........................................................................................................................297
Chapter 21: Managing ipc facilities (UNIX only)............................................................................................................. 300
Message queues, shared memory, and semaphores......................................................................................... 300
UniData log files........................................................................................................................................304
Removing ipc structures...................................................................................................................................... 304
1. Check for remaining facilities.............................................................................................................. 304
2. Stop UniData.........................................................................................................................................304
3. Decide how to proceed........................................................................................................................ 305

11
 Contents

4. Remove ipc facilities with udipcrm.....................................................................................................305

5. Remove ipc facilities with UNIX ipcrm................................................................................................ 305
6. Restart UniData.................................................................................................................................... 306
Chapter 22: Performance monitoring and tuning (UNIX only)...................................................................................... 307
UNIX performance considerations...................................................................................................................... 307
UNIX performance monitoring.............................................................................................................................307
Tools.......................................................................................................................................................... 307
Tips.............................................................................................................................................................308
uptime............................................................................................................................................308
ps, vmstat......................................................................................................................................308
iostat.............................................................................................................................................. 308
UniData performance factors.............................................................................................................................. 308
Database design considerations..............................................................................................................308
Using alternate key indexes.....................................................................................................................309
Sizing static hashed files..........................................................................................................................309
Sizing dynamic hashed files.....................................................................................................................309
UniBasic coding tips................................................................................................................................. 309
Use modular programming..........................................................................................................310
Use efficient commands...............................................................................................................310
Use dynamic and dimensioned arrays appropriately................................................................ 310
Use the correct READ in each situation...................................................................................... 310
Manage locks carefully.................................................................................................................311
UniBasic profiling..................................................................................................................................................311
1. Compile the programs with -G............................................................................................................ 311
2. Run the programs with -G................................................................................................................... 311
3. Review the profile output.................................................................................................................... 311
UniData performance monitoring: udtmon........................................................................................................313
udtmon: UniData user statistics.............................................................................................................. 316
udtmon: file I/O statistics.........................................................................................................................317
udtmon: program control statistics........................................................................................................ 318
udtmon: dynamic array statistics............................................................................................................319
udtmon: lock statistics.............................................................................................................................320
udtmon: sequential I/O statistics............................................................................................................ 321
udtmon: data conversion statistics.........................................................................................................321
udtmon: index statistics...........................................................................................................................322
udtmon: Mglm performance....................................................................................................................324
Chapter 23: UniData and the UNIX file system (UNIX only)........................................................................................... 326
UniData directories and files............................................................................................................................... 326
Files, pointers, and links...................................................................................................................................... 327
Creating files............................................................................................................................................. 327
Setting a UniData pointer........................................................................................................................ 327
Setting an Environment Variable............................................................................................................ 328
Setting a UNIX link....................................................................................................................................329
UniData hashed files............................................................................................................................................ 330
Static files..................................................................................................................................................330
Points to remember about static files........................................................................................ 331
Dynamic files.............................................................................................................................................331
The dat001 file.............................................................................................................................. 331
The over001 file............................................................................................................................ 332
Points to remember about dynamic files................................................................................... 332
Sequentially hashed files......................................................................................................................... 332
The dat001 file.............................................................................................................................. 332
The over001 file............................................................................................................................ 332
The gmekey file.............................................................................................................................333
DIR-type files............................................................................................................................................. 334

12
 Contents

Multilevel files........................................................................................................................................... 334

Points to remember about multilevel files................................................................................. 335
Multilevel directory files........................................................................................................................... 335
Points to remember about multilevel directory files................................................................. 336
Index files and index log files.................................................................................................................. 336
Index-related files for a static hashed file.................................................................................. 336
Index-related files for a dynamic hashed or sequentially hashed file.......................................337
UniData and tmp space....................................................................................................................................... 337
Changing TMP in the udtconfig file.........................................................................................................338
Setting an environment variable.............................................................................................................338
Chapter 24: UniData and UNIX ipc facilities (UNIX only)............................................................................................... 339
Message queues.................................................................................................................................................... 339
UniData and message queues................................................................................................................. 339
Semaphores...........................................................................................................................................................340
Chapter 25: UniData and UNIX devices (UNIX only)....................................................................................................... 342
UNIX devices: overview........................................................................................................................................ 342
UniData and terminal devices............................................................................................................................. 342
UniData and tape devices....................................................................................................................................342
UniData and printers............................................................................................................................................ 343
UniData and serial devices.................................................................................................................................. 343
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)..................................................................................344
Dynamic linking in UniData................................................................................................................................. 344
Runtime linking.........................................................................................................................................345
The /.udlibs## definition.......................................................................................................................... 346
Dynamic library search method and tools............................................................................................. 346
Accessing C from UniBasic (CALLC).....................................................................................................................348
CALLC prerequisites..................................................................................................................................349
CALLC requirements................................................................................................................................. 349
Linking C functions into the UniData CALLC library...............................................................................350
Write the C program.....................................................................................................................351
Compile the C program................................................................................................................352
Add the C function to UniData.................................................................................................... 352
Create and modify the makefile..................................................................................................354
Make the u2callc library...............................................................................................................355
Write, compile, and test the UniBasic program......................................................................... 355
Deploy the updated library..........................................................................................................356
File examples............................................................................................................................................ 357
Passing bstring-type data example.........................................................................................................358
Reinitializing $UDTHOME/work files....................................................................................................... 361
Troubleshooting CALLC............................................................................................................................361
Using the debug executables (udt.d)...................................................................................................... 363
Accessing UniData from a C program (CallBasic)...............................................................................................364
Requirements............................................................................................................................................ 364
How CallBasic works................................................................................................................................ 365
C program example.................................................................................................................................. 365
Header files................................................................................................................................... 366
Error handler.................................................................................................................................366
Initialize CallBasic.........................................................................................................................366
Call a UniBasic subroutine...........................................................................................................367
Freeing resources..........................................................................................................................367
Ending CallBasic........................................................................................................................... 367
UniBasic subroutine example.................................................................................................................. 367
Steps for CallBasic....................................................................................................................................368
Code and compile the C program............................................................................................... 368
Code, compile, and catalog the UniBasic subroutine................................................................369

13
 Contents

Make a copy of the makefile template....................................................................................... 372

Edit the makefile...........................................................................................................................372
Build the new executable............................................................................................................ 373
Produce a stripped executable....................................................................................................374
Chapter 27: General troubleshooting (UNIX only)..........................................................................................................375
Crashes and restart problems............................................................................................................................. 375
UniData crashes........................................................................................................................................ 375
UniData cannot start................................................................................................................................ 375
Response problems in UniData........................................................................................................................... 376
UniData consistently slow........................................................................................................................376
UniData is hung........................................................................................................................................ 376
Error messages......................................................................................................................................................376
Common error messages......................................................................................................................... 377
Syntax error...................................................................................................................................377
Not a verb command................................................................................................................... 378
cannot open abcdef..................................................................................................................... 378
[100004]......................................................................................................................................... 378
[100000]......................................................................................................................................... 378
Virtual field too big.......................................................................................................................379
Record is too long. Ask UniData to extend the U_MAXEXTRA....................................................379
Numra is maxed out in installshmid........................................................................................... 379
Appendix A: Configuring SSL for Telnet (UNIX only)...................................................................................................... 380
Server side configuration..................................................................................................................................... 380
Appendix B: UniData configuration parameters............................................................................................................ 381
Appendix C: Environment variables for UniData............................................................................................................396
Appendix D: Daemon processes...................................................................................................................................... 399
Shared memory manager.................................................................................................................................... 399
System clock......................................................................................................................................................... 399
Replication manager daemon (repmanager)..................................................................................................... 399
The cleanupd daemon......................................................................................................................................... 399
The cleanupd.config file...........................................................................................................................400
cleanupd command..................................................................................................................................400
Starting UniData daemons...................................................................................................................................401
Stopping UniData daemons.................................................................................................................................401
Displaying UniData daemons...............................................................................................................................401
Global control table..................................................................................................................................402
Local control tables..................................................................................................................................402
Terminology.............................................................................................................................................. 402

14
Chapter 1: Introduction
The purpose of this manual is to collect in a single book as much information as possible about
activities that are needed to administer a Rocket UniData installation on UNIX and Windows.
This manual repeats some information that is presented elsewhere in the UniData documentation
set. Certain command descriptions and examples have been amplified or modified in this manual to
increase their usefulness to system administrators as opposed to end users.

Note: Before you try repeating the examples in this manual, make sure that you have set the
environment variables UDTHOME and UDTBIN, and make sure that your PATH includes udtbin.
See Configuring your UniData system, on page 64 for information about setting these variables.

Many of the administrative functions you can run from the command line are available through the U2
Extensible Administration Tool (XAdmin).

Audience
This manual is intended for people whose responsibilities include the following:
▪ Tasks that are performed at the host level (UNIX) or operating system level (Windows)
▫ 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

Note: The examples in this manual use UNIX-like path separators (/) instead of Windows-like path
separators (\) unless the content is only relevant to Windows. Keep this in mind when viewing the
tables, code examples, and directory locations.

IPv6 support
Starting at UniData 8.1.0, IPv6 support is included. IPv6 is an industry standard for the IP network. IPv6
removed 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.

15
Chapter 1: Introduction

Excluded commands
The following commands are not supported on UniData for Windows platforms:
▪ acctrestore
▪ ACCT.SAVE
▪ kp
▪ nusers
▪ shmconf
▪ showud
▪ smmtest
▪ systest
▪ udstat
▪ udtinstall

Reserved characters
UniData for Windows platforms does not allow the use of the following characters in a file or directory
name:
▪ “ (double quotation mark)
▪ | (pipe sign)
▪ * (asterisk)
▪ / (slash)
▪ : (colon)
▪ < (less than sign)
▪ > (greater than sign)
▪ ? (question mark)
▪ \ (backslash)
You can use the reserved characters in a file specification. For instance, C:\U2\ud82\DEMO
\INVENTORY is an acceptable file specification. The reserved characters : and \ are used as delimiters
in the file specification. However, they cannot be used within the name of a file or directory. DEM:O or
INVEN\TORY are unacceptable.

Note: If your application uses any of these characters in file or directory names, you need to
substitute other characters. See Migrating applications to UniData for Windows from UniData for
UNIX, on page 22 for information about tools that locate these special characters within your
accounts.

Case sensitivity
Windows platforms do not distinguish between uppercase and lowercase, except in a user’s password,
which is case sensitive. UniData is case sensitive. This difference creates a number of impacts.

16
 File names

See Migrating applications to UniData for Windows from UniData for UNIX, on page 22 for
information about tools to report all instances in your file and record names where case insensitivity
could cause problems.

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

Record names
On Windows platforms, you cannot have two records in the same DIR or MULTIDIR file whose names
are identical except for case.
The following screen illustrates one effect of this limitation.
:CREATE.FILE DIR TEST_DIR
Create DIR type file TEST_DIR.
Create file D_TEST_DIR, modulo/1,blocksize/1024
Hash type = 0
Added "@ID", the default record for UniData to DICT TEST_DIR.
:SELECT VOC WITH F1=PA

7 records selected to list 0.

>COPY FROM VOC TO TEST_DIR

get id's from select list:LISTPEQS(y/n)?Y
LISTDICT exists in TEST_DIR, cannot overwrite
6 records copied
:
UniData could not copy the LISTDICT record because a record called listdict already was copied.
Since each record in a DIR (or MULTIDIR) file is an NTFS file, Windows platforms treat listdict and
LISTDICT as the same file. You need to consider this limitation if your application:
▪ Creates records with names differing only in case in a DIR file or multilevel subdirectory.
▪ Copies records from a hashed file, where the limitation does not exist, into a DIR file or multilevel
subdirectory.

Index files and index log files

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

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

17
Chapter 1: Introduction

SAVEDLISTS file
By default, a UniData account on UNIX contains a SAVEDLISTS file for saving SELECT lists, and a
savedlists file for storing temporary information for BY.EXP sorts.
At the operating system level, the file named savedlists on UniData for UNIX is called
the SAVEDLISTSL file on UniData for Windows. However, the VOC file contains an entry for
savedlists pointing to the correct file, so you should not have to modify your application. You
must change the name of the savedlists file in any UniData account you are moving from UNIX to
Windows.
Prior to UniData 8.1.0, when creating a SAVEDLIST, UniData used an internal hard-coded break point
to control the size of files created in the SAVEDLIST directory. This could result in many SAVEDLIST
files being generated appending a sequential number format 000,001,002, and so on to the list name.
Now, the SAVEDLIST will be a single file with 000 appended to the list name. This behavior is
controlled via the udtconfig tuneable SINGLE_SAVEDLISTcommand. The default is 1. To return
to the previous method, the tuneable can be set to 0.

PHANTOM command
On UniData for Windows platforms, the PHANTOM command behaves differently, depending from
where you execute it.
▪ If you execute PHANTOM from a UniData session at the console, then end the UniData session, the
phantom job completes.
▪ If you execute PHANTOM from a telnet session, the phantom job continues until it completes. This
behavior matches the behavior of PHANTOM on UniData for UNIX.

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

Deleting files
Windows does not allow a process to delete a file if any other process has that file open. This operating
system limitation significantly affects the behavior of the ECL DELETE.FILE command. To minimize
the impact of this restriction, DELETE.FILE only removes the DICT portion and VOC entry for a file if
it has successfully removed the DATA portion of the file. However, the operating system restriction still
results in the following behaviors in UniData:
▪ If one process executes DELETE.FILE filename, and another process has the DATA portion of
filename open, or both the DICT and the DATA portions of filename open, the DELETE.FILE fails
with an error, and no component of the file is deleted.
▪ If one process executes DELETE.FILE filename, and another process has only the DICT
portion of filename open, the DELETE.FILE removes only the data portion of the file, leaving the
VOC entry and the DICT portion intact and displaying an error.

18
 PCPERFORM command

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

PCPERFORM command
The UniBasic PCPERFORM command allows users to execute an operating system command from
within a UniBasic program. In UniData for Windows platforms, only MS-DOS commands can be
executed with PCPERFORM. In some cases (for instance, the echo command) there are MS-DOS
commands named like the UNIX versions (although their behavior can differ somewhat). In other cases
(for instance, who, ls, ps) you must identify replacements. Refer to your Windows platform and UNIX
documentation for information about system-level commands.
UniData supplies a suite of tools to automate some application analysis tasks. You can use the
NT_SCOUT tool to report all instances of the PCPERFORM command in your UniBasic programs,
PROCS, and paragraphs. See Migrating applications to UniData for Windows from UniData for UNIX, on
page 22 for information about NT_SCOUT.

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

Shell command differences

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

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

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

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

19
Chapter 1: Introduction

Use of semicolon
In UNIX, the semicolon is recognized as a command separator, so users can enter multiple commands
on a single command line. This functionality is lacking in MS-DOS. This particular operating system
difference can cause unexpected results.
On UNIX, the command line entry would echo the string abc to the file named file, then attempt to
execute the dir command.

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

Tape devices
When you use UniData tape commands (for instance, SETTAPE), you must use the Universal Naming
Convention (UNC) format for device identifiers. UNC names are in the form \\server\device.
The following example shows the SETTAPE, T.ATT, and T.STATUS commands on UniData for
Windows:
:SETTAPE 0
unit # = 0.
non rewind device:\\.\tape0
rewind device :r\\.\tape0
block size =4096
:T.ATT 0
tape unit 0 blocksize = 4096.
:T.STATUS

UNIT STATUS UDTNO USER CHANNEL

ASSIGNED
Number NAME NAME
BLOCKSIZE
0 ASSIGNED 65 terric \\.\tape0
4096
:
The device identifier \\.\TAPE0 indicates the current server (.), device TAPE0.
You can identify a disk file as a tape device by entering a path and file name (not in UNC format) on
the SETTAPE command line. If you do not use UNC format, UniData checks for a path and file that
matches your entry. If the file exists, UniData writes to the file as a “tape device”. Otherwise, SETTAPE
fails with an error message. UniData stores tape definition information in a file called udthome\sys
\tapeinfo. This is a text file, which you can view with any text editor.
You must log in as a member of the Administrators group to define a tape device with the SETTAPE
command.

Printing in UniData
Windows platforms allow users to print to printers (which are simply drivers that control print
devices). A printer can control a network print device or a local print device. Microsoft applications,

20
 Printing in UniData

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

21
Chapter 2: Migrating applications to UniData for
Windows from UniData for UNIX
This chapter describes the process for moving a UniData application from a UNIX platform, where the
application is installed and running, to a Windows platform. The chapter describes how to use the
migration tools provided with UniData for Windows platforms.

Tip: We strongly recommend you read this entire chapter before you begin migrating your
application.

UniData migration tools

UniData provides migration tools to help migrate your application.
• NTMIGRATE file
When you install UniData on your Windows system, the installation creates a directory in your
UniData folder called NTMIGRATE, which contains a group of tools to assist you with application
migration tasks.
• NT_SCOUT
The NT_SCOUT program evaluates a UniData UNIX account and identifies areas that need
attention before you move the account to a Windows platform.
• NT_CATALOG_MAP
NT_CATALOG_MAP is a UniBasic program that helps you recompile and recatalog your UniBasic
application after you have moved an account to the Windows platform.
• TAR2FTP
TAR2FTP is a UniBasic program that analyzes a UniData account and produces an output file you
can use as an FTP script.
• convcode, convdata, convidx
UniData includes three system-level commands for converting machine format between high-byte
and low-byte platforms.
• NT_UPDATE_PATHS
NT_UPDATE_PATHS is a UniBasic program that searches the VOC file in a UniData account after it
has been moved from UNIX to the Windows platform.
• NT_RECATALOGGER
NT_RECATALOGGER is a paragraph that UniData creates when you execute NT_CATALOG_MAP in
a UniData account on UNIX.
• SQL_UNIX_2_NT
SQL_UNIX_2_NT is a UniBasic program that creates a Windows-style privilege table from a UNIX
style privilege table.

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

22
 NT_SCOUT

Tool Description
NT_SCOUT UniBasic preprocessor. Run this program in each UniData account on
UNIX to identify migration issues.
ALT.ECL.CMDS List of ECL commands that are known to be excluded on UniData for
Windows Platforms or behave differently on UniData for Windows
Platforms. NT_SCOUT uses this file to analyze your application.
ALT.BP.CMDS List of UniBasic commands known to perform differently on UniData
for Windows Platforms. NT_SCOUT uses this file to analyze your
application.
RESERVED.CHARS List of Windows platforms reserved characters. NT_SCOUT uses this
file to analyze your application.
TAR2FTP UniBasic program that produces a directory listing in valid FTP
syntax. Run this program in each UniData account on UNIX, then
transfer the output to your Windows machine to FTP the contents of
the UniData account.
NT_CATALOG_MAP UniBasic program that builds a paragraph to catalog programs on
your Windows machine. Run this program in each UniData account
on UNIX. Execute the paragraph to catalog your programs after
moving to the Windows platform.
NT_UPDATE_PATHS UniBasic program that allows you to make global substitutions
for paths or subpaths in VOC entries. Execute this program in each
UniData account after moving to the Windows platform.
BUILD.FULL.PATH UniBasic subroutine used by NT_UPDATE_PATHS to generate
Windows-style path specifications.
SQL_UNIX_2_NT UniBasic program that converts a privilege table from UNIX style to
the Windows platform style.

Parent topic: UniData migration tools

NT_SCOUT
The NT_SCOUT program evaluates a UniData UNIX account and identifies areas that need attention
before you move the account to a Windows platform.
NT_SCOUT detects and reports:
▪ Case-sensitive file names.
▪ Case-sensitive record names in DIR type files.
▪ Reserved characters in file names (including record names in DIR type files). NT_SCOUT uses the
list of reserved characters in the RESERVED.CHARS record.
▪ UniBasic commands that can behave differently on the Windows platform. NT_SCOUT uses the list
of UniBasic commands in the ALT.BP.CMDS record.
▪ ECL commands that are excluded or may behave differently on Windows. NT_SCOUT uses the list
of ECL commands in the ALT.ECL.CMDS record.
▪ VOC entries without corresponding files.
NT_SCOUT runs with a GLOBAL or a LOCAL option.

Options
The following table describes the options.

23
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

Parameter Description
LOCAL Processes only files that physically reside in the current account
directory. This is the default if no option is specified.
GLOBAL Processes all files with entries in the VOC file of the account,
regardless of physical location.

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

Parameter Description
UNIX_NT_CATASTROPHIC List of findings that you should address before moving this account to
the Windows platform. If you do not address these findings, they can
cause data loss.
UNIX_NT_WARNING List of findings that you should review before running this application
on the Windows platform. These findings may cause run-time errors
or unexpected results from your application programs.
UNIX_NT_SUMMARY List of all findings from NT_SCOUT.

NTMIGRATE.LOC
NT_SCOUT also checks for a local NTMIGRATE file, called NTMIGRATE.LOC, in the current account.
If there is no NTMIGRATE.LOC, NT_SCOUT creates this DIR file. The local NTMIGRATE file has two
uses:
▪ Stores the output from TAR2FTP (which you can execute from NT_SCOUT if you want).
▪ Stores a UNIX text file called exclude.files, which lists program files in the current account
that you do not want to preprocess. If you want to exclude program files, you must create both
NTMIGRATE.LOC and exclude.files before you execute NT_SCOUT.

Parent topic: UniData migration tools

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

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

24
 TAR2FTP

Parent topic: UniData migration tools

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

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

25
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

The output file contains:

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

Parent topic: UniData migration tools

convcode, convdata, convidx

UniData includes three system-level commands for converting machine format between high-byte and
low-byte platforms.
▪ convcode converts UniBasic compiled programs.
▪ convdata converts UniData hashed files.
▪ convidx converts index files.
Run these commands in your UniData accounts after you move them if:
▪ You migrated the application from a high-byte UNIX system to a Windows platform, and
▪ You did not use TAR2FTP.

26
 NT_UPDATE_PATHS

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

Parent topic: UniData migration tools

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

Parent topic: UniData migration tools

NT_RECATALOGGER
NT_RECATALOGGER is a paragraph that UniData creates when you execute NT_CATALOG_MAP in a
UniData account on UNIX.
Run NT_RECATALOGGER after you move the account to the Windows platform to recompile and
recatalog your application. You cannot run NT_RECATALOGGER on Windows platforms unless you
executed NT_CATALOG_MAP on UNIX. Run NT_RECATALOGGER after you move your account,
convert machine type (if needed), and run NT_UPDATE_PATHS.

Parent topic: UniData migration tools

SQL_UNIX_2_NT
SQL_UNIX_2_NT is a UniBasic program that creates a Windows-style privilege table from a UNIX
style privilege table.
In the Windows-style table, the OWNER for all items is ADMINISTRATORS (the local Administrators
group on the Windows platform). UniData maintains any privileges granted on the UNIX side to
PUBLIC, but does not maintain privileges granted to individual users. However, the program keeps a
copy of the UNIX-style privilege table for your reference.
SQL_UNIX_2_NT also checks to see if schema was migrated. If so, the program changes the
value of Attribute 2, TABLE_OWNER, to ADMINISTRATORS in all records in the SQLTables file, the
SQLColumns file, and the SQLStatistics file.

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

27
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

Parent topic: UniData migration tools

Special considerations for UniData SQL

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

Migrating schema and dictionaries

UniData supports the ability to migrate schema and dictionaries generated under release 3.3.x or
above of UniData on UNIX. However, you might encounter difficulties if you rename one or more data
or dictionary files to resolve naming conflicts. Naming conflicts arise because Windows platforms are
case insensitive. If you have two files on UNIX whose names differ only by case, you must rename one
before moving your account to the Windows platform.
It is important to remember that case insensitivity affects views as well as base tables. For instance, if
a UNIX account has a view called RENTALS and a view called Rentals, the names of their dictionaries
are in conflict. The dictionary names (D_DV_RENTALS and D_DV_Rentals) differ only in case. You
should rename one of the views before moving the account to the Windows platform.

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

If NT_SCOUT identifies a catastrophic problem such as a file naming conflict, and views were
generated on an affected file, the warning message includes the information that the problem will
impact UniData SQL. Even after you resolve the file name conflict, you need to regenerate views and
schema against one or more data files. We recommend you perform these steps before you move the
account to the Windows platform. The following example shows the error message generated when a
catastrophic problem affects UniData SQL:
...
CATASTROPHIC -- Directory/file name conflict in 'Student'
Name conflicts with 'STUDENT'
and WILL affect your sql views
...
If you fail to resolve a catastrophic item, you will lose data when moving your account to the Windows
platform. If the item affects UniData SQL views and you resolve the item without regenerating views
and schema, you will encounter problems in UniData SQL on Windows platforms.

Migrating privilege tables

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

28
 Migrating privilege tables

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

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

The migration tool SQL_UNIX_2_NT creates a Windows-style privilege table from a UNIX-style table.
A copy of the UNIX-style table is retained so that you can compare the two. The Windows style table
observes the following rules:
▪ The OWNER for all items in the privilege table is set to ADMINISTRATORS (the local Administrators
group on the Windows machine)
▪ All privileges granted to PUBLIC on the UNIX side are retained for PUBLIC on the Windows platform.
Privileges granted to individual users on the UNIX side are not migrated to the Windows platform.
After you run SQL_UNIX_2_NT, any member of the local Administrators group can use the UniData SQL
GRANT command to make the privilege table consistent with your UNIX table.

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

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

29
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

Process overview
This overview presents a high-level view of the migration process. Click the links to see the detailed
steps.
1. Copying the NTMIGRATE file
Copy the directory NTMIGRATE from your Windows system to your UNIX system.
2. Running the migration tools
Run the migration tools for each UniData account.
3. Moving the programs to the Windows machine
Move the programs and data files from your UNIX machine to the Windows machine. Once
moved, you must update paths, compile and catalog the applications, then test your
applications.

Copying the NTMIGRATE file

Copy the directory NTMIGRATE from your Windows system to your UNIX system.
In the following examples, the NTMIGRATE directory was copied to the UniData demo account on a
UNIX computer.

1. Use FTP or copy the NTMIGRATE directory to the media of your choice and load it into a UniData
account directory on your UNIX machine.
2. Because NTMIGRATE is a DIR-type file, create the VOC entry for NTMIGRATE and create a
dictionary, as shown in the following example.
:SETFILE NTMIGRATE NTMIGRATE
Establish the file pointer
Tree name NTMIGRATE
Voc name NTMIGRATE
Ok to establish printer(Y/N) = Y
SETFILE completed.
:CT VOC NTMIGRATE
VOC:

NTMIGRATE:
DIR
NTMIGRATE
:CREATE.FILE DICT NTMIGRATE

30
 Running the migration tools

Create file D_NTMIGRATE, modulo/1,blocksize/1024

Hash type = 0
Added "@ID", the default record for UniData to DICT NTMIGRATE.
3. The tools in the NTMIGRATE file are executed one UniData account at a time. In each UniData
account you want to preprocess, set a pointer to the NTMIGRATE file, as shown in the following
example:
:SETFILE /usr/ud82/demo/NTMIGRATE NTMIGRATE
Establish the file pointer
Tree name /usr/ud82/demo/NTMIGRATE
Voc name NTMIGRATE
Dictionary name /usr/ud82/demo/D_NTMIGRATE
Ok to establish printer(Y/N) = Y
SETFILE completed.
:CT VOC NTMIGRATE
VOC:

NTMIGRATE:
DIR
/usr/ud82/demo/NTMIGRATE
/usr/ud82/demo/D_NTMIGRATE
:
4. Compile the following UniBasic programs in the NTMIGRATE file:
▪ NT_SCOUT
▪ BUILD.FULL.PATH
▪ TAR2FTP
▪ NT_CATALOG_MAP
You do not need to compile NT_UPDATE_PATHS or SQL_UNIX_2_NT at this time because you
execute those programs on your Windows machine.
Next topic: Running the migration tools
Parent topic: Process overview

Running the migration tools

Run the migration tools for each UniData account.
1. Run NT_SCOUT in the account to identify migration items.
a. Optional: Create exclude.files.
Before you execute NT_SCOUT in each account, decide if there are program files in the
account that you do not want to preprocess. If there are, create the NTMIGRATE.LOC file
and then create exclude.files, as shown in the example:

31
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

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

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

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

c. Print the output files from NT_SCOUT.

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

32
 Running the migration tools

d. Correct all CATASTROPHIC items.

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

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

NT_SCOUT only identifies possible conflicts and problems in your UniData account. We
cannot supply an automated solution to these conflicts and problems, because the correct
solutions depend on your application and environment. Resolving these items may be time
consuming, but is crucial to the success of your migration to the Windows platform. Refer
to your UniData manuals and your UNIX and Windows platform documentation to help you
determine the best ways to resolve these items.
e. Analyze WARNING items.
You can resolve WARNINGS (listed in UNIX_NT_WARNING) on either the UNIX or the Windows
platform. These items will not cause data loss while you are moving programs and files, but
they may cause runtime errors and other unexpected results when you attempt to run your
application on the Windows platform. It is not necessary to resolve all these issues before
you move your programs and data, but you need to identify which items must be addressed,
and how they should be addressed. The Warnings report from NT_SCOUT helps you to size
the conversion effort and determine if some items should be addressed before you move to
the Windows platform.

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

f. Back up the account.

Consider creating and verifying a full backup of your UniData account at this time. A backup
is particularly advisable if you have expended a lot of effort resolving migration items.
2. Optional: Run NT_CATALOG_MAP in the account to create a VOC paragraph that compiles and
catalogs UniBasic programs on Windows platforms. This is an optional step. You can recompile
and catalog programs manually if you prefer.
The following example shows NT_CATALOG_MAP run from the ECL prompt.
:RUN NTMIGRATE NT_CATALOG_MAP
No data retrieved from current (S)SELECT statement.
1 records selected to list 0.
2 records selected to list 0.
BP
4 records selected to list 0.
:

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

33
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

3. Run TAR2FTP in the account to create a script for moving the programs and data files to
Windows platforms using FTP. This is an optional step. You can move the account using tape or
FTP the account manually, if you prefer.
The following example shows TAR2FTP run from the ECL prompt.

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

Next topic: Moving the programs to the Windows machine

Previous topic: Copying the NTMIGRATE file
Parent topic: Process overview

Moving the programs to the Windows machine

Move the programs and data files from your UNIX machine to the Windows machine. Once moved, you
must update paths, compile and catalog the applications, then test your applications.
1. If you used TAR2FTP as described in step 3 of Running the migration tools, on page 31, move
TAR2FTP output to Windows platforms. Otherwise, move the programs and data files from your
UNIX machine using your own method, and proceed to step 2.
You can use FTP (ASCII mode) to move the tar2ftp.out text file (from NTMIGRATE.LOC
in your current account directory) to your Windows platform. Copy the file to a directory one
level higher than the account will be. (For instance, if the account directory will be \users
\ACCOUNT, then copy tar2ftp.out into \users.)
a. Edit the FTP script. At minimum, you need to edit two lines in this file. At the top of the file,
replace the lines beginning with “#” by a UNIX user ID and a UNIX password for the machine
where the account currently exists. Use the DOS editor or Notepad to edit the lines in the file.
If you want to transfer files that were not included in tar2ftp.out (for instance, data files
physically outside the account directory), you can add lines to include them at this time. If
you want to move only a portion of the contents of the account directory, you can remove
lines from tar2ftp.out.

34
 Moving the programs to the Windows machine

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

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

b. Execute the FTP command by using the -s argument to supply the input file, as shown in the
following example:
D:\users\default>FTP -s:tar2ftp.out eagle_
The script completes the following actions:
▪ Creates the required directory structure.
▪ Copies the programs and data from UNIX.
▪ Executes the UniData convcode and convdata commands to convert machine format
for UniBasic compiled programs and UniData hashed files, respectively. See convcode,
convdata, convidx, on page 26 for more information about these commands.

35
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

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

2. Convert the machine format in programs, data and indexes using convcode, convdata, and
convidx. This is a required step if you are migrating from a high-byte UNIX system and you did
not use TAR2FTP. If you did use TAR2FTP, proceed to step 3.
The following screens show output from the commands. For these examples, a modified demo
database was migrated from an HPUX platform to a Windows platform. The first example shows
output from convdata, run with the -r (recursive) option:

The next example shows the output from convcode:

36
 Moving the programs to the Windows machine

The next example shows the output from convidx:

3. Run NT_UPDATE_PATHS in the account to update paths in VOC entries.

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

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

execute.

c. Compile the NT_UPDATE_PATHS program on your Windows platform, as shown in the

following example:
:BASIC NTMIGRATE NT_UPDATE_PATHS

Compiling Unibasic: \UNIDATA\NTMIGRATE\NT_UPDATE_PATHS in mode

'u'.
compilation finished
:
d. Execute NT_UPDATE_PATHS from the ECL prompt, as shown in the following example:

Note: NT_UPDATE_PATHS compiles and catalogs a called subroutine named

BUILD.FULL.PATH, which UniData uses to update the VOC pointers in your account.

4. Compile and catalog the application.

If you executed NT_CATALOG_MAP on UNIX as described in step 2 of Running the migration
tools, on page 31, execute NT_RECATALOGGER as shown in the following example. You
cannot run NT_RECATALOGGER on Windows platforms unless you executed NT_CATALOG_MAP
on UNIX.
:NT_RECATALOGGER
Compiling programs

37
Chapter 2: Migrating applications to UniData for Windows from UniData for UNIX

Now compiling file BP

Compiling Unibasic: BP\NUM_TST in mode 'u'.

Basictype is changed, BP\NUM_TST is compiling in mode 'p'
compilation finished

Compiling Unibasic: BP\BASIC_STATIC in mode 'u'.

compilation finished

Compiling Unibasic: BP\TIMETEST1 in mode 'u'.

compilation finished

Compiling Unibasic: BP\TIMETEST2 in mode 'u'.

compilation finished
Now cataloging file BP
:
5. If the account is a UniData SQL account, convert the UniData SQL privilege table into the
Windows platform format using the SQL_UNIX_2_NT program.
a. Compile the UniBasic program, as shown in the following example:
:BASIC NTMIGRATE SQL_UNIX_2_NT

Compiling Unibasic: D:\UNIDATA\NTMIGRATE\SQL_UNIX_2_NT in mode

'u'.
compilation finishedRun SQL_UNIX_2_NT
b. Run SQL_UNIX_2_NT from the ECL prompt, as shown in the following example:
:RUN NTMIGRATE SQL_UNIX_2_NT
The first time you run SQL_UNIX_2_NT in an account, the program makes a copy of the
privilege table for your future reference. The copy is called unix_privilege. The program
then clears all records from the privilege table and rebuilds the table by processing records
from unix_privilege.

Tip: If you execute SQL_UNIX_2_NT more than once in an account, the

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

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

38
 Moving the programs to the Windows machine

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

Remember the following points:

▪ Privileges granted to PUBLIC on the UNIX system are unchanged on the Windows
platform.
▪ Ownership and privileges associated with individual users are not reflected in the new
privilege table.
▪ The OWNER of all items in the privilege table is now ADMINISTRATORS (the local
Administrators group). You must log in as a member of the local Administrators group on
your Windows platform if you wish to grant other privileges, or create schema, for any of
these items.
▪ If you wish to modify the new privilege table, use the UniData SQL GRANT and REVOKE
commands to do so.
6. After you have completed the sequence for each UniData account, begin testing your application.
Previous topic: Running the migration tools
Parent topic: Process overview

39
Chapter 3: Managing the UDTelnet and UDSerial
services
Windows platforms support UDTelnet and UDSerial services.
The UniData Telnet Service (UDTelnet) enables multiple users to log on to a single Windows platform
to run UniData. With the UniData Telnet Service installed and started, your Windows platform exports
a logon prompt to its network so that network users can log on and run UniData.
The UniData Terminal Server (UDSerial) enables users to access UniData on a Windows platform
through a modem or an asynchronous terminal connected through one of the Windows platform’s
COM ports. A terminal or other serial device that is managed by the UniData Terminal Server also has
complete Telnet access to the TCP/IP network where your Windows platform resides.

Introduction
The UniData Telnet Service is a service that exports a logon prompt to a network. Users can log on
through the logon prompt, and multiple users can work on the system at the same time. UDTelnet
creates an alternate console window when a user runs programs other than UniData in that window,
just as they would run in a console window.
When a user opens a UniData session through UDTelnet, UniData writes screen output directly to a
socket. Using the socket is more efficient than writing screen output to the alternate console window.
When a user “shells out” from UniData to execute a non-UniData process (for instance, !DIR), UniData
directs output to the alternate console window. This allows programs that write to “standard output”
to function without modification under UDTelnet.
The UniData Terminal Server (also called UDSerial) is a software product that enables you to connect
serial devices to your network. If you have UDSerial running on a Windows system, any serial device
connected to the Windows system through UDSerial can have complete Telnet capabilities throughout
the Windows network.
Functionally, UDSerial simply connects a device to Telnet. To run UniData through UDSerial, you must
have both UDSerial and UDTelnet installed and running.

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

Requirements for the services

Review the following information to ensure your system meets the requirements using the UDTelnet
and UDSerial services.
UDTelnet service requirements:
▪ Your system must be running Windows XP or greater, and have the Extensible Administration Tool
installed. UDTelnet runs with Windows Server and Windows Workstation.
▪ UDTelnet uses less than one megabyte of disk space. During the installation process, UniData
installs the files for UDTelnet in the Telnet subdirectory in your \U2\ud82\bin folder.

40
 UDTelnet service features

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

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

▪ You must have a Telnet client running on your Windows system. The UDTelnet Service interacts
with the existing Telnet client.
UDSerial service requirements:
▪ Your system must have TCP/IP installed. Consult your Microsoft documentation for information
about TCP/IP.
▪ Your system must have one or more serial ports. These may be native ports built into the PC,
or multiport cards (provided the cards have Windows drivers). UDSerial functions with any
serial device that is supported by Windows platforms. Consult your hardware documentation or
hardware vendor if you are not sure whether a serial device or serial port is supported by your
Windows platform.
▪ UDSerial uses less than one megabyte of disk space.
▪ The UniData Terminal Server and configuration screens take less than one megabyte of system
memory to run. You need approximately 100Kb of additional memory for every UDSerial user
logged on to your system, over and above the memory required for the application.
▪ To access UniData through UDSerial, you must also have the UniData Telnet Server (UDTelnet)
installed and running. UDSerial connects asynchronous terminals to Telnet through the UDTelnet
Service.

UDTelnet service features

UDTelnet service includes the following features.
▪ Configurability: Through XAdmin, you can perform the following tasks to configure the UDTelnet
Service:

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

▫ Establish a default configuration for all users who access your system through UDTelnet.
▫ Create individual user profiles that establish session characteristics for each user.
▫ Create a combination of custom profiles and a default configuration.
▫ Set parameters, including the number of concurrent UDTelnet sessions and the number of
logon attempts to allow each user.
▫ Make tuning changes that may affect performance for users logging in via UDTelnet to execute
MS-DOS commands.
▪ Direct access to UniData: You can configure the UniData Telnet Service so that users never see the
Windows command prompt. Users can log directly on to UniData, or on to a custom application.

41
Chapter 3: Managing the UDTelnet and UDSerial services

▪ Security: Users cannot log on through the Telnet Service unless:

▫ They have a valid logon on the Windows workstation or domain.
▫ They belong to a local group that has the user privileges Access this computer from
network and Log on locally assigned.
Users logged on through Telnet have only the permissions already associated with their Windows
system account, just as if they had logged on from the console.
▪ SSL: For UniData 6.0 and higher, the UniData telnet server, udt.exe has been changed to listen
on two ports, the ordinary telnet port and an SSL port, defaulted to 23 and 992, respectively.
Depending on the requested port by the client, either a nonsecure or secure connection will be
established.
If a telnet session is started on a secured port (992 by default), all data transferred between the
telnet window and the UniData database server is secured. For a more detailed description, see
Developing UniBasic Applications.
The UniData telnet service can be configured to encrypt the data sent over the connection using
strong SSL encryption. Security can then be further enhanced with the use of SSL certificates. This
ensures that a client device without the correct certificate cannot even connect to the service.
Thus, the UniData telnet service’s security is based not just on something you know, that is, your
login credentials, but also on something you have, that is, the SSL certificate, when so configured.
This is significantly more secure than traditional telnet servers.
▪ Terminal emulation: UniData uses the udtermcap file to validate terminal settings. The
udtermcap file, located in the udthome\include directory, contains definitions for terminals
supported within UniData. By default, the UDTERMCAP file contains definitions for the following
terminals:
▫ VT100, VT200, VT300, VT400, VT420
▫ WYSE60
▫ ADDS-VP
▫ IN 9400
▫ IN 9400B
You can add terminal definitions to udtermcap, or modify the definitions, if you desire.
▪ Integration with UniData serial terminal support: Connecting the UniData Telnet Service with
UniData Serial Terminal Support provides the same functionality for users logged in from “dumb”
terminals and other serial devices.

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

UDSerial service features

UDSelnet service includes the following features.
▪ Security: Users cannot log on through the Terminal Server unless:
▫ They have a valid logon ID on the Windows workstation or domain.
▫ They belong to a local group that has the User Rights Access this computer from network and
Log on locally assigned.
Users logged on through the terminal server have only the permissions already associated with
their Windows system account, just as if they had logged on from the console.

42
 Security

▪ Terminal emulation: The UniData Terminal Server can use any terminal emulation supported by
UniData. UniData uses the udtermcap file to validate terminal settings. The udtermcap file,
located in the udthome\include directory, contains definitions for terminals supported within
UniData. By default, the UDTERMCAP file contains definitions for the following terminals:
▫ VT100, VT200, VT300, VT400, VT420
▫ WYSE60
▫ ADDS-VP
▫ IN 9400
▫ IN 9400B
You can add terminal definitions to udtermcap, or modify the definitions, if you desire.
▪ Logging: The UniData Terminal Server writes a record to the Windows Event Log every time a user
connects or disconnects, along with a record of what process the user executed, the result code
from that process, and any Windows system errors that pertain to the Terminal Server.
▪ Integration with UDTelnet service: Connecting the UniData Terminal Server with UDTelnet provides
the same functionality for users logged on through Telnet.

Security
Users cannot log on through the Terminal Server unless:
▪ They have a valid logon ID on the Windows workstation or domain.
▪ They belong to a local group that has the User Rights Access this computer from network and
Log on locally assigned.
Users logged on through the terminal server have only the permissions already associated with their
Windows system account, just as if they had logged on from the console.

Terminal emulation
The UniData Terminal Server can use any terminal emulation supported by UniData. UniData
uses the udtermcap file to validate terminal settings. The udtermcap file, located in the
udthome\include directory, contains definitions for terminals supported within UniData. By
default, the UDTERMCAP file contains definitions for the following terminals:
▪ VT100, VT200, VT300, VT400, VT420
▪ WYSE60
▪ ADDS-VP
▪ IN 9400
▪ IN 9400B
You can add terminal definitions to udtermcap, or modify the definitions, if you desire.

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

43
Chapter 3: Managing the UDTelnet and UDSerial services

Integration with UniData telnet service

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

Managing Windows UDTelnet sessions (Windows only)

You can manage the UDTelnet service and UDTelnet users with XAdmin.

Modifying the UDTelnet session parameters

You can modify any of the UDTelnet server parameters in XAdmin using the UDTelnet tab.

Note: To use the new settings, you must save, stop, and restart the UniData Telnet service

Note: You need to log in to the local Administrator account or log on as a member of the
Administrators group that manages the Windows server to configure the Telnet services.

1. In XAdmin, from the Admin Tasks view, expand Network Services and double-click UDTelnet.
The UDTelnet tab opens, as shown in the following example.

2. To change the port number for the UDTelnet service, enter the new port number in the Port #
field. By default, the telnet port number is set to 23.
UniData stores the Telnet port number on the Windows server as a TELNET_SOCKET_NUM entry
in the Windows registry.
3. To disable the Telnet port, click the Disable Telnet Port check box.
4. In the SSL Port # field, enter the SSL port number that the UDTelnet service should monitor for
client connections. The default value for the SSL Port number is 992. It is not recommended to
change this unless you have another service that requires port 992.
5. To disable the SSL telnet port, click the Disable SSL Telnet Port check box.
6. Set the Telnet connection parameters:
a. In the Max. Logon Attempts field, define the number of failed log in attempts a user is
allowed before the UDTelnet connection is dropped. The default setting is 4.

44
 Modifying the UDTelnet session parameters

b. In the Logon Pause field, enter the number of seconds to pause between login attempts if a
login attempt fails. The default is 4 seconds.
c. In the Logon Timeout field, enter the time, in seconds, that the system waits for a response
to a login prompt. When the timeout occurs, the UDTelnet connection is dropped. The
default is 30 seconds.
d. In the Termination Pause field, enter the number of seconds to pause after the final failed
login attempt. After the specified pause, the connection is dropped. The default is 4 seconds.
When the UDTelnet client is closed without logging out, the ON.EXIT command is not
executed. This can cause an unhandled exception or access violation in the event log.
Change the termination pause to increase the time and allow the main thread to exit
properly.
7. Set the keep alive parameters by selecting the Keep Alive check box. The Keep Alive feature
determines when inactive connections can be disconnected. When a connection becomes
inactive, keep-alive packets are periodically exchanged. When a number of consecutive packets
remain unanswered, by default 20, the connection is broken.
a. In the Keep Alive Interval field, enter the interval, in milliseconds, to separate keep alive
retransmissions until a response is received. Once a response is received, the delay until the
next keep alive transmission is controlled by the value of Keep Alive Time. After the number
of retransmissions specified by Max. Data Retransmissions are unanswered, the connection
aborts. The default value is 1000 (one second).
b. In the Keep Alive Time field, specify how often TCP attempts to verify that an idle
connection is still valid by sending a keep alive packet. If the connection is still valid, the
remote system will acknowledge the keep alive transmission. The default value is 7,200,000
milliseconds (two hours).
c. In the Max. Data Retransmissions field, specify the number of times TCP retransmits an
individual data segment before aborting the connection. The retransmission timeout is
doubled with each successive retransmission on a connection. It is reset when responses
resume.
8. In the Backlog queue field, enter the maximum length of the queue of pending UDTelnet
connections. The default value is 14.
9. Select the Detach process check box to create the process as detached.
10. Select the Create desktop check box to create the Telnet service on its own WinStation/Desktop
and assign it to the process.
11. Select the SSL Protocols check boxes to choose which SSL protocols will be enabled for use with
SSL Telnet. By default, TLSv1, TLSv1.1, and TLSv1.2 are enabled at install. For some outdated
SSL Telnet client software, newer protocols, such as TLSv1.1 and TLSv1.2, may not be supported.
It is not recommended to enable SSLv3.

Note: The ability to changes these protocols is only available if you are running UniData 8.2.1
or UniVerse 11.3.2 or higher.

12. Select the SSL Options radio buttons to change options for use with SSL Telnet. By default,
NO_TLS_FALLBACK_SCSV is selected and recommended. TLS_FALLBACK_SCSV is used to
prevent protocol downgrade (i.e. POODLE attack). Since both client and server need to support
this for it to work, it is recommended to keep the default setting of NO_TLS_FALLBACK_SCSV in
place. TLS_FALLBACK_SCSV should not be set unless it can be verified that all SSL Telnet client
software in use supports signaling cipher suite values and protocol downgrade is preferred to be
prevented.
13. In the Logon Banner field, enter the text that uses see when they connect to the host.
14. In the SSL Logon Banner field, enter a message to display when a user connects using SSL.
15. Click OK to save the new settings. Changed settings do not affect Telnet sessions that are already
started. New sessions started after the service parameters were changed use the new parameters.

45
Chapter 3: Managing the UDTelnet and UDSerial services

Starting, stopping, and pausing the UDTelnet server

Use the UDTelnet tab to control the UDTelnet server. You can alternatively use the Control Panel to
control the server.
1. In XAdmin, from the Admin Tasks view, expand Network Services and double-click UDTelnet.
2. Click Start to start the UDTelnet Server.
3. Click Stop to stop the UDTelnet Server.

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

4. Click Pause to pause the UDTelnet Server.

Adding, updating, or deleting UDTelnet users

Add a UDTelnet user on the UDTelnet Users tab. You can also update any currently existing users or
remove them.

About this task

At installation, UDTelnet is started with a default configuration that allows any user who can access
your Windows system from the network to access the system through UDTelnet as well. This default
behavior is acceptable in many instances. However, administrators might want to grant only certain
users Telnet access, or to create individual user profiles.

Warning: If you remove the Default profile, no user can log on through UDTelnet unless you have
created a specific profile for the user. You can update the Default profile by selecting it from the
UDTelnet Users tab and clicking Update. The profile displays as shown in the following example:

46
 Adding, updating, or deleting UDTelnet users

Procedure
1. In XAdmin, from the Admin Tasks view, expand Network Services and double-click UDTelnet
Users.
The UDTelnet Users tab displays, as shown in the following example.

2. Click Add.
A dialog box similar to the following example displays.

3. Enter the details for the new UDTelnet user:

a. In the User Name field, enter a unique user name for the UDTelnet user.
b. In the Default Shell field, enter the full path of an executable. In the default profile, this is set
to udtbin\udt.exe, which starts a UniData session.

47
Chapter 3: Managing the UDTelnet and UDSerial services

c. In the Startup Directory field, enter the full path of the working directory to which you want
to connect when you log on. In the default profile, this is set to the UniData demo account.
d. In the Command Line field, enter any arguments you want to pass to the default shell. In the
default configuration, this is blank.
e. Enter the full path to the UDTHOME directory in the UDTHOME field.
f. Select the ANSI Version 3.x check box if you want to enable faster screen refreshes for
terminals that support ANSI 3.x color.
g. Select the Use Redirection Chars check box if you want to map unprintable characters to
printable characters.
h. Select the Prompt Directory check box if you want the user to select a working directory
when they log on.

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

If you select Prompt Directory in the Default Profile, UniData creates a profile for each user
who would normally receive the default user profile. UniData creates the individual profiles
the first time a user chooses a startup directory different from the default. The generated
profile uses the same configuration settings as the default profile, with the exception of
Startup Directory, which is set to the directory chosen by the user when they log on.
The following example shows the appearance of the screen when a user logs on:
Path (C:\U2\ud82\demo) : \U2\ud82\cbrown
Notice that the default path is C:\U2\ud82\demo, and the user is selecting an alternate
startup directory, \U2\ud82\cbrown. Pressing Enter starts a UniData session in
\U2\ud82\cbrown. This logon session also creates a profile for the user, which you can
view or edit from the Telnet Users tab. The next time the user logs on through Telnet, the
default path is changed, as shown in the following example:
Path (\U2\ud82\cbrown) :
i. Click OK to save the new user.
4. To update a UDTelnet user, select the user, and then click Update to modify the previously
described fields.
5. To delete a UDTelnet user, select the user, and then click Delete to remove them.

Managing Windows UDSerial sessions (Windows only)

You configure the UniData Terminal Server by running Serialcfg.exe on the server.

Note: In previous versions of UniData, you could manage UDSerial sessions through UniAdmin.
UniAdmin has since been replaced with XAdmin, and the UDSerial configuration functionality was
not implemented due to lack of use. Contact [email protected] for information about
the Serialcfg.exe file or to request the UDSerial configuration functionality in XAdmin.

Configuring SSL for Telnet

There are two files in the unishared directory on the server that you need to be familiar with,
udtelnetd.conf and .udscrfile.
Udtelnetd.config is the UniData Telnet server configuration file, and .udscrfile is the
security file containing the path to the security context file. Both of these files are located in the

48
 Configuring SSL for Telnet

unishared/unirpc directory. The default location can be found by examining the registry record
at HKEY_LOCAL_MACHINE\Software\Rocket Software\unishared.
▪ udtelnetd.conf - The UniData telnet server configuration file.
▪ udscrfile - The security file containing the path to the security context file.
udtelnetd.conf has the following format per line:
security_context_record_id password
Where security_context_record_id and password are the security context record ID and password used
to get security context in a pregenerated security file (defined in .udscrfile). This security context
record ID is system-wide, which means that the security context record identified by this ID will be
used for all secure telnet connections, rather than for a single user’s connection.
In addition, there are four new registry keys for SSL, found in HKEY_LOCAL_MACHINE\Software
\Rocket Software\UniData\8.2\UDTelnet.
The following table describes the registry keys for SSL.

Registry key Description

BACKLOG This key controls the maximum number of concurrent clients
requesting a connection. The default setting is 14 connections. This
key applies to both secure and nonsecure telnet.
DEBUG_LEVEL This key controls udt.exe debug message logging for SSL
processing and takes a value from 0 to 10, with a 0 setting indicating
no logging. The log file is generated under /temp on the system
drive with the file name tl_server_pid.log where pid is the
process id for udt.exe. The default setting is 0.
DISABLE_SSL_TELNET If set to 1, the SSL telnet service is disabled. The default setting is 0,
which enables the SSL telnet service.
SSL_LOGIN_BANNER This key defines the message text showed when a user first connects.
The default message is Welcome to UniData Secure
Telnet Server.
TELNET_SSL_SOCK_NUM This key sets the telnet port number. The default setting is port 992.
DISABLE_TELNET If set to 1, the telnet service is disabled. The default setting is 0,
which enables the telnet service.

49
Chapter 4: UniData and background processes
This chapter explains the background processes for UNIX (daemons) and Windows (services) and the
processes specific to UniData.

Daemons and services

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

Principal UniData daemons or services

On UNIX, three daemons control your UniData environment. All three of these UniData daemons run
as root. On Windows, database services control your UniData UniData.
When a user starts a UniData session, the user’s process, called a udt, communicates with the
daemons or services. The udt process runs with the permissions valid for the user, preventing
inappropriate file access by the UniData daemons or services.
▪ Lock tracking — smm records all UniBasic locks and semaphore locks, identifying which UniData
user holds each.
▪ Process cleanup — At periodic intervals, the cleanupd daemon or service checks the cleanupd
daemon or service to see if terminated process flags have been set. If cleanupd detects a
terminated process flag, it deletes the associated process from internal tables, removes requests
from the queue, and removes messages sent to the terminated process. If cleanupd receives a
message from a process, it checks to see if the message was sent from a terminated process. If so,
it throws away the message.

Shared basic code server (sbcs)

The shared basic code server, sbcs, manages shared memory used by globally cataloged UniBasic
programs. UniData starts sbcs when you 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 into
shared memory as needed, and tracks the programs that are loaded and the number of processes
that are running each one. When you run a globally cataloged program, sbcs checks in shared
memory, then takes the following actions:
▫ If the program is already loaded, sbcs increments the counter for the number of users 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 and
starts a counter for it.
▪ Periodically sbcs checks shared memory and removes loaded programs that are no longer in use.

50
 Shared memory manager (smm)

▪ Controlling shared memory—The sbcs daemon can attach up to 20 shared memory segments.
(On some UNIXplatforms sbcs cannot attach 20 segments because the operating system imposes
a lower limit. For instance, AIX allows a process to attach only 10 shared memory segments.)
▪ The maximum size of each segment for sbcs is determined by the UniData configuration
parameter SBCS_SHM_SIZE. sbcs attaches segments as it needs to load globally cataloged
programs, and releases memory back to the operating system when it is no longer needed.
▪ Process cleanup — At periodic intervals, the sbcs process checks the cleanupd daemon or
service to see if terminated process flags have been set. If sbcs detects a terminated process flag,
it removes all messages that are sent for the process. If the terminated process is the only process
that is using a program in shared memory, the program is removed from shared memory. sbcs
uses the process ID to determine if a message it receives is from a terminated process. If so, sbcs
discards the message.

Note: For more information about sbcs, see Managing cataloged programs, on page 211.

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 (on UNIX) or start the UniData Database Service
(Windows). UniData stops smm when you run stopud (on UNIX) or stop the UniData Database Service
(Windows).
UniData processes (udt processes) communicate with smm to request and return shared memory. The
UniData processes request shared memory from smm for the following tasks:
▪ License control—The smm process tracks the number of users for which a site is licensed, and
prevents more than that number of users from logging in to UniData. When a license is about to
expire, smm also displays warning messages.
▪ User process tracking — When a user logs on to UniData, smm assigns an internal tracking number
to the user’s process and records information about the process in tables within UniData.
▪ Buffering program variables.
▪ Storing query records and intermediate results.
▪ Storing select lists.
▪ Storing expression buffers.
▪ Managing a current modulo table for dynamic files.
▪ Process cleanup—At periodic intervals, the smm process checks the cleanupd daemon or service
to see if terminated process flags have been set. If smm detects a terminated process flag, it checks
all ipc IDs. If one of the ipc IDs is invalid, smm exits, bringing down UniData. smm also checks all
process groups to see if a group leader terminated abnormally. If so, smm removes all self-created
shared memory pieces and reclaims all global pages that are occupied by the terminated group.
smm also corrects inconsistencies the global control tables (GCT) might have. An inconsistency
could exist if the process was updating a GCT when it terminated.
The startud command starts smm, which creates a control table (CTL) in shared memory. The CTL
tracks all information about the shared memory segments that smm manages. The size of the CTL is
related to the number of users on the system and to a series of configuration parameters.
See UniData and memory, on page 55 and UniData and UNIX devices (UNIX only), on page 342 for
more information about smm.

51
Chapter 4: UniData and background processes

Note: If you are using NFS-mounted file systems on UNIX, make sure the file systems are mounted
as SOFT mounts. If they are mounted as HARD mounts and the remote system is unavailable, the
internal system functions to determine available space on the file system hang until the file system
becomes available. Because of this behavior, udt processes trying to log on to UniData, processes
requesting new shared memory global pages, and processes trying to log off hang. If you mount
NFS files as SOFT mounts, these system functions will timeout and return instead of hang.

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

UniRPC (unirpcd)
The UniRPC service is used XAdmin, UniObjects, UniObjects for Java, UniData ODBC, UniOLEDB, and
UCI to communicate with UniData on the server.

sync daemon (UNIX only)

If you notice significant performance degradation during a checkpoint when you are running the
Recoverable File System (RFS), you can start sync daemons by setting the udtconfig parameters
N_SYNC and SYNC_TIME. Sync daemons periodically flush updated pages from the system buffer to
the log files, reducing the amount of time it takes to complete a checkpoint.
N_SYNC determines the number of sync daemons UniData starts. SYNC_TIME defines, in seconds, the
amount of time the sync daemons wait before scanning the system buffer for updated pages.

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

Monitoring UniData daemons or services

You can monitor daemons or services using the UniData for UNIX showud command, or on Windows
using the Control Panel.
To monitor UniData services on Windows, open the Control Panel and then double-click Services.
The UniData Database Service, NFA Server, Telnet Service, and Terminal Server are all started.
"Automatic" in the Startup column indicates that these services automatically start when you boot
your Windows system.

52
 The udt.errlog file

Note: ObjectCall is not available beginning at UniData 8.1.0.

UniData for UNIX provides the showud command to monitor the status of the daemons. The system-
level command showud displays UniData daemons that are currently running.
The following screen shows output from showud:
# showud
UID PID TIME COMMAND
root 19503 0:00 /disk1/ud82/bin/aimglog 0 27543
root 19504 0:00 /disk1/ud82/bin/aimglog 1 27543
root 19505 0:00 /disk1/ud82/bin/bimglog 2 27543
root 19506 0:00 /disk1/ud82/bin/bimglog 3 27543
root 19494 0:06 /disk1/ud82/bin/cleanupd -m 10 -t 20
root 19500 1:14 /disk1/ud82/bin/cm 27543
root 19490 0:00 /disk1/ud82/bin/sbcs -r
root 19499 0:01 /disk1/ud82/bin/sm 60 10705
root 19483 0:05 /disk1/ud82/bin/smm -t 60
root 19525 0:00 /disk1/unishared/unirpc/unirpcd
#

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

Daemon/Service 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
(Windows only) udtbin\startud.log udtbin\startud.errlog
startud
(Windows only) rm udtbin\rm.log udtbin\rm.errlog
(Windows only) rw udtbin\rw.log udtbin\rw.errlog
(Windows only) sm udtbin\sm.log udtbin\sm.errlog

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

For more information and examples, see Starting, stopping, and pausing UniData, on page 77.

The udt.errlog file

If a UniData process encounters file corruption in a data file during processing, the process writes
a message to the udt.errlog in udtbin. System administrators can monitor this log and take
corrective action for the specified file.
The following example illustrates errors that are printed to the udt.errlog when a SELECT
statement is run against a corrupted file:

53
Chapter 4: UniData and background processes

udtno=1,pid=937,uid=1172,cwd=/home/claireg,Sep 12 12:44:46
1:grpno error in U_blkread for file 'TEST', key '', number=3

udtno=1,pid=937,uid=1172,cwd=/home/claireg,Sep 12 12:44:46
1:blkread error in U_read_group for file 'TEST', key '', number=3

udtno=1,pid=937,uid=1172,cwd=/home/claireg,Sep 12 12:44:46
1:read_all_block_in_group error in U_gen_read_group for file
' ', key ' ', number=0

54
Chapter 5: UniData and memory
This chapter describes how UniData interacts with the operating system kernel to configure, attach,
and release shared memory.

Shared memory on Windows or UNIX platforms

Shared memory is a region of memory that one or more processes can access. Shared memory resides
on a UNIX or Windows system outside the address space of any process. It is partitioned into segments
depending on the configuration of the system. As a process requires memory, the process attaches a
segment to its own address space. Processes use UNIX system or Windows system-level calls to create,
attach, and release shared memory segments.
UNIX platforms only. UNIX kernels define certain limits, such as the maximum and minimum size
of a shared memory segment and the maximum number of shared memory segments the system
supports. The names of these kernel parameters vary from system to system. The following table lists
kernel parameters that are related to shared memory on an HP-UX system.

UNIX Parameter Description

shmmax The size, in bytes, of the largest shared memory segment the system
supports.
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 to affect
the configuration. Some UNIX versions also have fixed limits on some parameters. Other UNIX
versions allow the system administrator to change parameter values, but procedures vary from
system to system. Refer to your host operating system documentation for detailed information
about your UNIX kernel.

Note: You can distinguish between UNIX kernel parameter names and UniData configuration
parameter 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 memory

UniData interacts with shared memory by using UNIX system or Windows system-level calls, UniData
daemons (UNIX) or services (Windows), and UniData configuration parameters (within the limits that
are imposed by the host system) to build its own structures in shared memory.
UniData, like UNIX, defines shared memory segments that can be attached by UniData processes.
The sbcs daemon or service creates shared memory structures for storing active globally cataloged
UniBasic programs.
For more information about sbcs, see Managing cataloged programs, on page 211.
The smm daemon or service creates shared memory structures for internal tables that are required by
UniData processes. UniData processes request memory for:
▪ Buffering UniBasic variables

55
Chapter 5: UniData and memory

▪ 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 is
called the system buffer. If you are using RFS, refer to Administering the Recoverable File System
for information about the system buffer.

smm and shared memory

The smm daemon or service creates shared memory segments as needed. The size and characteristics
of segments smm creates are determined by UniData configuration parameters.
Whenever UniData is started, UniData reads the .udtconfig file and stores these values in shared
memory. smm subdivides each of its segments into global pages, and subdivides each global page into
local pages.
smm also creates and maintains internal tables that track the use of the structures it creates. These
internal tables, which are stored in a shared memory structure that is called CTL, allow smm to protect
shared memory pages against accidental overwriting, and optimize the efficiency of memory use by
releasing unneeded shared memory pages back to the UNIX or Windows system.

Control table list (CTL)

When you start UniData, smm creates one shared memory segment for the UniData CTL. The CTL
remains in memory when UniData is running, and is returned to the operating system when you run
the stopud command.
CTL is subdivided into three regions, as shown in the following example.

56
 Control table list (CTL)

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 the
configuration parameter SHM_GNTBLS. SHM_GNTBLS must not
exceed the kernel parameter shmmni.
LCTs (local control tables) Each LCT records the shared memory activity of a UniData process
group. UniData determines the number of LCTs in the CTL by
the configuration parameter NUSERS. Each LCT comprises four
subtables: PI, CT, MI, and CI. A process group is related to a process
group leader, which can be a udt or SQL session, or a user that
is running UniData system-level commands from the operating-
system level on UNIX or an MS-DOS window on Windows.
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 the
parameters smm uses to compute the size of CTL.

57
Chapter 5: UniData and memory

Configuration parameter Description

SHM_GNTBLS The number of GCTs in the CTL, which is also the maximum number
of shared memory segments that UniData can attach at one time.
NUSERS The number of LCTs in the CTL, which is also the maximum number
of UniData process groups that can run at the same time. This is not
the same as the number of licenses. If using device licensing, the
recommended value is:
"(# of licenses * avg. # of connections per device) + # of phantoms"
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 process
group.
SHM_LCINENTS The number of entries available in the CI table of each LCT; this is
the maximum number of local memory segments that can be used
by a process group at one time. A local segment is made up of one
or more contiguous local pages. This value must be greater than or
equal to SHM_LMINENTS. It cannot exceed 255.
SHM_LMINENTS The number of entries available in the MI table of each LCT; this
is the maximum number of global pages or self-created memory
segments a process group can use at one time.
N_GLM_GLOBAL_BUCKET The number of hash buckets system-wide, used to hold the lock
names in shared memory. This setting directly affects performance.
Normally, the default value of this parameter should not be
changed. However, if you notice significant degradation in
performance, or your application intensively accesses specific files,
you can increase this parameter. The default value is the closest
prime number to NUSERS * 3.
N_GLM_SELF_BUCKET The number of hash buckets for the per-process locking table.
This parameter is highly application dependent. If the application
requires a large number of locks in one transaction (more than 20),
you should increase this setting to the closest prime number to the
maximum number of locks per transaction.
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 more
than 200 UNIX file systems, increase to your number of file systems.

The size of the CTL is determined by totaling the size of the various memory components. These
include 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 and
version and will be affected by additional components of UniData such as the recoverable file system
and U2 Data Replication.
You can also use the UniData command shmconf to calculate the size of CTL. See Managing memory
(UNIX only), on page 285 for more information.

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

58
 Creating and assigning memory structures

Creating and assigning memory structures

When a UniData process requests memory, smm assigns one or more global pages, as requested, and
updates the GCT (or GCTs, if global pages are assigned from more than one shared memory segment).
smm also updates the information in the requesting processes’ LCT. When the requesting process has
finished using the assigned memory, the process sends a message to smm, which releases the global
page or pages and updates the GCTs and LCT.
The following figure illustrates smm’s shared memory structures.

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

Parameter Description
SHM_LPAGESZ The size (in 512-byte blocks) of a single local page of shared
memory.
SHM_GPAGESZ The size (in 512-byte blocks) of a global page of shared memory.
SHM_GPAGESZ must be an integral multiple of SHM_LPAGESZ.
Divide SHM_GPAGESZ by SHM_LPAGESZ to obtain the number of
local pages in a global page.
SHM_GNPAGES The number of global pages in a shared memory segment. Compute
the size, in bytes, of a shared memory segment by multiplying the
size of a single global page (512*SHM_GPAGESZ) by the number
of global pages per segment (SHM_GNPAGES). This total cannot
exceed the maximum segment size that is defined by your Windows
operating system or in your UNIX kernel.

59
Chapter 5: UniData and memory

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

Parameter Description
SHM_FREEPCT Percentage of global pages in a shared memory segment that should
be kept free. If the percentage of free pages in a segment drops
below this value, smm creates a new segment to handle requests.
SHM_NFREES Number of free shared memory segments that should be kept for
UniData. If the number of free segments is larger than this value,
smm releases the additional segments back to the operating system.
If the number drops below this value, smm creates another segment.
This parameter is usually set to one.

Displaying parameter settings

Use the UniData system-level command sms -h to display the current settings for configuration
parameters that are related to shared memory.
The following screens show the output for this command for a system with a 32-user license.
UNIX example:
% sms -h
Shmid 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 = 25
SHM_NFREES = 1
SHM_FIL_CNT = 2048
JRNL_BUFSZ = 53248
Windows example:
C:\UniData82\Bin>sms -h
Shmid 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 = 25
SHM_NFREES = 1
SHM_FIL_CNT = 2048
JRNL_BUFSZ = 53248

60
 Learning about global pages

N_FILESYS = 200
C:\UniData82\Bin>

Note: Refer to UniData configuration parameters, on page 381 for further information about
these parameters.

Learning about global pages

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

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

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

Learning about local control tables

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

Syntax
lstt [-l n| -L pid]
The following screen shows the output from lstt entered with no options:
# lstt
----------------------- LCTs Statistics -----------------------
Total LCTs (Process Groups allowed): 50
LCTs Used (Active Process Groups): 1 (2% of 50) Total Ps: 2
Total Global Pages Used: 2 (256K bytes)
Total Self-created.....: 0 (0K bytes)
Total memory used......: 256K bytes
-------------------- End of LCTs Statistics -------------------

61
Chapter 5: UniData and memory

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

Use the -l or -L option to display additional information about a specific local control table. The
following screen shows an example:
# lstt -l 1
----------------------- LCTs Statistics -----------------------
Total LCTs (Process Groups allowed): 50
LCTs Used (Active Process Groups): 1 (2% of 50) Total Ps: 2
Total Global Pages Used: 2 (256K bytes)
Total Self-created.....: 0 (0K bytes)
Total memory used......: 256K bytes
Statistics for LCT-1 (Leader’s pid: 24230)
PI Entries Used (Processes): 2 (20% of 10)
MI Entries Used (LSMs).....: 2 (6% of 32)
Global Pages...........: 2 (256K bytes)
Self-created...........: 0 (0K bytes)
Total memory used......: 256K bytes
CI Entries Used (BLKs).....: 6 (6% of 100)
Local Blocks Used......: 5
Local Blocks Freed.....: 1
-------------------- End of LCTs Statistics -------------------
See the UniBasic Commands Reference for additional information about the parameters of the lstt
syntax.

sbcs and shared memory

sbcs creates structures in shared memory as needed for storing active globally cataloged UniBasic
programs. The limits for structures that are created by sbcs are different from those created for smm.
The following table describes two udtconfig file 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 UNIX
versions, the kernel parameter shmseg constrains sbcs to 10
segments.)
MAX_OBJ_SIZE Maximum size, in bytes, of object code files that sbcs can load
into shared memory. sbcs loads object code files larger than
this size into the address space of the user instead of shared
memory.

Self-created segments
A UniData process can attach a segment of shared memory larger than a standard global page. If a
variable is larger than the size of a global page, smm creates a special segment in shared memory.

62
 UniData and the UNIX kernel (UNIX only)

These “self-created” segments, also called “indirect” segments, are attached to the requesting udt
process.
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 single
variable.
▪ Reading a large array as a single variable.
smm creates a segment large enough to hold the variable. smm determines the maximum size by the
UNIX kernel parameter shmmax. The self-created segment is counted as a global page used by the
UniData process that created the segment.

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

UniData and the UNIX kernel (UNIX only)

When optimizing configuration parameters for shared memory, certain changes might impact
parameters in the UNIX kernel. Before you implement configuration changes, you should explore the
impact of these changes on your kernel parameters, and determine if the kernel parameters should be
changed.
The following table describes relationships between UNIX kernel parameters and UniData.

UNIX kernel Relationship to UniData

Maximum size of shared memory Must be larger than CTL, and larger than a shared memory
segment (shmmax) segment created by smm or sbcs. If this kernel parameter
is too low, UniData might not start. If you change the
configuration parameters that control the size of memory
structures, you might need to adjust this kernel parameter.
Maximum number of shared memory Must be greater than SHM_GNTBLS, the number of GCTs in
segments (shmmni) the control table. This parameter should be set high enough
to accommodate all the GCTs, plus one segment for CTL,
and one or more (up to 20) for sbcs.
Maximum number of shared memory Must be greater than SHM_LMINENTS, the number of entries
segments per process (shmseg) available in the MI table for each LCT, which is the number
of 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 for
RFS processing. When you start UniData with RFS, UniData reserves this buffer, and it is therefore
not available to smm or sbcs. For information about the system buffer, see Administering the
Recoverable File System.

63
Chapter 6: Configuring your UniData system
This section outlines configuration considerations that might be appropriate when you first
implement UniData or when you make major changes to your system. (Major changes include
adding or reconfiguring hardware, installing a new software application, or upgrading or re-licensing
UniData.)
This section does not present detailed information, but outlines the considerations and refers you to
sources of more information.

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

1. Identify disk requirements

Disk space and disk configuration are key factors that determine system performance.
2. Identify memory requirements
The initial estimates in the Installation Guide should allow you to install and run UniData with a
minimal configuration. However, memory requirements can be platform-dependent as well as
application dependent.
3. Verify version compatibilities
If you are considering major upgrades to your hardware or to your operating system version,
consult your Rocket Software account representative early in your planning process to determine
whether your current UniData version is supported by the hardware or software you are
considering.
4. Check/reset the UNIX kernel or Windows system-level parameters
Depending on your version of Windows or UNIX, you might not be able to modify kernel or
system-level parameters directly.
5. Check/reset UniData configuration parameters
The UniData udtconfig file contains a set of parameters that are given default values when you
install UniData.
6. Define peripherals within UniData
You need to define tape devices, printers, and line devices needed by UniData before they can be
accessed from UniData.
7. Create UniData accounts
When you implement UniData, you might need to create one or more UniData accounts for your
application.
8. Add UNIX and Windows users
Accessing UniData requires each user to have a login and password on your UNIX or Windows
system.
9. Set environment variables
A user who wants to access UniData must have two environment variables set: UDTHOME and
UDTBIN.
10. Review UniData security
Depending on your application, you might need to implement extra measures to ensure data
security and separation of duties.
11. Convert data files

64
 Identify disk requirements

Depending upon the nature of your system change, you might need to perform some conversion
of UniData hashed files.
12. Perform makeudt (UNIX only)
UniData provides the capability to invoke C functions from within UniBasic programs. It is
necessary to rebuild the UniData executable (the binary file udtbin/udt) whenever you want to
link in more C functions.
13. Review backup procedures
Special considerations are needed to back up UniData accounts.

Identify disk requirements

Disk space and disk configuration are key factors that determine system performance.
The initial estimates in the Installation Guide should allow you to install and run UniData. However,
we recommend that you evaluate your system, including your operating system, your hardware
configuration, and your application, to develop accurate disk space requirements. We offer the
following suggestions.
▪ Disk Requirements—Use the largest expected size for your data files to estimate how much disk
space you need. In certain applications, such as financial applications, the number of records
varies in a predictable way over time. Your system must have enough disk space to handle the
maximum number of records without difficulty.
▪ Disk I/O—For best results, configure your disk system so that access is balanced across all devices.
We suggest the following:
▫ Locate your /tmp (UNIX) or \TEMP (Windows) directory on a different physical device from
your data for improved performance.
▫ If your application uses more than one UniData account, locate the account directories on
separate devices to distribute load.
▫ If on UNIX, consider implementing a logical volume management protocol that includes disk
striping. Various products and utilities are available; consult with your hardware vendor for
recommendations. Striping, which allows you to create logical volumes that span physical
devices, can provide significant performance improvements by balancing the load on the
system.

Tip: If your application frequently accesses data files that are larger than 300 MB in size, we
strongly recommend striping.

Next topic: Identify memory requirements

Parent topic: Configuration procedure

Identify memory requirements

The initial estimates in the Installation Guide should allow you to install and run UniData with a
minimal configuration. However, memory requirements can be platform-dependent as well as
application dependent.
Estimate the memory that is required for the following components of your application:
▪ The control table list (CTL)
▪ The memory segments controlled by smm

65
Chapter 6: Configuring your UniData system

▪ The memory segments for sbcs

▪ If you use the Recoverable File System (RFS), the system buffer.
Refer to UniData and memory, on page 55 for information about estimating memory needs.

Next topic: Verify version compatibilities

Previous topic: Identify disk requirements
Parent topic: Configuration procedure

Verify version compatibilities

If you are considering major upgrades to your hardware or to your operating system version, consult
your Rocket Software account representative early in your planning process to determine whether
your current UniData version is supported by the hardware or software you are considering.
Next topic: Check/reset the UNIX kernel or Windows system-level parameters
Previous topic: Identify memory requirements
Parent topic: Configuration procedure

Check/reset the UNIX kernel or Windows system-level parameters

Depending on your version of Windows or UNIX, you might not be able to modify kernel or system-
level parameters directly.
When you first implement UniData, the following categories of parameters might need 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 per
process. For more information, see UniData and memory, on page 55 and Managing memory (UNIX
only), on page 285.
▪ Files and Users — Review parameters that define the maximum number of open files and file locks
supported system-wide, the maximum number of files per user process, and the maximum number
of user processes the system can support at one time.
▪ ipc Facilities — Review parameters that define the number and size of message queues your
system supports, the number of semaphore sets and semaphores your system supports, and the
number of semaphore undo structures that are supported. For more information, see UniData and
UNIX devices (UNIX only), on page 342 and Managing ipc facilities (UNIX only), on page 300.
UniData requires that certain kernel parameters have adequate settings in order for UniData to
accommodate the full number of licensed users. The following table lists some recommended kernel
parameters.

Description HPUX Solaris Recommended value

Semaphore semmnu semmnu NUSERS * 3.25
undo
structures
system wide
Shared shmmni shmmni Must be greater than SHM_GNTBLS
memory
max-shm-ids
segments
(Solaris 10+)

66
 Check/reset UniData configuration parameters

Description HPUX Solaris Recommended value

Number of msgmni msgmni Non-RFS: 10 + the number of concurrent journal
message processes if you are using UniData Journaling.
max-msg-ids
queues
(Solaris 10+) RFS: ((number of authorized users / 4) * 2) + 10
Semaphore semmni semmni For UniData 8.1+ and later:
identifiers
max-sem-ids Standard Systems:
(Solaris 10+) semmni >= ((NUSERS / NSEM_PSET) * 2) + 5
Systems with Replication:
semmni >= ((NUSERS / NSEM_PSET) * 3) + 10
For UniData 7.3.x and prior:
Standard Systems: semmni >= (NUSERS /
NSEM_PSET) + 5
Systems with Replication:
semmni >= ((NUSERS / NSEM_PSET) * 2) + 10
Number of semmns semmns semmni * (NSEM_PSET or semmsl)
semaphores
available Note: NSEM_PSET in these formulas are from the
system wide udtconfig file, and the corresponding kernel
parameter is semmsl.

Warning: If semmni or semmns is not tuned high enough, the error in the smm.errlog file will be
similar to the following:
Exit: smm: cannot allocate semaphore for udtno xx errno 28. Exit:
SMM can’t setup Control Table List
When this message displays, UniData will fail to start.

Note: On Red Hat Linux, running telnet in SSL mode will not work when SELINUX is enabled.

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

Next topic: Check/reset UniData configuration parameters

Previous topic: Verify version compatibilities
Parent topic: Configuration procedure

Check/reset UniData configuration parameters

The UniData udtconfig file contains a set of parameters that are given default values when you
install UniData.
When you start a UniData session, UniData sets UNIX environment variables for each value in the
filepath file.

67
Chapter 6: Configuring your UniData system

Note: The udtconfig file is always located in udtbin\include on Windows or /usr/ud##/

include on UNIX, where ## is the release number of UniData. For example, the udtconfig file
for Release 8.1 is located 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 UniData
environment. Most udtconfig parameters can be adjusted for your environment, but some
parameters should not be changed. Refer to UniData configuration parameters, on page 381 for
detailed information about each udtconfig parameter.
On Windows, you must log on as an Administrator to modify udtconfig parameters.
On UNIX, 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=1
SYS_PV=3

# 1.2 Changeable parameters

NFILES=1019
NUSERS=40
WRITE_TO_CONSOLE=0
TMP=/tmp/
NVLMARK=
FCNTL_ON=0
TOGGLE_NAP_TIME=2
TOGGLE_NAP_TIME_NS=200000
NULL_FLAG=0
QUOTED_IDENTIFIER=1
N_FILESYS=200
N_GLM_GLOBAL_BUCKET=101
N_GLM_SELF_BUCKET=23
GLM_MEM_SEGSZ=4194304
BGINPUTTIMEOUT=0
LB_FLAG=1
USE_DF=0
NFA_COMPAT_FLAG=0
UDT_SPLIT_POLICY=0
DEFAULT_HASH_TYPE=3
SINGLE_SAVEDLIST=1
TANDEM_FLAG=1
FIPS_MODE=0
TRIGGER_ADMIN=

# 1.3 I18N related parameter

UDT_LANGGRP=255/192/129
ZERO_CHAR=131

#
# Section 2 Non-RFS related parameters
#
# 2.1 Shared memory related parameters
SBCS_SHM_SIZE=1048576

68
 Check/reset UniData configuration parameters

SHM_MAX_SIZE=2147467264
SHM_ATT_ADD=0
SHM_LBA=268435456
SHM_MIN_NATT=4
SHM_GNTBLS=75
SHM_GNPAGES=8
SHM_GPAGESZ=1024
SHM_LPINENTS=10
SHM_LMINENTS=128
SHM_LCINENTS=254
SHM_LPAGESZ=8
SHM_FREEPCT=25
SHM_NFREES=1

# 2.2 Size limitation parameters

AVG_TUPLE_LEN=4
EXPBLKSIZE=64
MAX_OBJ_SIZE=307200
MIN_MEMORY_TEMP=256
STATIC_GROWTH_WARN_TABLE_SIZE=256
STATIC_GROWTH_WARN_SIZE=1610612736
STATIC_GROWTH_WARN_INTERVAL=300

# 2.3 Dynamic file related parameters

GRP_FREE_BLK=5
SHM_FIL_CNT=2048
SPLIT_LOAD=60
MERGE_LOAD=40
KEYDATA_SPLIT_LOAD=95
KEYDATA_MERGE_LOAD=40
MAX_FLENGTH=1073740800
PART_TBL=/disk1/srcman/alpha/ud82_111222_6069/parttbl
WHOLEFILE_SPLIT_LOAD=75
WHOLEFILE_MERGE_LOAD=40
DEFAULT_SPLIT_STYLE=3

# 2.4 NFA/Telnet service related parameter

EFS_LCKTIME=0
TSTIMEOUT=60
NFA_CONVERT_CHAR=0

# 2.5 Journal related parameters

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

#2.7 UniBasic related parameters

MAX_CAPT_LEVEL=2
MAX_RETN_LEVEL=2
COMPACTOR_POLICY=1
VARMEM_PCT=50

# 2.8 Number of semaphores per semaphore set

NSEM_PSET=8

# 2.9 Index related parameters

SETINDEX_BUFFER_KEYS=0
SETINDEX_VALIDATE_KEY=0

# 2.10 UPL/MGLM parameter

MGLM_BUCKET_SIZE=50
UPL_LOGGING=0

69
Chapter 6: Configuring your UniData system

# 2.11 Printer _HOLD_ file related parameters

MAX_NEXT_HOLD_DIGITS=4
CHECK_HOLD_EXIST=0

#
# Section 3 RFS related parameters
# These parameters are only used for RFS which is turned by
# setting SB_FLAG to a positive value.
#
# 3.1 RFS flag
SB_FLAG=1

# 3.2 File related parameters

BPF_NFILES=80
N_PARTFILE=2000

# 3.3 AFT related parameters

N_AFT=1000
N_AFT_SECTION=1
N_AFT_BUCKET=101
N_AFT_MLF_BUCKET=23
N_TMAFT_BUCKET=19

# 3.4 Archive related parameters

ARCH_FLAG=0
N_ARCH=2
ARCHIVE_TO_TAPE=0
ARCH_WRITE_SZ=0

# 3.5 System buffer parameters

N_BIG=233
N_PUT=8192
SB_PAGE_SZ=1

# 3.6 TM message queue related parameters

N_PGQ=10
N_TMQ=10

# 3.7 After/before image related parameters

N_AIMG=2
N_BIMG=2
AIMG_BUFSZ=102400
BIMG_BUFSZ=102400
AIMG_MIN_BLKS=10
BIMG_MIN_BLKS=10
AIMG_FLUSH_BLKS=2
BIMG_FLUSH_BLKS=2
LOG_OVRFLO=/disk2/logs/udrfs/ud82/log_overflow_dir

# 3.8 Flushing interval related parameters

CHKPNT_TIME=300
GRPCMT_TIME=5

# 3.9 Sync Daemon related parameters

N_SYNC=0
SYNC_TIME=0

# 3.10 dump file control

RFS_DUMP_DIR=
RFS_DUMP_HISTORY=1

#
# Section 4 Misc parameters

70
 Check/reset UniData configuration parameters

#
SORT_FLD_DELIMITER=127

#
# Section 6 Century Pivot Date
#
CENTURY_PIVOT=1930

#
# Section 7 Replication parameters
#
REP_FLAG=1
TCA_SIZE=2048
MAX_LRF_FILESIZE=1073741824
N_REP_OPEN_FILE=8
MAX_REP_DISTRIB=1
REP_CP_TIMEOUT=300
MAX_REP_SHMSZ=2147467264
REP_LOG_PATH=/disk2/logs/udreplication/ud82
UDR_CONVERT_CHAR=1
REP_DISABLE_DISK_PCT=95
TP_COMMIT_LOGGING=0
REP_ASYNCHRONOUS_TP=0
FIELD_UPDATE_THRESHOLD=0

#
# Euro data handling symbols
#
CONVERT_EURO=0
SYSTEM_EURO=164
TERM_EURO=164

#
# Communication and Security Section
#
HTTP_DEFAULT_VERSION=1.1
SSL_PROTOCOLS=TLSv1,TLSv1.1,TLSv1.2
SSL_OPTIONS=NO_TLS_FALLBACK_SCSV

#
# Audit logging Section
#
AUDIT_LOG_LOC=/disk2/logs/udaudit/ud82
AUDIT_LOG_MAX=1
AUDIT_LOG_ENC=0
AUDIT_LOG_TYPE=2
AUDIT_SEQ_BUF_SZ=1024
AUDIT_SEQ_OUTBLK_SZ=4
AUDIT_SEQ_FILE_SZ=500000
AUDIT_SEQ_FILE_SWITCH=0
AUDIT_SEQ_SYNC_TIME=0
AUDIT_SEQ_SYNC_CNT=0
AUDIT_LOG_COMPRESS=0
AUDIT_LOG_START_DISABLED=0
AUDIT_LOG_MSG_LEVELS=INFO,WARNING,ERROR,CRITICAL

Next topic: Define peripherals within UniData

Previous topic: Check/reset the UNIX kernel or Windows system-level parameters
Parent topic: Configuration procedure

71
Chapter 6: Configuring your UniData system

Define peripherals within UniData

You need to define tape devices, printers, and line devices needed by UniData before they can be
accessed from UniData.
Before you define a device within UniData, make certain that it is properly installed and functioning
in your UNIX environment. Refer to your host operating system documentation for information about
setting up peripherals on your system.
Use the ECL SETTAPE, SETLINE, and SETPTR commands to define your peripherals to UniData.
For more information, see UniData and UNIX spoolers, on page 198, Managing printers in UniData, on
page 183, and Accessing UNIX devices (UNIX only), on page 277.

Next topic: Create UniData accounts

Previous topic: Check/reset UniData configuration parameters
Parent topic: Configuration procedure

Create UniData accounts

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

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

Use the UNIX or Windows mkdir command and the UniData system-level newacct command to
create UniData accounts. Refer to your host operating system documentation for information about
the mkdir command, and see Managing UniData accounts, on page 89 for information about the
newacct command.

Next topic: Add UNIX and Windows users

Previous topic: Define peripherals within UniData
Parent topic: Configuration procedure

Add UNIX and Windows users

Accessing UniData requires each user to have a login and password on your UNIX or Windows system.
We recommend you create a separate UNIX login (UNIX account) or Windows account for each UniData
user. For detailed information about creating UNIX or Windows accounts, see your host operating
system documentation. For UniData-specific information, see Managing UniData security, on page
95.

Next topic: Set environment variables

Previous topic: Create UniData accounts
Parent topic: Configuration procedure

72
 Set environment variables

Set environment variables

A user who wants to access UniData must have two environment variables set: UDTHOME and
UDTBIN.
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 who
wants to access UniData using a different UDTHOME and UDTBIN than those defined in the Registry
must set these two environment variables. The settings that you assign for these variables depend on
whether you performed a basic or an advanced UniData installation.

Note: See the Installation Guide for information about installation types.

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

Next topic: Review UniData security

Previous topic: Add UNIX and Windows users
Parent topic: Configuration procedure

Setting UDTHOME and UDTBIN

Each user needs UDTHOME and UDTBIN set to access UniData.
On UNIX, you can add commands to set these environment variables to each user’s .login or
.profile, or a user can set them at the UNIX prompt. On Windows, if the user is accessing UniData
with a different UDTHOME or UDTBIN than defined in the Registry, you must add these commands to
the environment variables.

If you are using the C shell on UNIX, 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 on UNIX, use these commands:
UDTHOME=/directory-name;export UDTHOME
UDTBIN=/directory-name;export UDTBIN
Use the following commands to set these variables on Windows:
set UDTHOME \directory-name
set UDTBIN \directory-name
set PATH \directory-name
You can also set environment variables on Windows from the System window. Open the System
Window form the Control Panel. Click the Advanced system settings, then click Environment
Variables.
To add a new environment variable, click New. To change the value of an environment variable,
highlight the variable you want to change, then click Edit. Enter the name of the environment variable
you want to establish or change in the Variable field. Enter the setting for the environment variable in
the Value field. Click OK to set the variable.

73
Chapter 6: Configuring your UniData system

Setting PATH
On UNIX, 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 396 lists an additional set of variables that are
significant for UniData users. On UNIX, these environment variables can be set in a user’s login script
or defined from a UNIX prompt before you enter UniData. On Windows, these can be set in the same
manner as the environment variables in the previous example before entering UniData.

Note: While you are in a UniData session, you cannot change environment variables for that
session. Even if you run setenv, for instance, from the ! prompt, the new setting affects only
processes started from the ! prompt. The new settings do not affect the current UniData session.

Review UniData security

Depending on your application, you might need to implement extra measures to ensure data security
and separation of duties.
Review your application, and implement any or all of the following:
▪ Default Permissions—Modify the default permissions for udthome and its contents that were set
when you installed UniData.
▪ Users and domains—On Windows, assign UniData users to separate domains, and set permissions
on your database so that each group of users has access to the data they need.
▪ Users and groups—On UNIX, assign UniData users to separate UNIX groups, and set permissions
on your database so that each group of users has access to the data they need.
▪ VOC file—Customize your VOC file to limit access to powerful commands.
▪ Remote entries—Use remote pointers to files and commands to allow more fine-grained
protection.
▪ SQL Privileges—For SQL access, use the UniData SQL GRANT and UniData SQL REVOKE
commands to customize access to tables.
▪ Query Privileges—For UniQuery access, use the QUERY.PRIVILEGE file.
For more information, see Managing UniData security, on page 95.

Next topic: Convert data files

Previous topic: Set environment variables
Parent topic: Configuration procedure

74
 Convert data files

Convert data files

Depending upon the nature of your system change, you might need to perform some conversion of
UniData hashed files.
Consider the following:
▪ Recoverable files—If you are implementing UniData’s Recoverable File System, you need to create
recoverable files and/or convert existing hashed files to recoverable files. See Administering the
Recoverable File System for detailed information.
▪ Schema—If you are implementing UniData ODBC or UniOLEDB, you might need to make UniData
files accessible to UniData SQL, and you might also need to utilize the Schema API to incorporate
ODBC compliance for field and attribute names. See Using VSG and the Schema API for detailed
information.
▪ File characteristics—UniData also offers you the capability to convert files from static to dynamic,
change file characteristics such as block size and modulo, change hashing algorithm for a static
file, and change file format between high-byte and low-byte formats. For more information, see
Managing UniData files, on page 117 and the UniData Commands Reference.

Next topic: Perform makeudt (UNIX only)

Previous topic: Review UniData security
Parent topic: Configuration procedure

Perform makeudt (UNIX only)

UniData provides the capability to invoke C functions from within UniBasic programs. It is necessary
to rebuild the UniData executable (the binary file udtbin/udt) whenever you want to link in more C
functions.
Next topic: Review backup procedures
Previous topic: Convert data files
Parent topic: Configuration procedure

Review backup procedures

Special considerations are needed to back up UniData accounts.
Make certain your backup procedures have the following capabilities:
▪ Subdirectories—Your backup procedure should be able to back up at least three levels of
subdirectories to support UniData MULTIDIR and MULTIFILE files.
▪ Symbolic links—Your backup procedure should be able to follow UNIX symbolic links to support
large dynamic files.
▪ Backing up selected files—Your backup procedure should allow you to input a list of files to back
up to support full backups of UniData accounts. Simply backing up the directory that contains
the VOC file might be insufficient, since data files might not be located in the same UNIX directory
as the VOC file. The ECL SETFILE command creates VOC entries with pointers to files in other
locations. However, backup utilities do not follow these SETFILE pointers like they do UNIX
symbolic links. To create a complete backup of an account, make sure you back up and verify each
physical file that is associated with the account.

Previous topic: Perform makeudt (UNIX only)

75
Chapter 6: Configuring your UniData system

Parent topic: Configuration procedure

76
Chapter 7: Starting, stopping, and pausing
UniData
This section describes procedures for normal startup and shutdown of UniData, and also describes
commands 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 operation
Use the UniData startud and stopud commands, respectively, for normal startup and shutdown.
These commands start and stop the sbcs, cleanupd, and smm daemons or services in the correct
order.

Note: You must be logged on as an Administrator on Windows or as root on UNIX to run startud
or stopud. Make sure you have defined the environment variables UDTHOME and UDTBIN, and
make sure your PATH includes udtbin. If you are running more than one version of UniData,
make sure that these environment variables are set for the version of UniData you want to start
and stop.

UniData log files

startud makes entries in the log files (smm.log, sbcs.log, and cleanupd.log) that identify
the system resources that are used by the daemons or services. If you are using RFS, startud and
stopud also start the sm daemon and record information in its sm.log.
The following example shows a sample sbcs.log for UNIX:
% pg sbcs.log
The next example shows a sample smm.log:
# pg sbcs.log
SBCS version: 7.3

BEGSMALL = 1 BEGMED = 5 BEGLARGE = 20 BEGHUGE = 45

Begsmall = 0 Begmed = 163 Beglarge = 490 Beghuge = 981
Beginning of emergency area = 1638, size = 410
Recover = 1 Debugmode = 0

Shm Attach Address: 0

Shm Max. Size.....: 1048576
SBCS 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
SMM version: 7.3

77
Chapter 7: Starting, stopping, and pausing UniData

Number of users......: 32
SMM checking interval: 60 seconds
SMM 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 seconds
CLEANUPD minimum interval: 10 seconds
CLEANUPD process id.....: 880

The following example is a sample sbcs.log file for Windows:

%# type sbcs.log
SBCS version: 7.3

BEGSMALL = 1 BEGMED = 5 BEGLARGE = 20 BEGHUGE = 45

Begsmall = 0 Begmed = 163 Beglarge = 490 Beghuge = 981
Beginning of emergency area = 1638, size = 410
Recover = 1 Debugmode = 0

Shm Attach Address: 0

Shm Max. Size.....: 1048576
SBCS 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 for Windows:
% type smm.log
SMM version: 7.3

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

IPC facilities:
q - 0 (request queue)
q - 1 (reply queue)
m - 1094717696 (ctl)
m - -1795163136 (glm)

78
 Starting UniData with startud

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 for Windows:
% pg cleanupd.log

CLEANUPD daemon:
CLEANUPD checking interval: 20 seconds
CLEANUPD minimum interval: 10 seconds
CLEANUPD process id.....: 880

Starting UniData with startud

The following screens show the normal output from the startud command.
Windows example:
C:\UniData82\Bin>startud
Wait 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 service with
a setting to automatically start when you boot your computer. You can change this setting to
manually start the UniData Database Service 8.2.1. See your host operating system documentation
for detailed information about starting and stopping services.

UNIX example:
# startud
Using UDTBIN=/disk1/ud82/bin
All 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
UniData R8.2.1 has been started.
#

79
Chapter 7: Starting, stopping, and pausing UniData

Note: You can configure your system so that UniData starts automatically when you boot your
computer. You need to add or modify a startup script to accomplish this. Refer to your host
operating 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 been
damaged, UniData failure recovery will not complete successfully.

Stopping UniData with stopud

For normal operation, use the stopud command with no options. You need to make sure users are
logged out of UniData before you run this command.
The following screens show the expected response to the stopud command.
Windows example:
C:\UniData82\Bin>stopud
DBpause is OFF.
Stop Unidata Service now ...
CLEANUPD stopped successfully.
The Unidata Service has been stopped successfully.
#
UNIX example:
# stopud
Using UDTBIN=/disk1/ud82/bin
SM stopped successfully.
CLEANUPD stopped successfully.
SBCS stopped successfully.
SMM stopped successfully.
Unirpcd has already been stopped
Unidata R8.2.1 has been shut down.
#

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

The dbpause command

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

Syntax
dbpause -c
You must log on as an Administrator on Windows or as root on UNIX to issue the dbpause command.

80
 The dbpause command

Note: Windows only.

When you add users who are not administrators to the group name located in the
UDTADMIN_GROUP registry key, those users can perform UniData administrator commands.
For more information about the UDTADMIN_GROUP registry key and the available commands, see
UDTADMIN_GROUP registry key, on page 177.

When you specify the -c option, UniData checks to see if any process would prevent dbpause from
completing and displays details about those processes that would prevent completion without
actually pausing the database.
On UNIX, UniData starts a new archive file when you resume processing.
dbpause blocks most updates to the database that are made within UniData. UniData completes
writes or transactions in process when you issue the dbpause command before dbpause takes
effect. Updates are blocked until the system administrator runs the dbresume command.
UniData does not block UNIX commands, such as cp or mv. UniData does not block Windows system-
level commands, such as COPY or MOVE. In addition, UniData does not block updates to the _HOLD_
file and the _PH_ file, and does not interrupt report printing. If you run dbpause while you are
running RFS, UniData forces a checkpoint, flushes the after image logs to the archive files (if archiving
is enabled), and marks the next available logical sequence number in the archive file for use after the
backup. UniData displays this information on the screen from which you ran dbpause, and writes it
to udtbin/sm.log.

Note: Some UniData system-level commands, such as cntl_install, require that UniData not
be running. These commands do not run successfully with dbpause in effect. You cannot stop
UniData 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 defined
in the login paragraph that is paused)

81
Chapter 7: Starting, stopping, and pausing UniData

▪ MIN.MEMORY
▪ SET.DEC, SET.MONEY, SET.THOUS, SET.WIDEZERO
▪ SETOSPRINTER, SETPTR, SP.ASSIGN, SP.EDIT
▪ TERM
▪ WHAT
The following example illustrates the output from the dbpause command on UNIX:
# dbpause
DBpause successful.
#
If you are running RFS, it is important that you synchronize your archive files with your backup files
when 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 of
dbpause.

Syntax
dbpause_status
The following example illustrates the output from the dbpause_status command when dbpause
is in effect on UNIX:
% dbpause_status
DBpause is ON.
%

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

Syntax
dbresume
You must log on as an Administrator on Windows or root on UNIX to issue the dbresume command.

Note: Windows only.

When you add users who are not administrators to the group name located in the
UDTADMIN_GROUP registry key, those users can perform UniData administrator commands.
For more information about the UDTADMIN_GROUP registry key and the available commands, see
UDTADMIN_GROUP registry key, on page 177.

The following screen illustrates the output from the dbresume command on UNIX:
# dbresume
DBresume successful.

82
 Additional commands

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

UniData command Function

listuser Lists all current UniData users.
showud UNIX only. 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. On UNIX, stopudt runs the
UNIX kill -15 command.
deleteuser On Windows, forces a user out of UniData and removes the user’s entry
from the internal tables.
On UNIX, deleteuser first issues the UNIX kill -15 command. If kill -15
is not successful after 5 seconds, deleteuser issues the UNIX 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 those that are
used by UniData daemons or services.
udipcrm UNIX only. Removes all IPC facilities that are associated with UniData
(queues, shared memory segments, semaphores). This command shuts
UniData down and may corrupt files; use the command only if a daemon
has been killed and has left IPC structures behind.
stopud -f Forces all UniData daemons or services to stop regardless of system
activity.

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

Listing processes with showud (UNIX only)

The showud command lists all UniData processes that are currently running. The following screen
shows an example of showud output:
# showud
UID PID TIME COMMAND
root 20376 0:00 /disk1/ud82/bin/aimglog 0 14553
root 20377 0:00 /disk1/ud82/bin/aimglog 1 14553
root 20378 0:00 /disk1/ud82/bin/bimglog 2 14553
root 20379 0:00 /disk1/ud82/bin/bimglog 3 14553
root 20367 0:00 /disk1/ud82/bin/cleanupd -m 10 -t 20
root 20373 0:00 /disk1/ud82/bin/cm 14553
root 20363 0:00 /disk1/ud82/bin/sbcs -r
root 20372 0:00 /disk1/ud82/bin/sm 60 30482
root 20356 0:00 /disk1/ud82/bin/smm -t 60

83
Chapter 7: Starting, stopping, and pausing UniData

root 20393 0:00 /disk1/unishared/unirpc/unirpcd

#

Stopping a user process with stopudt

The stopudt command logs out a user, as opposed to stopud, which stops UniData.

Syntax
stopudt pid
The argument pid is a system-level process ID. On Windows, this is found in the USRNBR column of
listuser command.
If you need to log out a user you cannot reach, or to clear a hung user process, use this command. The
following screens show the action of stopudt.
UNIX example:

Windows example:

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

84
 Stopping a user process with deleteuser

Note: The argument for stopudt is the process ID (pid) associated with the udt process you
are removing. On Windows, use the UniData listuser command, as shown in the preceding
example. The pid is under the USRNBR column. If you use the UNIX ps command to get the
number, the pid is clearly labeled. If you use the UniData listuser command, as shown in the
above screen, the pid is called USRNBR.

Stopping a user process with deleteuser

The deleteuser commands varies slightly between Windows and UNIX.
On Windows, the deleteuser command first tries to kill the udt process by sending UniData an
internal signal equivalent to the UNIX kill -15 command. If this signal is unsuccessful after five seconds,
it uses the Win32 API Terminate Process to kill that process.
On UNIX, the deleteuser command first tries to kill the user process with the UNIX kill -15
command. If the kill -15 is unsuccessful after five seconds, a kill -9 is issued.

Syntax
deleteuser pid
The argument pid is the UNIX process ID.

Warning: Because deleteuser can execute the Terminate Process on Windows, or issue the
UNIX kill -9 command, it is important that you verify the pid carefully.

The following screens show an example of the deleteuser command.

Windows example:

UNIX example:

85
Chapter 7: Starting, stopping, and pausing UniData

Note: You must log on as an Administrator on Windows or as root on UNIX to execute

deleteuser.

Displaying IPC facilities with ipcstat (Windows only)

The ipcstat command displays a list of all IPC facilities (message queues, semaphores, and
shared memory segments) in use on a system, and identifies those facilities that are used by UniData
processes. You do not need to log on as as an Administrator on Windows or as root on UNIX to execute
ipcstat.

Syntax
ipcstat [-q] [-m] [-s] [-g] [-b] [-c] [-o] [-p] [-t] [-a] [-n]
The following screen shows an example of ipcstat output:
UNIX example:

IPC status from /dev/mem as of Mon Feb 27 02:12:48 MST 2017

T ID KEY MODE OWNER GROUP
Shared Memory:
m 1048576 0x45047056 --rw-rw-rw- root system -> unknown
m 2097153 0x61003007 --rw------- pconsole system -> unknown
m 1048578 0xffffffff D-rw------- pconsole system -> unknown
m 3 0xffffffff --rw-rw-rw- root system -> unknown
m 4 0xffffffff --rw-rw-rw- root system -> unknown
m 5 0xffffffff --rw-r--r-- root system -> unknown
m 6 0x780007ad --rw-rw-rw- root system -> unknown
m 7 0x78000100 --rw-rw-rw- root system -> unknown
m 8 0x78100100 --rw-rw-rw- root system -> unknown
m 9 0x7800020a --rw-rw-rw- root system -> unknown
m 10 0x0d000c13 --rw-rw---- root system -> unknown
m 1048587 0x4503707c --rw-rw-rw- root system -> unknown
m 1048588 0xffffffff --rw-rw-rw- root system -> unknown
m 1048589 0xffffffff --rw-rw-rw- root system -> unknown
m 1048590 0xffffffff --rw-r--r-- root system -> unknown
m 35651600 0xffffffff --rw-rw-rw- root system -> smm R8.2 (glm)
m 31457297 0xffffffff --rw-rw-rw- root system -> sm R8.2 (sysbuf)
m 57671698 0xffffffff --rw-r--r-- root system -> sbcs R8.2

86
 Removing IPC structures with udipcrm (UNIX only)

m 32505875 0xacecb100 --rw-rw-rw- root system -> unknown

m 41943061 0x6503c13d --rw-rw-rw- root system -> sm R8.2 (ctl)
m 93323286 0xffffffff --rw-rw-rw- root system -> smm R8.2 (shmbuf)
m 36700188 0xdce08201 --rw-rw-rw- root system -> udaudd R8.2 (mctrl)
m 36700194 0xffffffff --rw-rw-rw- root system -> unknown
m 66060323 0x4503c13d --rw-rw-rw- root system -> smm R8.2 (ctl)

Windows example:

c:\u2\ud82> bin\ipcstat -m
T ID SIZE CPID
m UDShmem-Private--1124074496-2-15-0-16383-0 4194304 15248
->smm (ctl)
m UDShmem-Private--1124074495-2-15-0-16383-1 361392 15248
->smm (msg)
m UDShmem-Private--1124074494-2-15-0-16383-2 67108864 15248
->smm (shmbuf)
m UDShmem-Private--1124074496-2-15-0-16383-0 4194304 15248
->smm (glm)
m UDShmem-Private--1124075520-2-15-0-16382-0 ->sbcs
m UDShmem-Dynamic--589266431-3-484475393 134261760 13012 ->udaudd (mctrl)

c:\u2\ud82>

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

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

Removing IPC structures with udipcrm (UNIX only)

The udipcrm command uses the UNIX ipcrm command to remove any and all IPC facilities
associated with any UniData process. After an abnormal shutdown, you might be unable to start
UniData because some IPC facilities did not stop cleanly. You can use either the UNIX ipcrm
command or udipcrm to remove them.

Syntax
udipcrm
The udipcrm command is related to the ipcstat command. ipcstat lists all IPC facilities
currently in use on a system, and identifies which ones are used by UniData processes. udipcrm only
removes the ones associated with UniData.

Warning: Do not use udipcrm to shut down UniData. Use this command only 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 ipcstat
to identify IPC facilities that did not stop normally. See Managing ipc facilities (UNIX only), on page
300 for more information.

Stopping UniData with stopud -f

This command stops all daemons or services and UniData processes regardless of activity on the
system. Use this only if your system is hung and stopud fails to work.

87
Chapter 7: Starting, stopping, and pausing UniData

Syntax
stopud -f
The following screen shows the expected output from stopud -f on UNIX:
# stopud -f
Using 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]

y
SM stopped successfully.
CLEANUPD stopped successfully.
SBCS stopped successfully.
SMM stopped successfully.
Unirpcd has already been stopped
Unidata R8.2.1 has been shut down.
#
On Windows:
C:\UniData82\Bin>stopud -f
DBpause is OFF.
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]

y
Stop Unidata Service now ...
CLEANUPD stopped successfully.
The Unidata Service has been stopped successfully.
You must log on as an Administrator on Windows or as root on UNIX to run stopud -f.

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

88
Chapter 8: Managing UniData accounts
This section describes UniData accounts and describes procedures that are used to create, save, and
clear the accounts.

About UniData accounts

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

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

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

Note: A UNIX or Windows account typically means a login ID, its associated password, and its
default directory. No direct relationship exists between UniData accounts and UNIX or Windows
accounts (logins). Many UNIX or Windows users can access any UniData account. A UNIX or
Windows user’s default directory does not have to be (and usually is not) a UniData account.

Creating a UniData account

Complete the following steps to create a UniData account:
1. Make sure the environment variable UDTHOME is set.
2. Use the mkdir command to create the directory that will house the account. The name of the
UniData account directory can be in uppercase, lowercase, or mixed uppercase and lowercase.
3. Make the new directory your working directory. You can change to the directory with the MS-DOS
cd command.
4. Use the UniData newacct command to create the VOC and other UniData-specific files in the
directory.

Note: You do not need to log on as as an Administrator on Windows or as root on UNIX

to create a UniData account. However, on Windows, you must have Change access in the
account directory. On UNIX, the newacct command prompts you for a user and group for
your account. If you are logged on as root, UniData uses this information to set ownership and
permissions for the account. If you are not logged on as root, UniData ignores your responses
and uses your current logon and group ID.

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.

89
Chapter 8: Managing UniData accounts

Subdirectory Description
SAVEDLISTSL Windows only. Used to store temporary information for BY.EXP
sorts. UniData automatically creates and deletes the contents of this
subdirectory.
savedlists UNIX only. Used to store temporary information for BY.EXP sorts. UniData
automatically creates and deletes the contents of this subdirectory.
_HOLD_ Used to store print files.
_PH_ Used to store output from background processes (created by the UniData
ECL PHANTOM command) and captured terminal I/O (created by the
UniData ECL COMO command).
_EDAXMAP_ Windows only. Used to store EDA mapping files.
_XML_ Windows only. Used to store XML mapping files.
UD_SQLTABLES Windows only. 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_ UNIX only. Used to store UReport report definitions.
_SCREEN_ UNIX only. Used to store UEntry screen definitions.
__V__VIEW Used to store UniData SQL view specifications.
privilege Windows only. 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 UniBasic
and UniData SQL

UNIX example
The following screens illustrate how to create an account from UNIX, how to enter UniData in the new
account, and how to use the UniData LS command to list the contents of the account:
# mkdir ACCOUNT
# cd ACCOUNT
# newacct
% newacct

90
 Creating a UniData account

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 run
newacct, 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 created
Creating file D_SAVEDLISTS modulo /1
Added "@ID", the default record for UniData to D_SAVEDLISTS.
Creating file D_savedlists modulo /1
Added "@ID", the default record for UniData to D_savedlists.
Creating file D__PH_ modulo /1
Added "@ID", the default record for UniData to D__PH_.
Creating file D__HOLD_ modulo /1
Added "@ID", the default record for UniData to D__HOLD_.
Creating file D_BP modulo /1
Added "@ID", the default record for UniData to D_BP.
Creating file D_CTLG modulo /1
Added "@ID", the default record for UniData to D_CTLG.
D__REPORT_ file created
Create file _REPORT_(&report&), modulo/17
D__SCREEN_ file created
Create file _SCREEN_, modulo/17
D_MENUFILE file created
Create file MENUFILE, modulo/2
D___V__VIEW file created
Create file __V__VIEW, modulo/11
The next example shows output from udt and LS:
% udt
UniData Release 8.2.1 Build: (6069)
© Rocket Software, Inc. 1985-2015.
All rights reserved.
Current UniData home is /disk1/ud82/.
Current working directory is /disk1/ud82/demo.
:

Windows example
The following three screens illustrate how to create a UniData account. In the examples, the new
account is names ACCOUNT, and is located in the UniData directory:
C:\U2\ud82>mkdir ACCOUNT
C:\U2\ud82>cd ACCOUNT
C:\U2\ud82\ACCOUNT>dir
Volume in drive C has no label.
Volume Serial Number is 5CAF-C1C1
Directory of C:\U2\ud82\ACCOUNT
12/20/2011 02:08 PM <DIR>.
12/20/2011 02:08 PM <DIR>..
0 File(s) 0 bytes

91
Chapter 8: Managing UniData accounts

2 Dir(s) 209,704,177,664 bytes free

C:\U2\ud82\ACCOUNT>
The example illustrates executing the newacct command:
C:\U2\ud82\ACCOUNT>\u2\ud82\bin\newacct
The 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 to
continue.
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 VOC
file located in the sys subdirectory of your UniData home directory.

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

Saving and restoring accounts (UNIX only)

UniData includes two commands that are specifically designed for backing up and restoring UniData
accounts.
These commands are described in the following table.

UniData command Description

ACCT.SAVE Saves a current UNIX directory and its subdirectories to tape; uses UNIX
cpio utility, and writes only to the device defined as tape unit 0. (Use the
SETTAPE command to define a tape unit, and T.ATT to obtain exclusive use
of it within UniData.)
acctrestore [n] Restores a UniData account that was saved with ACCT.SAVE; uses
UNIX cpio utility; restricted to a single tape volume. Specify the tape
unit number n; the tape unit must be defined with SETTAPE. If you run
acctrestore while UniData is running, you may corrupt your data files.

92
 Deleting an account

Note: If you are using RFS, these commands do not function. If you attempt to run them, an error
message displays to the terminal.

Note: Use ACCT.SAVE and acctrestore carefully. These commands do not follow either
UniData pointers to other directories (set with the SETFILE command) or symbolic links for large
dynamic files. They are designed for use with small, self-contained UniData accounts.

Most UniData customer sites use the UNIX tar or cpio utilities, or commercial backup utilities, to
back up UniData files and accounts. Consult your host operating system documentation and vendor
documentation to determine the procedures to use at your site.

Deleting an account
No UniData command or utility exists that allows you to delete an entire account. If you need to delete
an account, complete the following steps.
1. Analyze the database and identify which files should be deleted. Take care not to delete shared
files that other UniData accounts might need.
2. Create and verify a full backup of at least the account you are going to delete.
3. Consider strategy. If the account is self-contained (that is, within one file system), you can use
the UNIX rm -r command or MS-DOS rmdir /s command to delete the account directory.
If the account has file pointers to other file systems, or dynamic files with part files on other file
systems, you may wish to use the ECL DELETE.FILE command to delete the files before you
remove the account directory. Use the ECL MAX.USER command to prevent inadvertent access
to the UniData account.

Warning: Be careful with the rmdir /s and rm -r commands. These commands remove
all files and subdirectories below the directory you specify. If you have nested accounts (a
UniData account within a UniData account) and you remove an account directory with these
commands, you could remove more than one account.

Clearing space in UniData accounts

The _PH_ and _HOLD_ subdirectories of each UniData account store output from background
processes and temporary print files, respectively. These subdirectories can become large, causing disk
space problems. The UniData ECL CLEAR.ACCOUNT command removes all files from either or both of
these subdirectories.

CLEAR.ACCOUNT
You must log on to the UniData account you are clearing. You do not need to log on as as an
Administrator on Windows or as root on UNIX; however, you must have write permission for the _PH_
and _HOLD_ directories.

Syntax
CLEAR.ACCOUNT

93
Chapter 8: Managing UniData accounts

When you issue the command, UniData prompts you for confirmation to clear each directory, as
shown in the following UNIX example.
:WHERE
/disk1/ud82/ACCOUNT
:CLEAR.ACCOUNT
Clear _PH_ directory(Y/N)? Y
Clear _HOLD_ directory(Y/N)? Y
Notice that the ECL WHERE command displays the current account.

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

94
Chapter 9: Managing UniData security
When you install UniData, UniData sets default permissions on system files and directories. After
installing UniData, you might want to customize some permissions.

Customizing a VOC file

Depending on your application, you might want to prevent users from executing certain ECL
commands. If you remove the entries corresponding to these commands from the VOC file in the
account, users logged on to that account will not be able to execute them.
When a user enters an ECL command, UniData searches the VOC file in the current account. If there is
no corresponding entry, UniData displays an error message instead of executing the command.
The following example shows the results of deleting a VOC entry:
LIST VOC WITH @ID = COPY 19:03:11 May 23 2011 1
VOC.......
COPY
1 record listed
:DELETE VOC COPY
'COPY' deleted.
:COPY FROM DICT INVENTORY TO DICT ORDERS ALL
Not a verb
COPY
The following table lists ECL commands that create or modify UniData files, or allow users to execute
UNIX system-level commands. You can consider removing some or all of these from the VOC files for
your accounts.

Command Description
! Escapes to a UNIX or MS-DOS 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.

95
Chapter 9: Managing UniData security

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

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

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

Customizing UniData
The UDT.OPTIONS command enables you to customize your UniData environment. UDT.OPTIONS
19 allows you to choose whether superusers (root access) can bypass security restrictions created
by removing entries from the VOC file. If UDT.OPTIONS 19 is on, UniData prevents even superusers
from executing commands after you remove the entries are from the VOC file.
If UDT.OPTIONS 19 is off (the default), UniData allows superusers to execute ECL commands
even if the command entries were removed from the VOC file. When a user executes a command
logged on as an Administrator on Windows or as root on UNIX, UniData first reads the VOC file in
the current account, just as it does for any other user. If there is a matching entry, UniData executes
the command. If there is no matching VOC entry, and if UDT.OPTIONS 19 is off, root users or
Administrators can still execute the command.
The following table shows the behavior of UDT.OPTIONS 19.

UDT.OPTIONS 19 Command status Behavior

ON VOC entry exists root/Administrator can execute command
Others can execute command
OFF VOC entry exists root/Administrator can execute command
Others can execute command
ON No VOC entry root/Administrator cannot execute command
Others cannot execute command
OFF No VOC entry root/Administrator can execute command
Others cannot execute command

UDT.OPTIONS 19 is turned off by default. Leave it off to allow root users/Administrators to execute
commands that users cannot; turn it on to make root users/Administrators consistent with other
users.

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

96
 Customizing permissions on UNIX

Customizing permissions on UNIX

When you install UniData, the system sets default permissions on system files and directories, as
shown in the following table.

File or directory name Permission settings of file/ Permission settings of files/

directory subdirectories
udtbin drwxr-xr-x See next rows
udtbin/product.info -rw-r--r-- Not applicable
udtbin/us_admin -r-sr-xr-x Not applicable
udtbin/us_update_db -r-sr-xr-x Not applicable
udthome drwxr-xr-x See following rows
udthome/demo drwxrwxrwx -rwxrwxrwx
udthome/lib drwxr-xr-x
udthome/objcall drwxrwxr-x See next rows
udthome/objcall/demo drwxrwxr-x rw-rw-rw-
udthome/objcall/ drwxrwxr-x rw-r--r--
include
/usr/ud82/ods drwxrwxr-x Varies
udthome/parttbl Not applicable -rw-r--r--
udthome/sybase drwxrwxr-x Varies
udthome/sys drwxr-xr-x Varies
udthome /sys/HELP.FILE -rw-r--r-- Not applicable
udthome/sys/udtpath -rw-rw-rw Not applicable
udthome/work drwxr-xr-x -rw-rw----
/usr/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 table
file, are -rw-rw-rw-. Users responsible for cataloging or deleting
cataloged programs need write permission. Other users need
only read permission.
udthome sys/DICT.DICT Users need only read permission. Administrators need write
permission as well.
udthome/sys/VOC Users need only read permission. Administrators need write
permission as well.
udthome/sys/CTLG Users, including programmers, need execute permission to this
global catalog directory. In general, do not allow users to add or
delete subdirectories to CTLG.
udthome/sys/ CTLG/n and CTLG contains a subdirectory for each letter of the alphabet
directories and files within these and one for symbols. Users need execute permission to these
subdirectories directories and read access to the files in them. Programmers
may need read and write permissions so that they can catalog or
delete cataloged programs.
udthome/demo This directory is used for training and experimentation. Use any
permissions settings that suit your situation.

97
Chapter 9: Managing UniData security

Directory or file Guidance

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

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

Directory or File Guidance

./ Only users who need to create files in the directory should have
write permission.
./BP Users need read and execute permissions so they can run
UniBasic programs that are not globally cataloged. Programmers
need write permission.
./CTLG Users need read and execute permissions so they can run locally
cataloged programs. Programmers and administrators need
write permission so they can locally catalog and delete locally
cataloged programs.
./SAVEDLISTS Users need read and write permissions.
./_HOLD_ Users need read and write permissions.
./_PH_ Users need read and write permissions.
./VOC (This refers to the account VOC file, not the master VOC file in
udthome/sys.) Users must have read and write access to
enter their accounts unless you have set the VOC_READONLY
environment variable. See Using UniData for more information
about the VOC file.

The following screen shows a long listing for a UniData account called PAYABLES, incorporating the
suggestions outlined in the preceding tables:

98
 Customizing permissions on Windows

Customizing permissions on Windows

To customize permissions, from Windows Explorer, select the directories or files for which you want to
customize permissions. Using the right mouse button, click the directory or file, click Properties, and
then click the Security tab.
Select the permissions you want in the Permissions area, then click OK.
We make a series of recommendations for customizing these permissions, as shown in the next table.

Directory or file Guidance

udthome\sys\CTLGTB Users responsible for cataloging or deleting cataloged programs
need write permission. Other users need only read permission.
udthome\sys\DICT.DICT Users need only read permission. Administrators need write
permission as well.
udthome\sys\VOC Users need only read permission. Administrators need write
permission as well.
udthome\sys\CTLG Users, including programmers, need execute permission to this
global catalog directory. In general, do not allow users to add or
delete subdirectories to CTLG.
udthome\sys\CTLG\n and CTLG contains a subdirectory for each letter of the alphabet
directories and files within these and one for symbols. Users need execute permission to these
subdirectories directories and read access to the files in them. Programmers
may need Change permissions to the subdirectories and files so
they can catalog or delete cataloged programs.
udthome\demo Use this directory for training and experimentation. Use any
permissions settings that suit your situation.
udthome\sys\AE_BP All users with access to AE (the line editor) need read and write
permissions.

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

Direct Description
The account directory Only users who need to create files in the directory should have
write permission.
BP Users need read and execute permissions so they can run
UniBasic programs that are not globally cataloged. Programmers
need write permission.
CTLG Users need read and execute permissions so they can run locally
cataloged programs. Programmers and administrators need
write permission so they can locally catalog and delete locally
cataloged programs.
SAVEDLISTS Users need read and write permissions.
_HOLD_ Users need read and write permissions.
_PH_ Users need read and write permissions.
VOC (This refers to the account VOC file, not the master VOC file in
udthome\sys.) Users must have read and write access to
enter their accounts unless you have set the VOC_READONLY
environment variable. See Using UniData for more information
about the VOC file.

99
Chapter 9: Managing UniData security

Remote items
You can further customize security by replacing some command entries in your VOC file with remote
items.
A remote item (R-type VOC record) allows you to store a record definition in a location other than the
VOC file. You can substitute remote items for sentences, paragraphs, commands, locally cataloged
programs, or menus. See Using UniData for more information about R-type items.
R-type items enable you to customize security in two ways:
▪ You can use a remote item as a pointer to a location with different UNIX/Windows file permissions
from the current account, limiting access to the item.
▪ You can supply a “security routine” for the remote item. R-type items name a cataloged subroutine
that is executed when a user invokes the remote item. The subroutine must have one argument,
and return a value of 1 (true) or 0 (false). When a user invokes a remote item with a security
subroutine, the remote item does not execute unless the subroutine returns 1 (true).
The following screen shows an example of a remote item created for the ECL LIST command:

With this VOC record in place, when a user executes the LIST command, UniData executes a security
subroutine called SECTEST2. If that subroutine returns a value of 1, UniData executes the item called
LIST in a file called OTHER_VOC.
The next screen shows the security subroutine:
:AE BP SECTEST2
Top of "SECTEST2" in "BP", 4 lines, 66 characters.
*--: P
001: SUBROUTINE SECTEST2(OKAY)
002: COMMON /SECUR/ VALID
003: OKAY = VALID
004: RETURN
Bottom.
In this example, the subroutine obtains the value of VALID from named COMMON. The value can be set
by another subroutine or program. The following example shows what happens if VALID is zero (false)
and a user executes the ECL LIST command:
:LIST VOC WITH F1 = PA
Not a verb
LIST
The next screen shows what happens if VALID is 1 (true):
:LIST VOC WITH F1 = PA
LIST VOC WITH F1 = PA 11:13:27 May 24 2011 1
VOC.......
ECLTYPE
CP
CT
SP.OPEN
listdict
LISTDICT

100
 The SETFILE command

6 records listed

The SETFILE command

You can also customize security by placing data files in a location with different UNIX permissions or
NTFS permissions on Windows than your UniData account, and then modifying the corresponding VOC
entries to point to the location.
Use the SETFILE ECL command to establish the file pointers, as shown in the following UNIX
example:
:SETFILE /usr/SECURE/INVENTORY INVENTORY
Establish the file pointer
Tree name /usr/SECURE/INVENTORY
Voc name INVENTORY
Dictionary name /usr/SECURE/D_INVENTORY
Ok to establish pointer(Y/N) = Y
SETFILE completed.
You can set the UNIX or NTFS permissions at the location of the file to limit access. If a user with
insufficient permissions tries to access the file, UniData displays an error message similar to the one
shown in the following example:
:LIST INVENTORY ALL
Open /usr/SECURE/INVENTORY error.
Open file error.
:
See the UniData Commands Reference for information about the SETFILE command.

LOGIN and LOGOUT paragraphs

You can define LOGIN and LOGOUT paragraphs in the VOC files of your accounts to provide further
control of users’ environments.
A typical LOGIN paragraph sets UDT.OPTIONS and invokes an application menu. A typical LOGOUT
paragraph executes a routine that cleans up application files and exits the application in an orderly
manner.
On UNIX, if a user’s .login or .profile sets their working directory to a UniData account and
executes the udt command, and the LOGIN paragraph defines the UDT.OPTIONS and displays a
menu, the user does not see the UNIX shell nor the ECL prompt. This is a similar result on Windows–
if you define the environment so that a user logs directly on to a UniData account and performs the
same actions, the user does not see the MS-DOS prompt nor the ECL prompt.
The behavior of LOGIN and LOGOUT paragraphs are summarized as follows:
▪ When a user enters UniData, UniData checks the VOC file in the account the user is entering for a
LOGIN paragraph. If there is one, UniData automatically executes it.
▪ If the user changes accounts with the ECL LOGTO command, UniData does not execute the
LOGOUT paragraph in the account the user is leaving. UniData looks in the VOC file of the account
the user is entering, and executes the LOGIN paragraph there, if there is one.
▪ When a user exits UniData, UniData checks the VOC file in the user’s current account and executes
the LOGOUT paragraph, if one is there.

101
Chapter 9: Managing UniData security

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

The following sample sessions show simple examples of LOGIN and LOGOUT paragraphs in a UniData
account, and a different LOGOUT paragraph in a second account.
UNIX example:
:WHERE
/users/testacct
:CT VOC LOGIN
VOC:
LOGIN:
PA
UDT.OPTIONS 19 ON
UDT.OPTIONS 20 ON
DISPLAY ENTERING UNIDATA APPLICATION
:CT VOC LOGOUT
VOC:
LOGOUT:
PA
DISPLAY EXITING UNIDATA APPLICATION
:
:LOGTO /usr/ud82/demo
:CT VOC LOGOUT
VOC:
LOGOUT:
PA
RUN BP EXIT_PROG
DISPLAY LOGGING OUT OF UNIDATA
:
Windows example:
:WHERE
C:\USERS\TEST
:CT VOC LOGIN
VOC:

LOGIN:
PA
UDT.OPTIONS 19 ON
UDT.OPTIONS 20 ON
DISPLAY ENTERING UNIDATA APPLICATION
:CT VOC LOGOUT
VOC:

LOGOUT:
PA
DISPLAY EXITING UNIDATA APPLICATION
:
:LOGTO \UniData82\demo
:CT VOC LOGOUT
VOC:

LOGOUT:
PA
RUN BP EXIT_PROG
DISPLAY LOGGING OUT OF UNIDATA
:

102
 LOGIN and LOGOUT paragraphs

In the preceding example, the second LOGOUT paragraph executes a program called EXIT_PROG,
which simply prints a message. A user-written exit program can perform a variety of tracking and
reporting functions.
The next screens show the response when two of these paragraphs are executed.
UNIX example:
% pwd
/users/testacct
% udt
UniData Release 8.2.1 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
:QUIT
EXITING THE INVENTORY APPLICATION
LOGGING OUT OF UNIDATA
%
Windows example:
C:\USERS\TEST
% udt
UniData Release 8.2.1 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
:WHERE
C:\U2\UD82\DEMO
:QUIT
EXITING THE INVENTORY APPLICATION
LOGGING OUT OF UNIDATA
%
Notice that the LOGIN paragraph defines UDT.OPTIONS and then prints a message. A LOGIN
paragraph can also execute a program or display a menu. If a user’s .login or .profile file
sets their working directory to a UniData account and executes the udt command, and the LOGIN
paragraph defines the UDT.OPTIONS and displays a menu, the user does not see either the UNIX
shell prompt or the ECL prompt.
Notice also that logging out of UniData after the LOGTO command executes the LOGOUT paragraph of
the current account only.

Note: If UDT.OPTIONS 20, U_IGNLGN_LGTO, is on, users logged on as root/Administrators can

access an account through the LOGTO command without executing the LOGIN paragraph. If a user
logged on as root or an Administrator accesses the account directly, UniData executes the LOGIN
paragraph regardless of the setting of UDT.OPTIONS 20.

103
Chapter 9: Managing UniData security

Creating a login paragraph for UniData ODBC connections

ODBCLOGIN is a UniBasic subroutine you can create to initialize the UniData environment for UniData
ODBC, 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 ODBCLOGIN
subroutine to initialize environments when accessing through UniData ODBC, UCI, UniOLEDB,
U2.Net, or JDBC.

Syntax
SUBROUTINE ODBCLOGIN(RTNVAL,USERNAME)
When a UniData ODBC, UCI, UniOLEDB, U2.Net, or JDBC connection is made, UniData attempts to
execute the ODBCLOGIN paragraph during the verification phase of a connection, in the database you
specify in the connection information.

Note: If there is no cataloged ODBCLOGIN, the connection is allowed.

Parameters
The following table describes the parameters of the subroutine.

Parameter Description
RTNVAL If RTNVAL is a nonzero value, the connection is allowed. If it is zero, 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 use
during a UniData ODBC connection.

In the following example, the ODBCLOGIN subroutine returns zero and does not allow a connection
unless the user name is “root.”
SUBROUTINE OEDBCLOGIN(RTNVAL,USERNAME)
IF USERNAME=”root” THEN
RTNVAL = 1
END ELSE
RTNVAL = 0
END
RETURN

Creating a login paragraph for UniObjects connections

UOLOGIN is a UniBasic subroutine you can create to implement any sort of security functionality you
would like.

Syntax
SUBROUTINE UOLOGIN(RTNVAL,SECRET)

104
 UniData SQL privileges

You must globally catalog the subroutine. For example, you might want to prevent a UniObjects
connection unless a user provides the name of the application.
When a UniObjects connection is made, UniData attempts to execute the UOLOGIN paragraph during
the 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.

Parameters
The following table describes the parameters of the subroutine.

Parameter Description
RTNVAL If RTNVAL is a nonzero value, the connection is allowed. If it is zero, the
connection is disallowed and an error message is returned.
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, or anything that
only the client and the server know between them to identify the client.

In the following example. UniData does not allow a connection unless the name of the application and
the user name is provided. In this case, the user information is “<SECURITYTOKEN>:username”.
SUBROUTINE UOLOGIN(RTNVAL,SECURITYTOKEN)
IF SECURITYTOKEN=”uocommand” THEN
RTNVAL=1
END ELSE
RTNVAL=0
END
RETURN
If the UOLOGIN subroutine is cataloged on the server, the UniObjects server runs the subroutine when
the connection is made. If the return value is zero, the server process terminates and returns Error
80011.

The UOLoginCommand file

The UOLOGIN subroutine provides similar functionality as the LOGIN paragraph, where UniObjects
connections bypass paragraphs. You can use some LOGIN paragraph commands from UniData, such
as DATE.FORMAT, in the UOLOGIN subroutine to set global conditions, but they would not result in a
global change.
At UniData 8.1.1, you can enable one or multiple commands to be read from the UOLoginCommand
file, located in the $UDTHOME directory, when a UniObjects session starts. Only one command, or
one paragraph (defined in the VOC file) with multiple commands, can run from this file and must be
specified on the first line of the UOLoginCommand file (for example, DATE.FORMAT)
This UOLoginCommand file is in addition to the UOLOGIN subroutine. It does not impact the existing
UOLOGIN functionality.

UniData SQL privileges

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

105
Chapter 9: Managing UniData security

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

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

Field-level security for UniQuery

UniData includes functionality to determine UniQuery access on an attribute-by-attribute basis.
System administrators can set privileges for UniQuery access at the file or attribute level for a single
user, or for all users in the UNIX group, by creating a QUERY.PRIVILEGE table in a specified format and
adding records to that table.
You can also set a default for your system, defining all files as OPEN or SECURE. In an OPEN
system, the ability to access a file or a field with UniQuery is a function of operating system
level file permissions, other UniData security implementations, and privileges granted using the
QUERY.PRIVILEGE table. In a SECURE system, unless privileges are granted in the QUERY.PRIVILEGE
table, users cannot access files through UniQuery, regardless of operating system 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 must
create and populate the QUERY.PRIVILEGE file manually.
▪ ECL commands, such as CREATE.FILE, DELETE.FILE, and CNAME, do not update the
QUERY.PRIVILEGE table.
▪ ECL commands are not affected by UniQuery security.
▪ The UniQuery MODIFY command is not affected by the UniQuery security feature. The security is
imposed when a user attempts to SELECT.
▪ A default of OPEN or SECURE affects all UniData accounts that share the same udthome. You
cannot define some accounts as OPEN and some as SECURE.
▪ Privileges granted on a file are not automatically applied to its dictionary. Therefore, if a user has
ALL access to the INVENTORY file and its dictionary, you must consider D_INVENTORY as well. If
the system default is OPEN, the user can access D_INVENTORY. Otherwise, if you want the user to
access D_INVENTORY, you need a QUERY.PRIVILEGE record for D_INVENTORY as well.

The QUERY.PRIVILEGE file

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

106
 The QUERY.PRIVILEGE file

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

When you install UniData, the UniQuery security is not implemented, and there is no
QUERY.PRIVILEGE file. If you wish to turn on this feature, you must create QUERY.PRIVILEGE
and D_QUERY.PRIVILEGE manually.
Records in the QUERY.PRIVILEGE file grant the SELECT privilege to users or groups of users, at the
file level or the attribute level. Each QUERY.PRIVILEGE record has one attribute. The dictionary of
the QUERY.PRIVILEGE file contains four records.
Following is a sample of the dictionary of the QUERY.PRIVILEGE file:

The following table describes each QUERY.PRIVILEGE attribute. The descriptions differ between
Windows and UNIX.

Attributes Description
@ID Windows: Data attribute that defines the user or domain and the file for which
you are setting privileges. If you are setting up a system default, @ID is DEFAULT.
Otherwise, @ID must be of the format username*path, domain\ username*path,
or PUBLIC*path.
UNIX: Defines the user or UNIX group and the file for which you are setting
privileges. If you are setting up a system default, @ID is DEFAULT. Otherwise, @ID
must be of the format username*path or PUBLIC*path.
PRIV Windows: Data attribute that indicates the attributes to which you are granting
privileges, by location. PRIV is a multivalued attribute. To grant privileges to all
attributes in a file, set PRIV to ALL. If you are setting a system default, set PRIV to
OPEN to grant privileges. To restrict privileges to every attribute in a file, set PRIV
to SECURE.
UNIX: Multivalued; lists the field(s) to which you are granting access by location in
the data file record. You can grant privileges on all fields in a data file by setting
PRIV to ALL. If you are setting up a system default, set PRIV to either OPEN or
SECURE.
FULLPATH Windows: Virtual attribute formula that designates the full path of the file affected
by PRIV. This formula has the format FIELD(@ID,”*”,2).
UNIX: The absolute UNIX path of the file on which you are setting UniQuery
privileges.

107
Chapter 9: Managing UniData security

Attributes Description
USERNAME Windows: Virtual attribute formula that designates the user affected by PRIV. This
formula has the format FIELD(@ID,”*”,1).
UNIX: The UNIX ID of the user (or group) to which you are granting privileges.

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

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

This QUERY.PRIVILEGE file means:

▪ Except for INVENTORY and CLIENTS, which are in the demo database, all users have privileges to
query all files in all accounts that share the same udthome.
▪ user01 can query the fields in positions 1, 2, 3, 4, 5, and 11 only in the INVENTORY file. No other user
can query this file.
▪ user01 can query any field in the CLIENTS file. No other user can query the CLIENTS file.

UniQuery processing
If you have turned on the security feature by creating and populating the QUERY.PRIVILEGE file,
every time a user logs on to UniData, their udt process reads the contents of QUERY.PRIVILEGE and
stores the information for reference. Then, when a user attempts a UniQuery access, UniData checks
the stored information, following the following steps:
1. Check for privileges granted to the user’s UNIX group or Windows domain.
If the user’s UNIX group or Windows domain has sufficient privileges for the requested access,
allow the access. Otherwise, proceed to the next step.
2. Check for privileges granted specifically to the user.
If the user has sufficient privileges for the requested access, allow the access. Otherwise, proceed
to the next step.
3. Check for privileges granted to PUBLIC.
Privileges granted to PUBLIC apply to all system users. If PUBLIC has sufficient privileges for the
requested access, grant the access. Otherwise, proceed to the next step.
4. Check for a DEFAULT entry.

108
 Turning on field-level security

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

Turning on field-level security

Implement field-level security by creating the QUERY.PRIVILEGE file.
1. With UniData running, log on as an Administrator on Windows or as root on UNIX. Users do not
need to log off unless you choose to add records as described in step 5.
2. Change your working directory to udthome/sys, and enter udt to start a UniData session. Use
the ECL CREATE.FILE command as displayed in the following UNIX example:
:WHERE
/usr/ud82/sys
:CREATE.FILE QUERY.PRIVILEGE 101
Create file D_QUERY.PRIVILEGE, modulo/1,blocksize/1024
Hash type = 0
Create file QUERY.PRIVILEGE, modulo/101,blocksize/1024
Hash type = 0
Added "@ID", the default record for UniData to DICT
QUERY.PRIVILEGE.
Make the QUERY.PRIVILEGE file a static hashed file.
3. Set permissions to the QUERY.PRIVILEGE file. The file and its dictionary should be read-only to
all users except Administrators/root users.
For example, if you need to change UNIX permissions:

4. Use AE or ED to edit D_QUERY.PRIVILEGE.

The dictionary must look like the following example:

You can customize the format for the dictionary items to specify lengths for the attributes that
match your system.
5. Add records to QUERY.PRIVILEGE using AE or ED.

109
Chapter 9: Managing UniData security

Note: For this step, have users log out of UniData. As you add records to the
QUERY.PRIVILEGE file, users logging on to UniData access whatever records are present at
the time they log on, which can cause unexpected results.

UniData and UNIX security

This section describes UNIX security mechanisms and outlines how these mechanisms are used by
UniData. It is important to understand UNIX security because UNIX file permissions form the basis of
UniData security.

UNIX file permissions

In UNIX, each file or directory has permissions set for the owner (called user), for members of the
group owner (called group), and for all other users except root (called other). The root user has all
access to all files on the system, regardless of their owners or group owners.
UniData uses UNIX permissions as a principal security mechanism. The following table shows what the
UNIX permissions mean when applied to a file.

Permission Description
r (read) Read or copy a file
w (write) Modify a file
x (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 shown
in the following table.

Permission Description
r (read) List the directory’s contents
w (write) Add or remove files from the directory
x (search) cd to the directory, or include it in a path

The following screen shows a long listing for the contents of a UNIX directory:
% ls -l
drwxrwxrwx 2 ump01 other 24 May 21 13:14 ACCOUNT
-rw-rw-rw- 1 root sys 0 Apr 30 10:51 FileInfo
drwxrwxrwx 12 root unisrc 4096 Apr 30 16:06 bin
drwxrwxrwx 12 root unisrc 2048 May 17 18:40 demo
drwxr-xr-x 2 root sys 1024 Apr 30 16:05 include
drwxr-xr-x 2 root unisrc 1024 Apr 11 12:23 lib
drwxrwxrwx 3 root sys 1024 Apr 17 11:55 logs
drwxrwxrwx 4 root unisrc 1024 Apr 10 18:28 objcall
drwxrwxrwx 5 us_admin users 1024 May 1 12:50 ods
-rw-r--r-- 1 root sys 7 Apr 11 12:22 parttbl
drwxrwxrwx 4 root unisrc 1024 Apr 10 19:12 sybase
drwxrwxrwx 4 root unisrc 1024 May 20 19:31 sys
drwxr-xr-x 2 root unisrc 1024 Apr 30 15:58 work

110
 Additional UNIX access modes

Entries beginning with “d” are directories. Entries beginning with “-” are files. Permissions for owner,
group, and all others are shown in the next nine characters. For example, the directory ACCOUNT
is owned by “ump01,” and the group owner is “other.” The owner, “ump01,” members of the group
“other” and all other users all have read, write, and search permission on ACCOUNT.
To delete a file from a directory, a user needs write permission to the directory, but does not need any
permissions to the file. On most UNIX versions, if the user does not have write permissions to the file,
the system displays the octal format for the current permissions and asks for confirmation to override
them, as shown on the following screen:
% rm testfile
testfile: 644 mode ? (y/n)
On some systems, you can set an additional access mode called the “sticky bit,” which prevents users
from deleting a file unless they have write permission on that file. See Additional UNIX access modes,
on page 111 for more information.

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

Additional UNIX access modes

UNIX 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 access
on files within the directory.
s (set UID or SUID) Set on executable files. Allows a user to invoke the executable, which runs
with 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 runs
with the privileges of the owner of the group.

Warning: Setting SUID or SGID on executables allows access to users they would not be granted
based on the permissions. These access modes, if not used with caution, can compromise the
security of your system. Also, these access modes behave somewhat differently in different UNIX
versions. 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 each
of them is set.
The first screen shows the sticky bit:
% ls -l
total 2
drwxrwxrwx 2 ump01 unisrc 24 May 21 13:48 testdir
%
% chmod a+t testdir
% ls -l
total 2
drwxrwxrwt 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

111
Chapter 9: Managing UniData security

%
% chmod g+s testfile
% ls -l
-rwxrwsrwx 1 ump01 unisrc 0 May 21 15:58 testfile
%
The group owner must have x (execute) permission on the file, and you must be logged in as the file
owner or as root to set SGID.
The next screen shows how to set SUID on a file called newfile:
% ls -l
-rwxrwxr-x 1 ump01 unisrc 0 May 21 16:03 newfile
%
% chmod u+s newfile
% ls -l
-rwsrwxr-x 1 ump01 unisrc 0 May 21 16:03 newfile
%
The owner of the file must have x (execute) permission on the file, and you must be logged in as the
owner or as root to set SUID.

UNIX umask
The UNIX umask command sets default permissions for file creation. umask allows you to specify
permissions that apply when a file is created. To use umask, you need to know the octal values of the
basic permissions (read, write, execute), and the UNIX default permissions for files and directories. The
following table shows the octal values for the permissions and for common combinations.

Permission Octal value

read 1
write 2
execute (or search) 4
read+execute 5
read+write 6
write+execute 3
read+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 value
from the UNIX default. For example, if you set umask to 002 and create a file, the permissions on that
file are represented by the difference between the default (666) and umask (002), or 664. Permissions
of 664 translate to rw-rw-r--. The following screen shows three umask settings and their effects:
% umask 022
% touch umask.tst1
% ls -l umask.tst1
-rw-r--r-- 1 ump01 unisrc 0 May 21 17:43 umask.tst1
% umask 222
% touch umask.tst2
% ls -l umask.tst2
-r--r--r-- 1 ump01 unisrc 0 May 21 17:43 umask.tst2

112
 UniData for UNIX default permissions

% umask 007
% mkdir umask.tst3
% ls -l
drwxrwx--- 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 file
permissions in most cases according to the user’s current umask. The exceptions are the
directories for dynamic files and multilevel files and directories. Permissions for these are set to
775 octal (rwxrwxr-x).

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

Refer to your host operating system documentation for detailed information about the umask
command.

UniData for UNIX default permissions

When you install UniData software on your system, the installation process sets the ownership of
the 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 the
files it installs. For each file, the owner permissions apply to root. The group permissions apply to all
members of the group you specify in the installation procedure. The final set of permissions applies to
all other users on your system.
The following screen shows a long listing for the file /usr/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 has
read 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 system
allows you to specify the owner and group for the account. The system sets the owner and group
owner accordingly.
You can customize the file permissions to meet specific needs for your system. See Managing UniData
security, on page 95 for information about customizing file protections.
UniData also allows you to fine-tune your system security by customizing the VOC files in your
UniData accounts and by granting specific privileges to UniData SQL users via the UniData SQL GRANT
command. See Managing UniData security, on page 95 for information about tuning UniData
security.

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

113
Chapter 9: Managing UniData security

UniData for UNIX processes and root

Since the principal UniData daemons, smm, sbcs, unirpcd, and cleanupd must run as root,
UniData must be started by root. Those daemons have all access to all files on your system. (If you
are using the Recoverable File System (RFS), the RFS daemons also run as root.) For security reasons,
UniData users should not have root privileges. When a user enters UniData, the user process (called
a udt) runs under the UID of the user. Since the udt process drives all file access, users can perform
only actions that are allowed by your system’s security, which consists of UNIX file permissions, the
local VOC file, and SQL privileges.

Logins and groups on UNIX

To 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. For
consistency, we recommend that you use your UNIX system administration utility to create
and maintain UNIX accounts. Refer to your host operating system documentation and vendor
documentation 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 file name Description

/etc/group Contains a record for each group ID number (gid). Each record includes
a group name and defines the user ID numbers (uid) associated with the
group.
/etc/passwd Contains a record for each user ID. Each record includes a login name, uid,
gid, password, home directory, default shell identifier, and other optional
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 operating
system documentation for complete information about these files.

Adding a UNIX user

You can add a UNIX user manually or through your system administration utility.
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.

Use separate logon IDs

Although other database systems use group login IDs, which are shared by a number of users, UniData
enables you to define a separate logon ID for each user.
We strongly recommend that you use separate login 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 resources
more effectively.

114
 User groups

▪ 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 their
passwords and your data.

User groups
Every UNIX user is assigned to a default group. The system recognizes the user as a member of that
default group at log on.
UNIX permissions allow you to differentiate access among members of a group and users who are
not members of that group. You can use this feature to provide security in UniData by defining
applications (or accounts) that should be accessible to certain users, defining groups to which those
users belong, and setting the group owners of the files and directories accordingly.
For example, consider the directory structure that is shown in the following example:
...
drwxrwxr-- 2 root apusers 24 Jun 18 18:18 PAYABLES
drwxrwxr-- 2 root arusers 24 Jun 18 18:19 RECEIVABLES
...
The example shows a long style listing for separate UniData accounts for two applications: PAYABLES
and RECEIVABLES. Notice the following:
▪ Users in group apusers have read, write, and execute access to the contents of PAYABLES, but only
read access to RECEIVABLES. They can list the contents of RECEIVABLES, but they cannot add or
delete files in RECEIVABLES, or cd to that directory, or access it with the ECL LOGTO command.
▪ Users in group arusers have read, write, and execute access to RECEIVABLES, but only read access
to PAYABLES. They can list the contents of PAYABLES, but they cannot add or delete files in
PAYABLES, or cd to that directory, or access it with the ECL LOGTO command.
You can assign users to more than one group. Refer to your host operating system documentation for
information about your system. The UNIX id command enables root users to display the current uid
and group assignment for any login name. The UNIX newgrp command lets users change between
groups. A user can function as a member of only one group at any time.
A user must be defined as a member of a group (in /etc/group) before they use newgrp to change
to it. In the preceding example, a user who is a member of only group arusers cannot use newgrp to
change to apusers.

Home directories
UNIX requires you to define a home directory for each login ID. This directory is the working directory
of the user at login time. You can define the same home directory for a group of users, or create a
separate one for each user. The home directory does not must be a UniData account.

Tip: A user’s home directory can contain startup scripts as well as output from non-UniData
applications (such as UNIX text editors). The UniData command stack is also saved here. If you use
UniData accounts as home directories, and users generate other kinds of output there, you may
encounter space or performance problems.

Note: The home directory that you define for a user must exist. If you define a directory and you
do not create it or set appropriate permissions, the user may be unable to log on to UNIX. When
you add a user, some administrative utilities create the directory and set permissions. Check the
documentation for your UNIX system administration utility to determine procedures at your site.

115
Chapter 9: Managing UniData security

Startup scripts
When a user logs on, the default shell (specified in /etc/passwd) runs a startup script, if one exists,
in the user’s home directory. The file name of the startup script depends on the user’s default shell. If
the shell is the Bourne or Korn shell, the startup script is called .profile. If the shell is the C shell,
the startup script is called .login.

Tip: Many UNIX systems offer a default shell script that you can copy into a user’s home directory
and then customize. Some systems also execute a system-wide script for all login IDs. Refer to your
host operating system documentation for specific information about your system.

A sample .login file follows:

setenv TERM vt100
stty erase ^H
set path=( $path /usr/ud82/bin)
umask 002
cd /usr/ud82/PAYABLES
udt
This example shows how to use a startup script to ensure that a user logs on to a particular UniData
account and receives an ECL prompt, rather than a UNIX prompt. The example also defines the user’s
terminal type, defines the key sequence for erasing characters, modifies the user’s path to include the
UniData bin directory, and specifies the default permissions on files the user creates.

116
Chapter 10: Managing UniData files
UniData stores your data in hashed files of several different types in the database. UniData also
supplies other types of files to support your database, including index files, program files, and
directory files.
This section describes the types of UniData hashed files and explains the commands that are used to
manage them. See UniData and the UNIX file system (UNIX only), on page 326 for information about
other file types.

UniData hashed files

Hashed files are binary files that cannot be viewed at the operating system level or read by text editors
external to UniData. Each UniData hashed file consists of a file header and one or more groups of data.
Each data group contains the following structure:
▪ A fixed-length group header
▪ A pointer array
▪ Record IDs
▪ Data
A record key is assigned to a group in the file according to a hashing algorithm. Then, the precise
location of the data is stored in the header of that group. The goal of hashing is to make searching
for data more efficient by eliminating the need to search an entire file for a record. In a hashed file,
UniData searches only the group where the primary key of the record was assigned. UniData supports
two proprietary hashing algorithms (hash type 0 and hash type 1). The hash type determines the data
group that contains each record.
The most efficient hashing algorithm for a file is the one that provides the best distribution of keys
across the groups in the file. If the distribution is uneven, heavily loaded groups are accessed more
frequently, which results in inefficient disk space use and increased contention for those groups. The
default hash type for both static and dynamic files is 0. When you create a file, you can specify hash
type 1, and you can switch between hash types with the memresize command.

Static hashed files

Static hashed files are created with a specified block size multiplier and a specified modulo (number of
data groups). The block size and modulo are stored in the header of the file.
Groups in static hashed files can overflow in two ways, as shown in the following table.

Overflow type Description

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

117
Chapter 10: Managing UniData files

Overflow type Description

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

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 original
group and are not available to handle overflow from any other group in the data file. The space
used by the blocks is not returned to the operating system. Level 1 overflow eventually impacts
the performance of a static hashed file. Level 2 overflow impacts performance earlier and more
severely, so correct sizing to prevent level 2 overflow is critical.

Dynamic hashed files

Dynamic hashed files automatically increase modulo (number of groups) to minimize level 2 overflow.
When viewed at the operating system level, the structure of dynamic files is different from that of
static files.
A dynamic file is actually a directory containing at least two binary files:
▪ One or more data files named dat00x. These are hashed files. dat001 is the primary data file.
Each group in a dat file contains a group header, keys, pointers, and data.
▪ One or more overflow files named over00x. Blocks in these files hold data when a group in a data
file is in level 1 overflow.
The following screen shows the structure of the ORDERS file in the UniData demo database:

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

Dynamic files and overflow

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

118
 Splitting and merging

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

Splitting and merging

When a group in the primary data file reaches level 1 overflow, UniData stores the overflowed data in
blocks in the overflow file. Blocks in over001 are linked (internal to UniData) to groups in the primary
data file dat001. When the overflow file runs out of blocks, UniData adds blocks to it. To prevent level 2
overflow, UniData splits groups (increasing the modulo of the primary file) whenever the load factor of
an existing group reaches a level called the splitting threshold (or SPLIT.LOAD). The splitting process
is transparent to the user. When a group splits, the additional group is added to the primary data file,
increasing its modulo and physical size.
As records are removed from a dynamic file, groups that had been split can merge back together if all
the following conditions are true:
▪ The current modulo of the file is greater than the minimum modulo of the file.
▪ The combined load factor of the two groups is less than a value called merging threshold (or
MERGE.LOAD).
▪ One of the two groups is the last group in the file.
UniData provides three different split/merge types for dynamic files, KEYONLY, KEYDATA, and
WHOLEFILE (Windows only). You can set the split/merge type when you create a dynamic file, and you
can change an existing split/merge type with the CONFIGURE.FILE command or the memresize
command. Use FILE.STAT, ANALYZE.FILE, or GROUP.STAT to display the split/merge type.

WHOLEFILE type (Windows only)

At version 8.1.0, UniData features a new type of dynamic file type called WHOLEFILE that changes
its modulo based on the total file load rather than the load of an individual group. The previous
types of KEYDATA and KEYONLY worked well when the records hashed evenly and there was only a
small standard deviation in terms of record and key size. The new type of WHOLEFILE is designed
to overcome these restrictions and will work with both 32-bit and 64-bit dynamic files and for both
recoverable and nonrecoverable files.
In addition, a new udtconfig parameter called DEFAULT_SPLIT_TYPE has been introduced at this
release. This new parameter defines the default split style for a dynamic file and has values of 1 for
KEYONLY, 2 for KEYDATA, or 3 for WHOLEFILE. The default value when creating a new dynamic file is 3.
Two udtconfig parameters have been introduced at 8.1.0 for the WHOLEFILE type. The new
parameters are:

WHOLEFILE_SPILT_LOAD
This parameter refers to the default split load for a WHOLEFILE style dynamic file. The default for this
parameter is 75.

WHOLEFILE_MERGE_LOAD
This parameter refers to the default merge load for a WHOLEFILE style dynamic file. The default for
this parameter is 40.

119
Chapter 10: Managing UniData files

KEYONLY type
The KEYONLY split/merge type is the default for UniData dynamic files. For KEYONLY dynamic files,
the load factor of a group is the percentage of the group space that is filled with keys and pointers.
By default, the splitting threshold for a group in a KEYONLY dynamic file is 60%, so the group can split
into two when the space occupied by keys and pointers reaches 60% of the size of the group.
By default, the merging threshold for a KEYONLY dynamic file is 40%, so if the total load in a pair of
groups that resulted from a split is under 40% of the size of a single group, the pair are eligible to
merge. You can change the splitting threshold for a single KEYONLY file with the CONFIGURE.FILE
or memresize commands, and you can change the defaults for all files by changing the SPLIT_LOAD
and MERGE_LOAD parameters in the UniData configuration file (on Windows, the file is located in
\udthome\include\udtconfig; on UNIX, /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, and
data. By default, the splitting threshold for a group in a KEYDATA dynamic file is 95 percent, so the
group can split into two when the space occupied by keys, pointers, and data reaches 95 percent of
the size of the group.
By default, the merging threshold for a KEYDATA dynamic file is 40 percent, so if the total load in a pair
of groups that resulted from a split is under 40 percent of the size of a single group, the pair are eligible
to merge.

You can change the splitting threshold for a single KEYDATA file with the CONFIGURE.FILE
or memresize commands, and you can change the defaults for all files by changing the
KEYDATA_SPLIT_LOAD and KEYDATA_MERGE_LOAD parameters in the UniData configuration file.

Selecting a split/merge type

Use the KEYONLY split/merge type for files whose records differ widely in length (standard deviation
from average is large). When record lengths vary widely, the KEYONLY split/merge type makes more
efficient use of disk space. Use the guide or FILE.STAT command to determine the record length
and standard deviation from average for an existing file.
Use KEYDATA for files whose record length is consistent and in which the length of the data portion
of each record is large with respect to the record ID. For files with these characteristics, the KEYDATA
split/merge type provides a better distribution of records and less overflow than KEYONLY.

Dynamic files and hash type

For both static and dynamic files, the default hash type is 0. This hash type provides a more even
distribution of keys in groups in dynamic files. If key distribution in a file is uneven, you should
consider tuning the modulo, block size, and split/merge type of the file. If none of these methods is
effective, you should consider switching the hash type to 1.

Dynamic files, part files, and part tables (UNIX only)

UniData allows a dynamic file to have multiple dat, over, and idx files, so that a dynamic file does
not have the 2 GB limit as does a static file. These “part files” can reside in different file systems. Each
part file can approach 2 GB in size. The total number of part files in a dynamic file cannot exceed 255.
Part files are numbered sequentially by type (for instance, dat002, over002, and idx002).

120
 Location of part tables (UNIX only)

The UniData configuration parameter MAX_FLENGTH defines the maximum size, in bytes, for a “part”
of a dynamic file. UniData distributes “part files” across file systems using ASCII files called “part
tables.” A part table:
▪ Lists eligible file systems into which dynamic files are allowed to expand.
▪ Specifies the amount of reserved space on each file system. Reserved space is not available for
dynamic file expansion. Defining reserved space reduces the probability of the disk becoming full.
The default value for MAX_FLENGTH, set when you install UniData, is 1 GB (1073741824 bytes). You can
increase MAX_FLENGTH, but the maximum value is (2 GB - 16 K).

Location of part tables (UNIX only)

System default part table

The UniData installation procedure creates a system default part table, udthome/parttbl.
The location of the system default part table is identified by the UniData configuration parameter
PART_TBL.

Per-file part tables

You can also create individual part tables for dynamic files using vi or any other UNIX text editor.
Assign a part table to a file by using the PARTTBL keyword with the CREATE.FILE and memresize
commands. Supply the full path of the ASCII file you wish to use as a part table. UniData copies
the ASCII file into the dynamic file directory, where it becomes the part table for the dynamic file.
Specifying individual part tables allows you to balance the creation of part files across volumes in your
system. In the following example, the PARTTBL keyword assigns a part table to a new dynamic file:

Notice that the dynamic file directory contains the parttbl, which was copied from /disk1/
unidata.

Components of a part table (UNIX only)

The name of the system default part table (created at installation time) is udthome/parttbl. The
default parttbl looks like:
% more /usr/ud82/parttbl
. 1000
%
The following table describes the fields in the part table:

121
Chapter 10: Managing UniData files

Field Description
Path Name of the file system; the “.” in the default table indicates the file system where a
UniData dynamic file is created. The “.” can be used as the first entry in the table; all
other entries must be the absolute UNIX path (for instance, /disk6/files).
Reserved Amount of free space (in 512-byte blocks) that UniData should leave in the file
Space 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 part
table for your system. A sample part table follows:
. 10000000
/usr/unidata/partfiles 10000
/disk1/unidata/partfiles 10000

Part table tips and constraints (UNIX only)

Consider the following points if you are creating or modifying part tables:
▪ Do not use a dynamic file directory as an entry in the parttbl. This causes a number of problems,
including difficulty resolving the links to part files and the creation of part files from one dynamic
file in the directory for another dynamic file. This, in turn, causes failures when users attempt to
execute the CLEAR.FILE or DELETE.FILE command on one of the two dynamic files.
▪ Do not use multiple entries in the parttbl that resolve to the same device ID. This causes confusion
when UniData attempts to check reserved space against available space.
▪ If you move the system default part table, change the value of the configuration parameter
PART_TBL.
▪ When you create an ASCII file to use as a per-file part table, remember that UniData places a
copy of that file in a dynamic file directory each time you specify it with the PARTTBL keyword
(CREATE.FILE or memresize). If you wish to add a partition or otherwise edit the file, you need
to edit the copy in each dynamic file to which it is assigned, as well as at the location where you
created the file.
▪ If you execute the memresize command to change the parameters of a dynamic file, and you
specify the PARTTBL keyword for a file that already has a per-file part table, you will overwrite the
existing per-file part table.

When dynamic files are created

The following considerations determine where the parts of a newly created dynamic file are located.

Estimating the size of the file

The estimated space required for a new dynamic file is the smaller of the following:
▪ MAX_FLENGTH
▪ minimum modulo * block size
If (minimum modulo * block size) is larger than MAX_FLENGTH, the new file needs more than one data
part file.

Locating the dynamic file directory

The dynamic file directory is located in the UniData account where CREATE.FILE was executed.

122
 Locating the part files (UNIX only)

The following example illustrates creating a dynamic file in the current account directory:

In the above example, the primary data file (dat001) includes a file header and the three data
groups for a total of four 1K blocks. The overflow file (over001) includes a 1K file header. Since
MAX_FLENGTH is larger than minimum modulo * block size, the primary data file and overflow file
each have only one “part.”

Locating the part files (UNIX only)

The part files (or UNIX links to them) are located in the dynamic file directory. UniData reserves space
for part files on the UNIX file system where the dynamic file directory is located (the resident file
system) by making the following assessments:
▪ If the part table (per-file if one exists, or system default otherwise) has an entry for that file system,
use the reserved space defined for that entry. For instance, if the dynamic file is /usr/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 that
file system. Depending on the configuration of the system, /usr/ud82/demo might reside in a
file 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 figure
associated with the “.” entry.
UniData checks the resident file system for space as follows:
▪ The space available in the file system must be more than the sum of the estimated file size and the
reserved space requirement.
▪ If there is sufficient space, dat001 and over001 are created in the dynamic file directory.
If there is not enough space in the file system, UniData:
▪ Checks each file system that has an entry in the part table.
▪ Creates dat001 and over001 on the first file system that meets the space requirement.
▪ Creates UNIX links in the original dynamic file directory.
The following screen illustrates creating a dynamic file in the current account directory:

123
Chapter 10: Managing UniData files

In the preceding example, the primary data file (dat001) includes a file header and the three data
groups for a total of four 1K blocks. The overflow file (over001) includes a 1K file header. Since
MAX_FLENGTH is larger than minimum modulo * block size, the primary data file and overflow file
each have only one “part.”
The following example shows what happens when there is insufficient space on the resident partition
of the dynamic file. The part table used in the example is one that stipulates a very large reserved
space on the current file system, thereby forcing the part files to another file system:

Notice that the dat001 and over001 files were created in a different partition and are referenced by
UNIX links.

Tips and constraints for creating a dynamic file

This section provides information about choosing the optimal modulo and block size for a dynamic
file.

Choosing the initial modulo

If you are creating a dynamic hashed file, selecting an appropriate starting (minimum) modulo is
critical to the future efficiency of the file. You should select a starting modulo based on the expected
future size of the file, because subsequent splitting and merging operations are affected by the initial
modulo.

124
 Choosing the block size

Starting with a modulo that is very small (for instance, 3) produces inefficient hashing and splitting as
the file grows. Starting with a modulo that is very large produces a file that may initially take up more
disk space than needed, but that impact is more desirable than the slow performance and inefficiency
that results if the starting modulo is too small.
When you create a dynamic file, estimate the initial modulo by using the same procedure for
estimating the modulo for a static file.

Choosing the block size

If you are creating a KEYDATA dynamic file, make sure the block size is large with respect to the record
length. 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 by
both keys and data. If the block size is not large with respect to record size, the file will occupy a large
amount of space and much of that space will be unused.
If you are creating a KEYONLY dynamic file, make sure the block size is large with respect to the
average key length. We recommend that you choose a block size that is at least ten times the average
key length. Load factor in a KEYONLY file is based on the percentage of the space in each block that
is occupied by keys and pointers. If the block size is not large with respect to the average key length,
and the hashing is not even, certain groups will be split over and over, resulting in an inefficient
distribution.

When dynamic files expand (UNIX only)

When records are added or updated in a dynamic file, a data part file, overflow part file, or index part
file may expand. Whenever a write operation requires additional blocks, the following considerations
determine whether a new part file is needed, and if so, where it is located.

Determining whether a new part file Is needed (UNIX only)

UniData first checks to see if the part file can expand in its current location. The part file can expand if
the following two conditions are true:
▪ The size of the part file is less than MAX_FLENGTH.
▪ There is enough space in the file system where the part file resides to complete the current write
without expanding into reserved space. For instance, if 10 blocks are needed, and the difference
between available and reserved space is more than 10 blocks, the part file can expand.

Note: To check for space, UniData resolves the directory where the part file resides to its UNIX
file system, and then checks the part table for an entry for that file system. For example, if
the part file is /usr/ud82/demo/ORDERS/dat001, UniData locates the UNIX file system
where /usr/ud82/demo/ORDERS resides, and checks the part table for an entry for that
file 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 either
condition is not true, and the part file is an overflow part file, UniData checks all the existing overflow
part files. If one of those part files meets the conditions, that part file is expanded. If no existing part
file can expand, UniData must create a new overflow part file. If the part file is a data part file, UniData
can expand only the last data part file created. For instance, if the dynamic file directory contains
dat001 and dat002, only dat002 can expand.

125
Chapter 10: Managing UniData files

Locating space for a new part file (UNIX only)

The following table describes how UniData computes an estimated size for the new part file,
depending on its type.

Part file type Estimated size

Data part file The smaller of the following:
▪ The larger of (size of dat001) and (current modulo * block size)
▪ MAX_FLENGTH
Overflow part file The smaller of the following:
▪ The larger of (size of over001) and (current modulo * block size)
▪ MAX_FLENGTH
Index part file The smaller of the following:
▪ The larger of (size of dat001) and (current modulo * block size)
▪ MAX_FLENGTH

UniData searches the partitions listed in the part table for the dynamic file for a partition that meets
the requirement:
available space > (estimated size + reserved space)
UniData searches the part table in the following order:
1. The resident partition of the dynamic file, because locating the part file in the dynamic file
directory saves the overhead required by a symbolic link.
2. All entries, in order from top to bottom.
▪ Creates an appropriate directory, if needed.
▪ Creates the new part file.
▪ Creates a UNIX symbolic link in the dynamic file directory, if needed.
If no partition meets the space requirement, UniData:
▪ Checks to see which partition has the largest amount of free space (available space - reserved
space).
▪ If the amount of free space is 20% or more of the estimated size, creates the new part file at
that location.
▪ If no partition has sufficient free space (20% or more of the estimated size of the part file),
UniData prompts the user to reclaim space or change the part table.

How part files are stored (UNIX only)

When dynamic files expand into a different file system, UniData creates directories in the new file
system for the part files. To prevent duplicate directory names, UniData assigns a prefix to each. The
prefixes are assigned based on an index in the target file system called .fil_prefix_tbl (a hidden
ASCII text file maintained by UniData).
A sample .fil_prefix_tbl follows:
% more .fil_prefix_tbl
AA:/home/terric/SAMPLE
AB:/home/terric/NEWACCT
AC:/home/terric/NEWACCT/MULTI1

126
 Management tools for dynamic files (UNIX only)

Each entry in .fil_prefix_tbl relates a prefix (AA, AB, and so on) to the path of a parent directory
for dynamic files. The parent directory can be a UniData account directory or a UniData multilevel file
directory. Using the sample table, this creates the following directories:
▪ If a dynamic file originated in the account directory named /home/terric/SAMPLE, the
directory created when the file expands is called AAfilename.
▪ If a dynamic file originated in the account directory named /home/terric/NEWACCT, the
directory created when that file expands is called ABfilename.
▪ If a dynamic file is a subfile of the multilevel file /home/terric/NEWACCT/MULTI1, the
directory created when that file expands is called ACfilename.
The following screen shows a directory listing that corresponds to the prefix table from the previous
example:

Warning: Do not edit or remove .fil_prefix_tbl. You will encounter unexpected results
creating, updating, and deleting dynamic files. If .fil_prefix_tbl is inadvertently removed
from a target directory, you can execute the system-level fixtbl command in each of your
UniData accounts to rebuild it.

Management tools for dynamic files (UNIX only)

UniData supplies three tools for system administrators to manage dynamic files. The tools identify and
resolve some of the inconsistencies that result if users manipulate part files at the operating system
level or inadvertently modify or delete the prefix table in a target partition.
• auditor
The system-level auditor tool reports inconsistencies between the symbolic links and the hidden
files which should be resolved to prevent apparent data loss.
• fixtbl
The system-level fixtbl command detects error conditions.
• mvpart
The system-level mvpart command moves one or more part files of a dynamic file to a different
location.

127
Chapter 10: Managing UniData files

auditor
The system-level auditor tool reports inconsistencies between the symbolic links and the hidden
files which should be resolved to prevent apparent data loss.
The tool also reports an error if a part file is not found in the correct destination. Execute auditor
from the UNIX prompt or use ! to execute auditor from the ECL command prompt. Your current
working directory must be a UniData account. auditor checks all the dynamic files that have
pointers in the VOC file of the current account.

Parent topic: Management tools for dynamic files (UNIX only)

fixtbl
The system-level fixtbl command detects error conditions.
It checks the following conditions:
▪ .fil_prefix_tbl is missing. If a dynamic file directory contains links to another partition, but
there is no .fil_prefix_tbl at that location, fixtbl can create a new one.
▪ A prefix in .fil_prefix_tbl references a different directory than the symbolic links from a
dynamic file in the current account. fixtbl can select a new prefix, then move and relink the part
files for consistency.
▪ There are symbolic links from a dynamic file to another partition, but there is no entry in the
.fil_prefix_tbl that matches the links. Assuming the prefix in the links is not used by
another directory, fixtbl can create an entry in .fil_prefix_tbl that is consistent with the
links from dynamic files in the current account directory.

Note: You must stop the UniData daemons (with stopud) before executing fixtbl.

Parent topic: Management tools for dynamic files (UNIX only)

mvpart
The system-level mvpart command moves one or more part files of a dynamic file to a different
location.
mvpart sets or resets symbolic links, if needed, and creates or updates a prefix table
(.fil_prefix_tbl) at the destination location, if needed. Using mvpart ensures that the links, file
locations, and prefix tables remain synchronized.

Note: You must stop the UniData daemons (with stopud) before executing mvpart.

Parent topic: Management tools for dynamic files (UNIX only)

Dynamic files and disk space

While it is possible for a dynamic file to shrink with respect to modulo, the disk space “freed” by
merging is not necessarily made available for other use. When a group splits, the extra group added
to the dynamic file is assigned to the existing group that split. When a merge occurs, the “freed” group
remains allocated to the dynamic file, for use if the original group splits again.

128
 Dynamic files and disk space

When data is removed from blocks in the overflow file, UniData keeps those blocks for the dynamic
file. A certain number are reserved for the groups they were part of, and the remainder of the
blocks are available for overflow from any group in the file. The UniData configuration parameter
GRP_FREE_BLK defines the maximum number of free blocks that should be kept in the free block list
for a particular group. If more blocks are freed, they are kept in the free block list at the file level.
Refer to UniData configuration parameters, on page 381 for a list of the configuration parameters.
If you remove all records from a dynamic file with either the ECL CLEAR.FILE command or the ECL
DELETE command with the ALL option, the file returns to its minimum modulo, and the disk space
is returned to UNIX. However, if you remove all records from a dynamic file using a select list, the file
may not return to its minimum modulo. Depending on the order in which records are removed, some
groups resulting from earlier splits may not become eligible for merging even though they do not
contain any records.

UNIX example
The following screens show splitting and merging in a dynamic file. The first example shows creating a
dynamic file with a minimum modulo of 3:

Notice the following points:

▪ Because the file was created with a block size multiplier of two, the size of each block is 2,048
bytes.
▪ The primary file (dat001) has one block for the file header, and three for the data.
▪ The overflow file (over001) is initially allocated one block for its header.
▪ Because the split/merge type was not specified, the file was created as a KEYONLY file.
The next screen shows what happens when the dynamic file is populated with records:

129
Chapter 10: Managing UniData files

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 the
overflow file.
The following screen shows the results of deleting all records with a SELECT list:

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.

130
 Dynamic files and disk space

The final screen shows the results of CLEAR.FILE:

The ECL CLEAR.FILE command returns the file to its original modulo and size.

Windows example
The following screens show splitting and merging in a dynamic file. The first example shows creating a
dynamic file with a minimum modulo of 3:

131
Chapter 10: Managing UniData files

Notice the following points:

▪ Because the file was created with a block size multiplier of two, the size of each block is 2,048
bytes.
▪ The primary file (dat001) has one block for the file header, and three for the data.
▪ The overflow file (over001) is initially allocated one block for its header.
▪ Because the split/merge type was not specified, the file was created as a KEYONLY file.
The next screen shows what happens when the dynamic file is populated with records:

132
 Dynamic files and disk space

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 the
overflow file.
The following example shows the results of deleting all records with a SELECT list:

133
Chapter 10: Managing UniData files

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 previous
example.
▪ Some groups did not merge, and the groups that were added remain allocated to the file.
The final example shows the results of CLEAR.FILE:

134
 Sequentially hashed files

The ECL CLEAR.FILE command returns the file to its original modulo and size.

Sequentially hashed files

A sequentially hashed file has the same structure as a dynamic file, but all records are stored
sequentially based on the primary key. The modulo (number of groups) for a sequentially hashed file is
fixed, it does not grow and shrink as records are added or deleted.
You create a sequentially hashed files by converting from existing UniData static or dynamic files.
You specify a percentage of the file that you want to remain empty to allow for growth. Although the
structure for a sequentially hashed file is the same as a dynamic file, the modulo is fixed.
A sequentially hashed file is used for files where the majority of access is based on the primary key.

• The dat001 file

The dat001 file is also called the primary data file.
• The over001 file
As you add records to a sequentially hashed file, whenever the space reserved for data in a group in
the primary file gets too full, UniData writes the excess data into blocks in over001.
• The gmekey file

135
Chapter 10: Managing UniData files

Each sequentially hashed file contains a static, read-only file that is called the gmekey file.

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 data overflows the group (level 1 overflow), UniData writes
the overflow data to the over001 file.

Parent topic: Sequentially hashed files

The over001 file

As you add records to a sequentially hashed file, whenever the space reserved for data in a group in
the primary file gets too full, UniData writes the excess data into blocks in over001.
Registers within UniData track how blocks in over001 are linked to groups in dat001. If over001
gets too large, UniData adds more blocks to it. If the current file system becomes full, or over001
grows larger than a UniData limit, UniData creates an over002 file. If the over002 file resides
in a different file system than the over001 file, UniData creates a link to over002 in the original
sequentially hashed file.
If the sequentially hashed file has level 2 overflow, the file should be rebuilt by using the shfbuild
command.

Parent topic: Sequentially hashed files

The gmekey file

Each sequentially hashed file contains a static, read-only file that is called the gmekey file.
This file is read into memory when you open a sequentially hashed file. The gmekey file contains
information about the type of keys in the file (alphabetic or numeric), and controls which group a
record is hashed to when it is written.
You create a sequentially hashed file by converting an existing dynamic or static file with the
shfbuild command.

Syntax
shfbuild [-a |-k] [-n | -t] [-f] [-e empty percent] [-m modulo] [-b
block size multiplier] [-i infile] outfile

Parameters
The following table describes the shfbuild options.

Parameter Description
-a Only rebuild the last group of the sequentially hashed file. UniData splits the
last group into groups according to the records in the group. If you use this
option, the outfile should be the name of the sequentially hashed file. Do not
specify infile.
-k Build the gmekey file only. If you use this option, outfile should be the name of
the sequentially hashed file. Do not specify infile. UniData rebuilds the gmekey
file according to the keys in each group of outfile.

136
 DIR-type files (Windows only)

Parameter Description
-n/-t Force the outfile to be in numeric or alphabetic order. By default, the order
of outfile is determined by the infile primary key type. If infile is a sequentially
hashed file, UniData uses the same order in outfile. If infile is not a sequentially
hashed file, the order of outfile is determined by the justification of the @ID of
the infile dictionary record. If it is right-justified, it is numeric. Otherwise, it is
alphabetic.
If you use the -a or the -k option, these options have no effect.
-f Force outfile to truncate before 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 the new modulo
of the file from empty_percent and the number of records in the rebuilt groups.
If you do not specify -e or -m, UniData rebuilds the sequentially 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 in
the following example:
% shfbuild -m 59 SEQUENTIAL
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 VOC
file in order to access the sequentially hashed file, as shown in the following example:
:AE VOC SEQUENTIAL
Top of New "SEQUENTIAL" in "VOC".
*--: I
001= F
002= SEQUENTIAL
003= D_SEQUENTIAL
*--: FI
Filed "SEQUENTIAL" in file "VOC".

Parent topic: Sequentially hashed files

DIR-type files (Windows only)

A UniData DIR-type file is an NTFS directory that contains NTFS text or data files. Each NTFS text or
data file is a UniData record.
The BP file, a UniData file that stores UniBasic source files and compiled programs, is a DIR-type file.
The following example shows the structure of a sample BP file:

137
Chapter 10: Managing UniData files

In the example, MAINPROG and SUBR are UniBasic source files. _MAINPROG and _SUBR are compiled
programs.
The following DIR-type files are available:

• Multilevel files (MULTIFILES) (Windows only)

A UniData multilevel (LF type) file is an NTFS directory that contains one or more UniData hashed
files.
• Multilevel directory files (Windows only)
A UniData multilevel directory (LD) file is an NTFS directory. T

Multilevel files (MULTIFILES) (Windows only)

A UniData multilevel (LF type) file is an NTFS directory that contains one or more UniData hashed files.
All of the UniData hashed files share a common dictionary. To access a record, you must specify both
the directory and the hashed file where the record is located. The following screen shows an example
of a multilevel file:

138
 Multilevel directory files (Windows only)

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

Remember the following points about multilevel files:

▪ A UniData multilevel file is an NTFS directory that contains UniData hashed files.
▪ Each multilevel file might 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. The multilevel
structure allows a number of data files to share a single dictionary. However, multilevel files are
less efficient than ordinary static or dynamic files. The leveled structure means that more system
resources are needed to read and update these files. For this reason, we recommend that you
use ordinary static or dynamic hashed files rather than multilevel files whenever possible. You
can share a single dictionary between UniData files by modifying the VOC entries for each file to
reference the same dictionary.

Parent topic: DIR-type files (Windows only)

Multilevel directory files (Windows only)

A UniData multilevel directory (LD) file is an NTFS directory. T
he NTFS directory contains one or more NTFS subdirectories (UniData DIR type files). All of the DIR
files share the same dictionary. To access a record, you must specify both the multilevel directory file
and the DIR file where the record resides. The following example shows characteristics of a multilevel
directory file:

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

Remember the following points about multilevel directory files:

139
Chapter 10: Managing UniData files

▪ A UniData multilevel directory file is an NTFS directory that contains UniData DIR files (NTFS
subdirectories).
▪ All of the DIR files in a multilevel file share the same dictionary.
▪ Each record in a multilevel directory is an NTFS file.
▪ UniData supports multilevel directory files to simplify conversion for legacy applications. However,
multilevel directory files are less efficient than ordinary DIR files. The leveled structure means that
more system resources are needed to read and update these files. For this reason, we recommend
that you use ordinary DIR files rather than multilevel directory files whenever possible. You can
share a single dictionary between UniData DIR files by modifying the VOC entries for each file to
reference the same dictionary.

Parent topic: DIR-type files (Windows only)

Index files and index log files (Windows only)

UniData creates an index file whenever you create the first alternate key index on a UniData hashed
file. Index information is stored in B+ tree format. UniData index files are NTFS data files.

Note: Regardless how many alternate key indexes users create for a data file, UniData creates a
single index file.

The ECL CREATE.INDEX command creates the index file. The ECL BUILD.INDEX command
populates the index. DELETE.INDEX (with the ALL option) removes the index file.
By default, each time you update a UniData data file, its associated indexes are updated at the
same time. You can turn off automatic indexing on one or more data files (by using the ECL
DISABLE.INDEX command) to speed performance during periods of heavy activity on your system.
If you turn off automatic indexing, UniData stores all index updates in an index log file. The ECL
UPDATE.INDEX command applies updates from index logs to indexes in batch mode, and the ECL
ENABLE.INDEX command turns automatic updating back on. The ENABLE.INDEX command also
creates an index log file if one is not already there. DELETE.INDEX (with the ALL option) removes the
index log file.
For additional information about index handling commands, see the UniData Commands Reference.

• Index-related files for a static hashed file (Windows only)

For a static hashed file, UniData creates both the index file and the index log file in the account
directory with the data file.
• Index-related files for a dynamic hashed file (Windows only)
For a dynamic hashed file, UniData creates both the index file and the index log file in the dynamic
file directory itself.

Index-related files for a static hashed file (Windows only)

For a static hashed file, UniData creates both the index file and the index log file in the account
directory with the data file.
The following example shows a sample account where a static file named STATIC.TST has been
indexed:

140
 Index-related files for a dynamic hashed file (Windows only)

X_STATIC.TST is the index file for the data file STATIC.TST, and L_STATIC.TST is the index log
file.

Parent topic: Index files and index log files (Windows only)

Index-related files for a dynamic hashed file (Windows only)

For a dynamic hashed file, UniData creates both the index file and the index log file in the dynamic file
directory itself.
The following example shows the structure of the ORDERS file in the demo database after an index is
created on the file:

Notice that the index and index log files are located in the dynamic file directory rather than in the
account. The file idx001 is the index file, and xlog001 is the index log file.

Note: A dynamic hashed file can have more than one idx file. The same configuration parameter
(MAX_FLENGTH) that limits the size of a dat or over part file limits the size of index files. When the
size of an index file (for instance, idx001) reaches MAX_FLENGTH, UniData creates the next index
file (for instance, idx002).

Parent topic: Index files and index log files (Windows only)

141
Chapter 10: Managing UniData files

File-handling commands
UniData includes a variety of commands for you to create and delete UniData files, as well as to obtain
status information, change file parameters, and diagnose and repair damaged hashed files.

Note: Refer to UniData and the UNIX file system (UNIX only), on page 326 for additional
information about index files and index log files.

The following table describes ECL file-handling commands, and indicates the UniData file types they
affect.

Command Description
CREATE.FILE Creates a UniData file; works for static and dynamic hashed files, dictionary
files, DIR files, multilevel files and multilevel directories.
DELETE.FILE Deletes a UniData file; works for static, dynamic, and sequentially hashed
files, dictionary files, DIR files, multilevel files, and multilevel directories.
CLEAR.FILE Removes all records from a UniData file; works for static, dynamic, and
sequentially hashed files, dictionary files, DIR files, multilevel subfiles, and
multilevel subdirectories.
CNAME Changes the name of a UniData file; works for static, dynamic, and
sequentially hashed files and DIR files. Does not work for multilevel subfiles
and multilevel subdirectories or dictionary files.
SETFILE Sets a pointer to a UniData file; works for static, dynamic, and sequentially
files, DIR files, multilevel files, and multilevel directories. Does not work for
dictionary files or for multilevel subfiles or subdirectories.
RECORD Identifies group where a primary key is hashed, and displays a list of keys
hashed to that group. Works for static, dynamic, and sequentially hashed
files and for multilevel subfiles. Does not work for dictionaries, directory
files, multilevel directories, or multilevel subdirectories.
FILE.STAT Displays statistics about a hashed file, including modulo, block size, hash
type, and record statistics. Works for static, dynamic, and sequentially
hashed files, or static or dynamic multilevel subfiles. Does not work
for dictionaries, directory or multilevel directory files, or multilevel
subdirectories.
GROUP.STAT Displays record distribution in a UniData hashed file. Works for static,
dynamic, or sequentially hashed files, or static or dynamic multilevel
subfiles. Does not work for dictionaries, directory or multilevel directory
files, or multilevel subdirectories.
RESIZE Changes the modulo, block size, or hash type of a UniData static hashed
file. Works on static hashed files, static hashed multilevel subfiles, or
dynamic files. Does not work on directories, multilevel directories or
subdirectories, or dictionaries.
ANALYZE.FILE Displays statistics, including current and minimum modulo, hash type,
block size, split/merge type, split load, merge load, and record distribution
for a dynamic file. Works on dynamic and sequentially hashed files and
dynamic hashed multilevel subfiles only.
CONFIGURE.FILE Changes split/merge type, split load, merge load, part table, or minimum
modulo for a dynamic file. Works on dynamic hashed files and dynamic
hashed multilevel subfiles only.

142
 File-handling commands

Command Description
REBUILD.FILE Reconstructs a dynamic file using current settings for split load, merge load,
and minimum modulo. Used after CONFIGURE.FILE. Works on dynamic
hashed files and dynamic hashed multilevel subfiles only.
CHECKOVER Checks UniData hashed files for level 2 overflow. Works on all UniData
hashed files and subfiles. Used to check all files in a UniData account
directory.

See the UniData Commands Reference for detailed information about the syntax of file-handling
commands.
The next table describes UniData system-level file-handling commands.

Command Description
auditor UNIX only. Checks all dynamic files in a UniData account to report
inconsistencies between symbolic links, part file locations, and file prefix
tables.
checkover Checks UniData hashed files for level 2 overflow. Works on all UniData
hashed files and subfiles. Checks all files in a UniData account directory.
You can execute the system-level version with UniData shut down or with
UniData running.
dumpgroup Unloads the contents of a damaged group in a hashed file; you can execute
with UniData shut down or with UniData running. Does not work with EDA
files.
fixfile Repairs damaged groups in a file; you can execute with UniData shut down
or with UniData running. Does not work with EDA files.
fixgroup Repairs a damaged group; you can execute with UniData shut down or with
UniData running. Does not work with EDA files.
fixtbl UNIX only. Resolves inconsistencies between symbolic links and file prefix
tables for all dynamic files in a UniData account. You must execute with
UniData shut down.
guide Identifies damaged hashed files or dictionary files. You cannot execute if
UniData is shut down. Does not work with EDA files.
guide_ndx UNIX only. 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, multilevel directories or
subdirectories, or dictionaries. This command uses shared memory and
disk storage, rather than disk storage alone, as working storage.
Although you execute this command from a the operating-system level on
UNIX or an MS-DOS window on Windows, you cannot execute it if UniData is
shut down. memresize also converts static files to dynamic files, dynamic
files to static files, and changes the split/merge type and part table for
dynamic files.
mvpart UNIX only. Moves a part file from one location to another, keeping links,
location, and file prefix tables consistent. You must execute with UniData
shut down.
shfbuild Converts a static or dynamic file to a sequentially hashed file.

143
Chapter 10: Managing UniData files

File corruption
File corruption is damage to the structure of a file. UniData file management tools diagnose and
repair problems that occur if invalid, unreadable, or inconsistent information is written to file or group
headers.
Such invalid information can result in UniData being unable to access part or all of the data in the file.
UniData provides a series of utilities that allow you to detect and repair damaged files.

Note: UniData file tools do not detect or repair invalid or inconsistent data in files. Detecting data
inconsistencies should take place at the application level.

File corruption can result from a variety of causes:

▪ Hardware failures, including CPU crashes, media or memory failure, controller failures, bad spots
on a disk.
▪ Interrupting a write in progress; for example, terminating a UDTelnet Service while users are still
logged on to the system, or killing a UniData process using a UNIX kill -9 command.
▪ Incomplete writes; for example, a disk runs out of space before a write is complete. This is a rare
condition, since UniData prompts the user to reclaim space when this occurs.

Note: Overflowed files are more likely to become corrupted, since multiple I/O operations can
be required to accomplish a single read or write to an overflowed file. An interrupted write can
result in a condition where a primary data block and corresponding overflow blocks are out of
synch. The increased chance of corruption is particularly significant for files in level 2 overflow.

Preventing file corruption

You can reduce the possibility of file corruption by sizing your files to minimize overflow. Level 1
overflow can leave incomplete records in a file, although all the IDs are available. Level 2 overflow
can cause more severe data problems because IDs and data can be lost. We strongly recommend
that you monitor and minimize level 2 overflow. Using dynamic files versus static files minimizes level
2 overflow, which provides some protection. However, using dynamic files greatly increases level 1
overflow, making the risk of file corruption greater than that for static files.
Certain UniData commands carry a direct risk of file corruption, as shown in the following table.

Command Risk factor

deleteuser On UNIX, 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.
On Windows, this UniData command first tries to gracefully terminate a
process. If unsuccessful, deleteuser forces the process to terminate.
stopud -f This syntax of the stopud command does not allow writes to complete
before logging users off.

There are other operations that can corrupt UniData files. The following list contains some examples:
▪ Using UNIX file manipulation commands (for example, rm, mv, cp, and ln) on UniData hashed
files while UniData is running can damage files. You should always shut UniData down before
performing any UNIX-level manipulations on UniData files.

144
 UniData detection tools

▪ Stopping the UniData for Windows 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 file
whether or not UniData is running. In many cases, the file damage is irreversible.
▪ Backing up and restoring a UniData file (for example on UNIX, with the tar, dd, and cpio
commands) while users are accessing the file during backup can damage the restored file. Any
UniData file can be damaged in this way, but the risk is particularly great for dynamic files.

Note: The file being backed up is not damaged. Danger is only to the file being restored.

▪ Using system-level maintenance tools (for example, online file checking, which is supported under
some UNIX versions) can damage a file, although this is not a common cause of corruption.

UniData detection tools

UniData supplies the following tools for detecting damaged files:
• guide
guide is a UniData-supplied, system-level utility that provides detailed statistics and suggestions
for optimizing file size and ensuring data integrity.
• guide_ndx
As with other UniData file types, an index file could become corrupt due to hardware failures, the
interruption of a write to the index file, or an incomplete write. The guide_ndx utility checks for
physical and logical corruption of an index file.

guide
guide is a UniData-supplied, system-level utility that provides detailed statistics and suggestions for
optimizing file size and ensuring data integrity.

Note: If you do not want the guide utility to report orphan blocks, set the value of the
SUPPRESS_ORPHAN_BLOCK_ERROR to a positive integer.

Syntax
guide [file1, file2,...][-options]

Note: You can supply guide with the name of a single UniData file or a series of file names
separated by commas or spaces. If you do not specify any files, guide processes all files in the
current UniData account directory. However, guide does not work with EDA files.

Parameters
The following table lists the parameters available for the guide command.

145
Chapter 10: Managing UniData files

Parameter Description
-a |-A [filename] Controls whether UniData includes management advice in
the output. The default filename for the advice information is
-na | -NA
GUIDE_ADVICE.LIS. You cannot combine the -a and -o options,
(no advice) because UniData assumes the -a option when the -o (output) option is
present. You may use the -na option in combination with the -o option.
-b | -B [filename] Controls whether UniData produces a file containing a brief summary
of statistical information. The default file name is GUIDE_BRIEF.LIS.
-nb | -NB
(no brief statistics — this is
the default)
-d1 | -D1 Includes minimum statistics about the file. Does not work with the -ns
option.
-d2 | -D2 Includes statistical information helpful in estimating correct file sizing.
This is the default. Does not work with the -ns option.
-d3 | -D3 Includes all information reported with -d2, plus additional information
about distribution of data sizes. Does not work with the -ns option.
-e | -E [filename] Controls whether guide produces a report of structural errors in the
selected files. The default error list file name is GUIDE_ERRORS.LIS. The
-ne | -NE
-e option is assumed when the -o (output) option is present, and may
(no errors) not be specified at that time. You may, however, use the -ne option in
combination with the -o option.
-f | -F [filename] Specifies the file that should receive a list of damaged groups. The
default file name, if none is specified, is GUIDE_FIXUP.DAT. UniData
creates this file only if it detects errors.
-ha | -HA Evaluates all hash algorithms (default). Note: the -h option has no
effect if specified for a dynamic file.
-h0 | -H0 Evaluates algorithm 0. Note: the -h option has no effect if specified for
a dynamic file.
-h1 | -H1 Evaluates algorithm 1. Note: the -h option has no effect if specified for
a dynamic file.
-i | -I [filename] Directs the guide utility to evaluate all of the files in the file named
filename. GUIDE_INPUT.DAT is the default. The file should be
composed of one file name per line. UniData treats blank lines and
lines that begin with an exclamation point as comments.
-l | -L [count] If you specify the -d3 option, the guide utility displays the keys for the
largest records. The key appears in quotes and, if truncated, is followed
by an asterisk (*). The -l option controls the number of records that
display. The default value is three. Specifying a large number of records
results in a significantly slower analysis.
-m | -M Directs the utility to evaluate the effects of a different modulo upon the
specified file. You must use this option in conjunction with the -h (hash
new_modulo
test) option. This option has no effect when specified for a dynamic file.
-o | -O [filename] Controls whether output is combined or directed to separate files. If -o
is specified, UniData directs all output to the file specified by filename.
If you do not specify a file name, UniData directs the output from
guide to “standard out” (usually, your terminal).
-Z num_child_processes UNIX only. Defines the number of concurrent processes to use when
analyzing the file. The default is 4. If the file guide is analyzing has less
than 100 groups, guide only uses one process.

146
 guide

Parameter Description
-p | -P page_length Controls the display of guide output when you specify the -o option
and directs output to the terminal. Specify -np to scroll the output past
-np | -NP
with no pause. Specify -p page-length to pause after displaying each
(no pagination) page and prompt with the following message:
Press RETURN to continue...
The following responses are accepted at the prompt:
<RETURN> to display the next page.
“N” to continue with no pauses.
“Q” to quit the application.
page_length is the number of lines per page in the screen display. The
default value is 24.
-r | -R [filename] Specifies whether to produce a reporting file. The filename must be the
UNIX file specification of a UniData database file, previously created
by the CREATE.FILE command. Use this option to generate file
statistics reports using UniQuery. Copy a dictionary for the report file
from udthome/sys/D_UDT_GUIDE.
-s | -S count If you specify the -d3 option, the guide utility displays the keys for
the smallest records. UniData displays the key in quotes. If the key
is truncated, it is followed by an asterisk (*). The “-s count” option
controls the number of records to appear in sorted order. The default
value is three. Large values result in a significantly slower analysis.
-s | -S [filename] Controls whether UniData includes statistical information about the
file in the output file. If you do not specify a filename, UniData uses
-ns | -NS
GUIDE_STATS.LIS. (UniData assumes the -s (statistics) option when
(no statistics) the -o (output) option is present, and may not be specified at that
time.) You may use the -ne (no errors) option in combination with the -
o option.

Output
The guide utility can create five output files. The following table lists these files. You can change the
default names.

File Description
GUIDE_ADVICE.LIS Displays management advice about files that are poorly sized or
corrupted.
GUIDE_ERRORS.LIS Lists structural errors detected in the files specified.
GUIDE_STATS.LIS Lists statistical information about the files specified.
GUIDE_BRIEF.LIS Displays summary information about selected files, including record
counts, total size, used size and modulo.
GUIDE_FIXUP.DAT Produces a list of damaged groups that can be used as input for
fixfile. You can also use this list to input file names/group numbers
for dumpgroup/fixgroup.

If you do not specify options, UniData selects the default options: -a, -e, -f, and -s, and places the
results in the default files.
The guide utility checks for existing output files. If there are existing output files, guide appends
a six-digit timestamp to the end of the existing file before it creates the current output file. The most
current output files will not have this time stamp. UniData does not overwrite output files generated

147
Chapter 10: Managing UniData files

in a previous analysis. As a result, you might accumulate a large number of files that will need to be
purged periodically.

Report file
You can use the -r option of guide to create a UniData file containing statistical information about
your database. To use the option, complete the following steps:
1. Create a UniData file in the account where are running guide.
2. Copy the records from udthome/sys/D_UDT_GUIDE to the dictionary of the file you created in
step 1.
3. Execute guide -r filename where filename is the UniData file you created in step 1.
The guide utility creates statistical information in filename about the evaluated files. The records
contain 62 attributes and are keyed by VOC entry name. You can use UniQuery or ECL commands, or
write UniBasic code, to analyze the data and produce reports.

Example
The following example shows output from guide executed against a directory that contains a
damaged file:

Notice that group 1 of TEST.FILE is damaged.

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 guide
during recovery from a system or media failure.

Parent topic: UniData detection tools

Using guide
Complete the following steps to effectively using the guide utility.
You should execute guide against your database at regular intervals, as well as when you have had a
system crash. You can set up shell scripts to run guide at specified intervals on specified lists of files,
or you can simply execute the guide command in each UniData account. You can execute guide

148
 guide_ndx

against nonrecoverable static hashed files at any time, and schedule guide to run on dynamic files
and recoverable files at a time when the system is idle or only lightly loaded.

1. Monitor the file integrity regularly using guide.

2. Check the error output (GUIDE_ERRORS.LIS).
If there are no errors, proceed to step 7.
An error similar to the following is a partially allocated block message:
free block xx partially allocated, xxx bytes remaining
Block xx of primary file not a member of any group
Partially allocated block messages are not false error reports; they indicate an out-of-synch
condition in a dynamic file, but they do not mean that the file must be fixed immediately. Users
can continue to access the file; this will not cause damage. Complete the repair at a convenient
time using the procedure in step 3.
guide produces many messages besides the one discussed previously. If you see error messages
pertaining only to static files, or if you see other error messages pertaining to dynamic files,
proceed to step 3.
3. Back up the damaged files so if a system failure occurs, you will be able to restore from the
backup copies and repeat the procedures, rather than attempting to recover a partially-
completed repair.

Caution: Do not allow users to access your files while you are backing them up.

4. Repair the damaged groups. Execute either fixfile or dumpgroup/fixgroup to repair

the damaged groups. In either case, the process overview is: dump the readable records from a
damaged group, clear the group, and then reload all readable records back into the group.

Warning: Be sure no users are accessing your files before repairing damaged groups. The
dumpgroup command does not obtain exclusive access, and fixfile/fixgroup only lock
the file when the records are being written back to a group. Concurrent access to the file could
make corruption worse.

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, you
may encounter additional errors if you do not clear the group. Use fixfile or fixgroup
without -k; this procedure automatically clears the group before reloading the readable
records.

5. Rerun guide after the repair is complete to verify that the errors are fixed. If they are not, or if
additional groups are damaged, repeat the previous step.
6. Back up any files you have just completed repairing.
7. Continue processing. If you shut UniData down to repair files, start it again before allowing users
to log in to the system.

guide_ndx
As with other UniData file types, an index file could become corrupt due to hardware failures, the
interruption of a write to the index file, or an incomplete write. The guide_ndx utility checks for
physical and logical corruption of an index file.

149
Chapter 10: Managing UniData files

Syntax
guide_ndx{-x | -X} {1 | 2 | 3}, {index_names, ... | ALL} [-t template |
-T template] filename

If an index file is corrupt, UniData displays a runtime error when a UniData process tries to access the
index. If the index file is associated with a recoverable file, a message is written to the sm.log.
The guide_ndx command creates two files, the GUIDE_XERROR.LIS and the
GUIDE_STATS.LIS. GUIDE_ERROR.LIS lists any corruption found in the index file, and
GUIDE_STATS.LIS list statistics about the index. If you have a corrupt index, you must rebuild it
using the CREATE.INDEX and BUILD.INDEX commands. For more information and creating and
building indexes, see Using UniData.

Note: We recommend deleting the index with the DELETE.INDEX ALL command. Using the ALL
option deletes all alternate key indexes and the index file itself.

Parameters
The following table describes each parameter of the syntax.

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 checking
index_names The index names you want guide_ndx to check. Separate each index
name with a comma, or enter ALL to check all indexes for the file.
-t template The template to use for output files. The default is GUIDE.
filename The name of the data file containing the index.

Example
The following example illustrates the contents of the GUIDE_XERROR.LIS file when guide_ndx
detects corruption:

150
 UniData recovery tools

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 key
indexes that are built on virtual attributes (V-type).

Parent topic: UniData detection tools

UniData recovery tools

UniData includes the following commands to recover corrupted hashed files:

151
Chapter 10: Managing UniData files

Note: Although dumpgroup, fixgroup, and fixfile work against UniData recoverable files,
their actions are not recoverable. If you are recovering from a system crash or media failure, any
file repairs that took place since your last backup are not included in logs or archives. You should
check your files after recovery (using guide) and perform any needed repairs before users access
them.

• dumpgroup
The system-level dumpgroup command unloads readable records from a group you specify in a
UniData file. If the file was corrupted, dumpgroup unloads complete, valid records, leaving behind
any information it cannot read.
• fixgroup
The system-level fixgroup command reloads a hashed file group based on a file created by the
dumpgroup command.
• fixfile
The system-level fixfile command repairs damaged groups in UniData files by clearing the
group, and optionally restoring readable records to the group.

dumpgroup
The system-level dumpgroup command unloads readable records from a group you specify in a
UniData file. If the file was corrupted, dumpgroup unloads complete, valid records, leaving behind
any information it cannot read.

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 this information to select
groups to process.
[-doutputfile] Specifies the name of a file that contains the readable records from the
dumped group, in an uneditable form. If you do not specify the -d parameter
with an outputfile, the output prints to screen. To load outputfile back into the
file, use fixgroup. Note:

Note: No space is allowed between -d and outputfile.

[-p] Converts non-printing 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 specify
an output file, UniData places the records in a form that cannot be edited, suitable for reloading, into
the output file. UniData also creates a UNIX directory within your current account for each dumped
group. The directory is named FILE_GROUP, where FILE and GROUP are the file name and group

152
 fixgroup

number you specify on the command line. This directory contains an ASCII file for each record, so that
you can check them for consistency before reloading the damaged file.

Warning: When you use the -d option, make sure you name your output file with a name that does
not already exist in your account name. If you specify a duplicate name, the preexisting file may be
overwritten.

Parent topic: UniData recovery tools

fixgroup
The system-level fixgroup command reloads a hashed file group based on a file created by the
dumpgroup 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 the specified group,
without reloading it.

Note: No space is allowed between -i and inputfile.

[-k] Allows fixgroup to reload the damaged records from inputfile without
zeroing the group first. This option may be useful if the group was updated
since dumpgroup was executed. However, for best results, do not allow
access to a file while it is being repaired, and clear the damaged groups
rather than using the -k option.

Warning: If you execute fixgroup without an input file argument, UniData clears the damaged
group. Be sure that you save the readable records with dumpgroup before clearing the group. If
you clear the damaged group and you have not saved the readable records, the data in that group
is lost.

The syntax for clearing a group without reloading it is:

fixgroup filename group.no
UniData displays a warning message before clearing the group, as shown in the following example:
Fixgroup INVENTORY 5 will make group 5 empty,
do you wish to do it ? [y/n]

Parent topic: UniData recovery tools

153
Chapter 10: Managing UniData files

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 guide utility. 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] [-ggroup_count]

Parameters
The following table describes each parameter of the fixfile syntax.

Parameter Description
{-t} UNIX only. Directs all output to the terminal only. Each readable
record is described in a new line that includes the record key and
the record length. All attributes in the record appear on separate
lines, each line indented by two spaces. Special and non-printable
characters are translated 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 used
together.
{-dfilename} A file specification is required. For static files, the readable records
are dumped to this file in an uneditable format. For dynamic files,
this file is created, but the actual records are dumped to a file in
\temp (Windows) or /tmp (UNIX).
With the -d option, UniData also writes the records, in readable
format, to a directory in your current UniData account. This directory
contains an ASCII file for each readable record in the group. The
records are in a format suitable for editing. To repair any file, you
need both the -d and -f options.
{-k} If you specify the -k option with the -d option, the damaged groups
are not cleared. This has the effect of dumping the readable records
for examination, but leaving the file corrupt. If you specify the -d and
-f option along with the -k option, UniData repairs the file and returns
the readable records to the group. Any unreadable records that were
not dumped remain in the file as well.
{-p} If you specify the -p option with the -d option, all non-printing
characters and characters with special meaning to UniData are
translated. This translation applies to the editable ASCII files created
by the -d option. If you do not specify the -p option, only attribute
marks are translated.

154
 How fixfile works with static files

Parameter Description
{-f} If you specify the -f option with the -d option, UniData clears the
damaged group and restores the records that were dumped back
into the group, creating a fixed file with all readable data restored.
You must specify the -d option with the -f option.
[-mfilename] UniData writes all error messages and statistics to the file you
specify, instead of the terminal.
[-wdirectory] UniData creates the work files that are generated in the directory you
specify.
{-ifilename} UniData uses this file as the source of the names of damaged files
and groups to be repaired. If you do not use this option or the
{filename group_no} option, UniData uses the GUIDE_FIXUP.DAT
file under the current directory. This option is mutually exclusive with
{filename group_no}.
{filename group_no} The file name and group number that contains the corruption. If you
do not use this option or the {-ifilename} option, UniData uses the
GUIDE_FIXUP.DAT file under the current directory. This option is
mutually exclusive with the {-ifilename} option.
[-ggroup_count] The group_count variable is the number of groups specified by the
user. UniData uses the number specified in the -ggroup_count option
as the new number of groups to process in one loop of fixfile.
If no -ggroup_count option is specified, fixfile processes 500 groups
per loop by default. Previously, 100 groups per loop were processed.

Parent topic: UniData recovery tools

How fixfile works with static files

When you run fixfile with the -t option on a static file, UniData displays the readable records from
the file and group to the terminal. The group is not cleared or repaired. You can supply the names
of damaged files and groups from the command line or from an input file. The default input file is
GUIDE_FIXUP.DAT.
When you run fixfile with -dfilename on a static file, UniData creates:

155
Chapter 10: Managing UniData files

▪ An NTFS (Windows) or UNIX directory or directories for the files and groups being repaired. If only
one group in a file is damaged, the directory is named FILE_GROUP where FILE is the damaged file
(from GUIDE_FIXUP.DAT) and GROUP is the damaged group. If several groups in a file are damaged,
UniData creates a directory named FILE_dir.
▫ Each FILE_GROUP directory contains an ASCII file for every readable record in the damaged
group. Each file name is the key for the corresponding UniData record. These records are in a
format suitable for editing.
▫ Each FILE_dir contains a subdirectory for each damaged group in FILE. The name of each
subdirectory is the group number of the damaged group. Each subdirectory contains an
ASCII file for every readable record in the damaged group. Each file name is the key for the
corresponding UniData record. These records are in a format suitable for editing.
▪ A file, with the name you specify on the command line, that contains the records fixfile could
read, in uneditable format. UniData uses this file to reload the records into the damaged groups
after the groups are cleared.

Note: If you specify the -p option, fixfile translates non-printing characters in the records
when 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 the
damaged groups, taking them from the file you specify on the command line. Unless you specify the -
k option, fixfile clears the groups, removing all contents, before reloading the data. If you specify
the -k option, UniData adds the records back, but does not clear any data from the group.

Note: It is possible to run fixfile in two steps, one to dump the records for review and the
second to repair the file. To dump the records only, run fixfile with the -d option, but without
the -f option. Unless you specify the -k option, running fixfile with the -dfilename deletes the
readable data from the specified groups when it creates output. To repair the file, run fixfile
with both -d and -f options.

How fixfile works with dynamic files

When you execute fixfile with the -d option on a dynamic file, UniData creates the following:
▪ An NTFS (Windows) or UNIX directory for each file-group combination being repaired. The
directories are named FILE_GROUP, where FILE is a damaged file (from GUIDE_FIXUP.DAT) and
GROUP is a damaged group. If several groups in a file are damaged, UniData creates a directory for
each damaged group.
▪ Each FILE_GROUP directory contains an ASCII file for every readable record in the damaged group.
Each record name is the key for the corresponding UniData record. These records are in a format
suitable for editing.
▪ A file containing the records fixfile could read, in uneditable format suitable for reloading
into the group after it has been cleared. This file is located in the directory identified by the TMP
environment variable and is named ud_dp_pid, where pid is the process ID of the process that
executed fixfile.

Note: If you specify the -p option, fixfile translates non-printing characters in the records
when it creates the editable files. Otherwise, UniData only translates attribute marks to new
lines.

When you run fixfile with the -d and -f options on a dynamic file, UniData reads the file you
specify with the -d option on the command line, and also reads the uneditable file of dumped records.
UniData then reloads the records from that file into the damaged groups. Unless you specify the -

156
 Detection and repair examples

k option, fixfile clears the groups, removing all contents, before reloading the data. Otherwise,
UniData adds the records back, but does not clear any data from the group.

Note: You can run fixfile in two steps, one to dump the records for review and the second to
repair the file. To dump the records for review, run fixfile with the -d option, but without the
-f option. (You do not need to use -k for dynamic files. For dynamic files, running fixfile with -
dfilename and not -f does not delete the readable data from the groups you specify when it creates
output.) To repair the file, run fixfile with both the -d and -f options. If you specify the same file
name with -d in both the review and repair steps, UniData will prompt whether or not to clear the
damaged groups.

Detection and repair examples

The following screens display UNIX and Windows examples.

UNIX example
The following example shows a file called TEST.FILE being repaired using guide and fixfile:
# guide TEST.FILE -na -ns
# more GUIDE_ERRORS.LIS
TEST.FILE
File Integrity:
Group 4, block 5 bytes left 842 is wrong.
Group 4, block 5, record number 0 = "10055"
record length of 58 is wrong.
Group 4, block 5 bytes used 58 and bytes left 842 are inconsistent
Files processed: 1
Errors encountered: 3
# more GUIDE_FIXUP.DAT
TEST.FILE
4
#
# fixfile -dhold -f
1:grpno error in U_blkread for file '/users/claireg/TEST.FILE', key '',
number=3
1:U_blkread error in U_catch_tuple for file '/users/claireg/
TEST.FILE',
key '10055', number=3
the 0th record may be damaged,key='10055',length=0.
**** Record Key='10055', Record length=1
1 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.
#

Windows example
The following example shows typical output from running guide against a damaged file:

157
Chapter 10: Managing UniData files

The output displays statistics and then reports which groups are damaged. In this case, group 1 is
damaged.
The next example shows the output from dumping the records from the damaged group with
dumpgroup:

You can review the directory CLIENTS_1, containing a file for each record that was dumped from group
1. Verify that the data in each record is valid. The following example shows the output from rebuilding
the damaged group with fixgroup:

158
 Detection and repair examples

The following examples show a damaged CLIENTS file and a damaged TESTFILE being repaired by
using guide and fixfile. The first screen shows output from guide:

159
Chapter 10: Managing UniData files

Error messages
This section lists error messages you might see and provides information about the meaning of them.
UniData generates these messages from the guide command.

160
 File access messages

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 files
Unable to lock dynamic file 'filename'
All of these messages indicate that guide did not process the file because it was unable to obtain an
exclusive lock on the file.

Note: These messages display only at the terminal. They are not logged in any file.

Block usage messages

Block usage messages are similar to the following example:
Group xx, block xx is pointed at by multiple links
The xxth block, grpoff=xx is pointed at by multiple links
In file, 'filename', the xxth group, grpoff=xx, have hit by other
links.
These indicate that a block is found to be referenced by more than one link, which should not occur.
These messages indicate damage.
The xxth block of file (filename) has no link.
the xxth block has no link
A block has been found that is not in the global free chain and is not used by any group. This error can
be reported when guide encounters a corrupt block, and is therefore unable to check blocks linked
through the corrupted one.

Group header messages

Group header messages are similar to the following example:
Group xx, block xx, invalid flags xx, should be an overflow
header block
Group xx, block xx, invalid flags xx, should be a normal header
block
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 of
keys xx
Group xx, block xx key area is corrupted, incorrect key size xx
Group xx, block xx key area is corrupted, data position xx, key
size xx number of keys xx
Group xx, block xx key area is corrupted, total key length xx,
key size xx, number of keys xx
keys xx in group header yy error
keysize=xx,keys=xx

161
Chapter 10: Managing UniData files

Bad 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 offset
next 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 offset
does not indicate an overflow file offset.
Group xx, block xx data area is corrupted, incorrect data
position xx
wrong datapos=xx
A data position in a group header is damaged.
Group xx, block xx, y number xx = y invalid offset xx or length
Group xx, block xx, y number xx = y offset occurs in wrong order
Group xx, block xx, y number xx = y offset error
Primary group xx, block xx has xx offset(s) less than the offset
of the group header
the bad length of the xxth key = xx
The xxth key='yy', keylen=yy, hashed to xx this group =xx,
modulo=xx
totalkeylen=xx,keysize=xx,keys=xx key area corrupted
the xxth key[] offset(yy) has wrong order
The xxth[] off_lens error,offset=yy,len=xx
This isn’t an overflow group, but there is xx offset:are xx
offsets less than the offset of group header
Each group header has an area that stores offset-record length pairs, which are sorted by offset.
Each offset equals the offset of the previous record plus its length. If these conditions are not met,
corruption results, and some or all of the previous messages display.
Group xx, block xx bytes used xx and bytes left xx are
inconsistent
Group xx, block xx has wrong number of bytes remaining
group header byteleft (xx) wrong
*key[xx] (key) record length xx wrong
file no in xxth key[] offset() not right
byteleft (xx) in blk(yy) wrong
byteused (xx) + byteleft (xx) in block (yy) error
The counter that records the number of bytes available in a block does not agree with the actual
number of bytes in the block.
Group xx, block xx, yy number xx=yy record length error xx
&key[xx] (key) record length (xx) wrong
The actual record length does not match the offset-length pair of the record.

Free block messages

Free block messages are similar to the following example:

162
 Long record messages

Group xx, free block count in group header (y) error, should
be xx
The actual count of free blocks for a group does not match the counter in the group header.
Group xx, free block xx partially allocated, xx bytes remaining
Group xx, free block xx has invalid flags xx
A block is linked to the free block list but not correctly initialized. Blocks linked to the free list should
have no bytes used and should be “normal” blocks (not header blocks).

Long record messages

“Long” records are records which span more than one block. Messages about problems with long
records look similar to the following example:
Group xx, block xx, y number xx =y invalid flags xx
Group xx, block xx, y number xx =y longrecord, nextoff(zz) error
Group xx, block xx, y number xx =y longrec: file no in nextoff
(zz) error
Group xx, block xx, y number xx =y invalid next offset xx
Group xx, block xx, y number xx =y record length error
blockflag for normal block(yy) error (xx)
&key[xx] () blockflag (xx) for longrec error
longrecord, byteleft(xx) error
long record, last block (yy) flag (xx) error.
In UniData hashed files, a long record always starts from the beginning of a level one overflow block,
which is flagged as “STARTLONG.” Each intermediate block is flagged as “MIDLONG,” and the last
block is flagged as “ENDLONG.” If the length of a long record does not match header information, or if
any flag in its data blocks is incorrect or the pointer in the chain gets broken, guide reports messages
like the preceding ones.

Dynamic file messages

Dynamic file messages are similar to the following examples:
Dynamic file messages are similar to the following examples:
Overflow file number too large
Primary file number too large
The part file number that is stored in a data block is invalid.
The next_block(xx) in overflow file header error
The next_block(xx) in free block (xx) is over filesize.
The offset to the next global free block list is wrong.
The free block offset xx too large in header block
The free block offset xx error in header block
Block(xx) is not a index free block
Free blocks count in header of file error (should be xx)
Global free block information has been damaged.
level 2 overflow: file no in nextover (xx) error
opfile (xx) in group header(yy) error.
Header information for overflow part files has been damaged.

163
Chapter 11: Managing UniData locks
This section outlines file, record, and system resource locking within UniData, describes tools for
listing locks and listing the contents of the wait queue, and describes procedures for releasing locks
that remain set when a process exits UniData.

The global lock manager

The Global Lock Manager (GLM) is an internal software module that is linked into each udt process to
manage logical record locks.
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 contain
linked 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 process
requests a lock, UniData first searches the local lock table for that udt to see if that process is holding
the lock, then the global lock table to see if another udt process is holding the lock.
Four udtconfig parameters exist that control the size of the shared lock table and the memory
UniData allocates for each memory request. The following table describes these parameters:

Parameter Description
GLM_MEM_ALLOC Windows only. Defines the number of lock nodes allocated for
each memory request, and is highly application dependent. If your
application requires a large number of locks in one transaction, this
setting should be increased to the maximum number of locks per
transaction *2.
GLM_MEM_SEGSZ The segment size for each shared memory segment required for
the lock manager. The maximum number of segments is 16. Large
application environments require a larger size. Each udt will register
the lock names it is locking in its per-process locking table. This table
is also organized as a hashed table.
GLM_MEM_SEGSZ must be greater than 4096 and less than
GLM_MEM_SEGSZ. The formula for determining GLM_MEM_SEGSZ
is NUSERS * maximum number of locks per transaction * 512.
GLM_MEM_SEGSZ should be a multiple of 4096.
N_GLM_GLOBAL_BUCKET The number of hash buckets system-wide used to hold the lock
names in shared memory. This setting directly affects performance.
Normally, the default value of this parameter should not be changed.
However, if you notice significant degradation in performance, or
your application intensively accesses specific files, you can increase
this parameter. The default value is the closest prime number to
NUSERS * 3.
N_GLM_SELF_BUCKET The number of hash buckets for the per-process locking table.
This parameter is highly application-dependent. If the application
requires a large number of locks in one transaction (more than 20),
you should increase this setting to the closest prime number to the
maximum number of locks per transaction.

164
 Locking in UniBasic

Locking in UniBasic
A series of UniBasic commands allow you to set read-only and exclusive locks on UniData files and
their contents.
UniBasic locks are advisory rather than physical, so they inform other users of a file or record that the
file or record is in use, rather than explicitly preventing access. You can set exclusive locks or shared
(read-only) locks.

Exclusive locks (U type)

Exclusive (U) locks are respected by all lock-checking commands except those commands that
write and delete. Exclusive locks are set by “U” commands, for instance READU, MATREADU, and
RECORDLOCKU.

Shared locks (L type)

Shared (or read-only) locks can be shared by more than one user. These locks are set by “L”
commands, for instance READL, MATREADL, RECORDLOCKL. A record that is locked with an L lock
can be accessed for reading by another “L” command, but cannot be accessed by “U” commands

Writing and deleting

WRITE and DELETE commands run regardless of lock status. WRITEU, WRITEVU, MATWRITEU, and
DELETEU retain locks set by previous commands. To prevent multiple updates to records, you should
precede all WRITE and DELETE commands by a lock-setting command like READU.

Locking commands
The following table lists UniBasic commands for setting and releasing locks.

Command Description
FILELOCK Locks the data or dictionary portion of a UniData file against access by
commands 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 the record.
MATREADU Assigns the values that are found in successive attributes of a record to
corresponding elements of a matrix, and sets an exclusive lock on the record.
MATWRITE Writes successive elements of a matrix to the corresponding attributes of a
record and releases locks previously set on the record.
MATWRITEU Writes successive elements of a matrix to the corresponding attributes of a
record without releasing locks that were previously set on the record.
READBCKL Retrieves one record from a B+ tree-based alternate key index and places
a read-only lock on the record. Each subsequent READBCKU retrieves the
previous record in the index.
READBCKU Retrieves one record from a B+ tree-based alternate key index and places
an exclusive lock on the record. Each subsequent READBCKU retrieves the
previous record in the index.

165
Chapter 11: Managing UniData locks

Command Description
READFWDL Retrieves one record from a B+ tree-based alternate key index and places a
read-only lock on the record. Each subsequent READBCKU retrieves the next
record in the index.
READFWDU Retrieves one record from a B+ tree-based alternate key index and places an
exclusive lock on the record. Each subsequent READBCKU retrieves the next
record in the index.
READL Reads a specified record from a file, assigning the record contents to a
dynamic array and setting a read-only lock on the record.
READU Reads a specified record from a file, assigning the record contents to a
dynamic array and setting an exclusive lock on the record.
READVL Reads a specified attribute of a specified record, assigning the attribute value
to a variable and setting a read-only lock on the record.
READVU Reads a specified attribute of a specified record, assigning the attribute value
to a variable and setting an exclusive lock on the record.
RECORDLOCKL Sets a read-only lock on a specified record in a specified file.
RECORDLOCKU Sets a read-only lock on a specified record in a specified file.
RELEASE Releases record locks without updating records.
WRITE Writes an expression to a record, releasing locks 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 locks
In both UniData and UniBasic, you can reserve a system resource by setting a semaphore lock on it.

Note: Certain device handling commands (T.ATT, T.DET, LINE.ATT, and LINE.DET) set
semaphore locks.

The following table lists commands for explicitly reserving system resources from the ECL prompt.

Command Description
UNLOCK Releases system resources that are reserved by the LOCK command. (These
resources are not automatically released when a program terminates.) This
command is not needed to release file and record locks.
LOCK (ECL and Reserves a system resource for exclusive use.
UniBasic)

Note: Although the LOCK and UNLOCK commands allow you to set and release semaphore locks,
UniData does not necessarily use system-level semaphores to control access to system resources.
The output from LIST.LOCKS and ipcstat may not appear to be consistent, but UniData is
functioning correctly.

166
 Listing locks

Listing locks
UniData offers three commands for listing record and file locks, semaphore locks on system resources,
and processes waiting to get locks.
• LIST.READU
The ECL LIST.READU command allows any user with access to the ECL prompt to display a list of
file and record locks set on the system.
• LIST.LOCKS
The ECL LIST.LOCKS command displays semaphore-type locks that reserve system resources for
exclusive use.
• LIST.QUEUE
The ECL LIST.QUEUE command displays a list of all processes waiting to get locks.

LIST.READU
The ECL LIST.READU command allows any user with access to the ECL prompt to display a list of file
and record locks set on the system.

Syntax
LIST.READU [user_number | ALL | FILENAME filename | 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, nothing
is displayed.
USERNAME user_name Displays all active locks that are associated with the user name you
specify.
DETAIL Displays detailed information.

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 set the lock.
UNBR The process ID of the user who set the lock.
UID The user ID of the user who set the lock.
UNAME The 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 UNIX only. The i-node of the locked file.

167
Chapter 11: Managing UniData locks

Column heading Description

DNBR UNIX only. Used with INBR to define the file at the operating system level.
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.

Examples
The following example illustrates the output from the LIST.READU command when you do not
specify any options:
:LIST.READU
UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME DATE
4 6739 0 root ttyp5 INVENTOR 243 138 11000 X 16:22:13 Aug 04
5 6758 112 clair pts/3 INVENTOR 243 138 10060 X 16:21:53 Aug 04
The next example illustrates the output from the LIST.READU command when you specify a user
number. The user number can be found in the output from the LIST.QUEUE and LIST.READU
commands under the UNBR column.
:LIST.READU 6739
UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME DATE
4 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 claireg
UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME
DATE
5 6758 1172 clair pts/3 INVENTOR 24193 10738 11060 X 16:28:14 Aug
04
The next example illustrates output on UNIX from the LIST.READU command when you specify a file
name:
:LIST.READU FILENAME INVENTORY
UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME
DATE
4 6739 0 root ttyp5 INVENTOR 24193 10738 11000 X 16:28:24
Aug 04
5 6758 1172 clair pts/3 INVENTOR 24193 10738 11060 X 16:28:14
Aug 04
And on Windows:
:LIST.READU FILENAME INVENTORY
UNO UNBR UID UNAME TTY FILENAME RECORD_ID M TIME DATE
3 196 1049668 claireg Console INVENTORY 10060 X 08:39:40 Jun 13

Parent topic: Listing locks

LIST.LOCKS
The ECL LIST.LOCKS command displays semaphore-type locks that reserve system resources for
exclusive use.
These locks can be set individually with the LOCK command. They are also set by other ECL
commands, including T.ATT.

168
 LIST.QUEUE

Syntax
LIST.LOCKS
The following screen shows the LIST.LOCKS command and its output:
:LIST.LOCKS
UNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE
1 15290 1172 ump01 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 the
lock number for the lock. In the example, the lock number is 65 for the lock displayed.

Parent topic: Listing locks

LIST.QUEUE
The ECL LIST.QUEUE command displays a list of all processes waiting to get locks.
If a process is waiting for a lock, LIST.QUEUE displays information about the holder of the lock and
processes that are waiting for the lock. Locks are set by each udt process through the 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.

Parameter Description
USERNAME user_name Lists all locks the user is waiting for. user_name is the operating
system logon name.
FILENAME filename Lists all users that are waiting for locks for the file name you specify.
user_number Lists all locks for which the user_number is waiting. The user
number can be found in the UNBR column of the LIST.READU and
LIST.QUEUE output.
DETAIL Displays a detailed listing.

LIST.QUEUE display
The LIST.QUEUE display in the above examples use the default display. Information about the
owner of the lock is listed above the line. Information about processes that are waiting for the lock is
listed 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.

169
Chapter 11: Managing UniData locks

Column heading Description

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.

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 DETAIL
FILENAME RECORD_ID M INBR DNBR OWNER UNBR UNO TTY TIME DATE
INVENTORY 10060 X 241938 107380 clair 13798 3 pts/0 14:48:47 Nov
19
-----------------------------------------------------------------------
FILENAME RECORD_ID M INBR DNBR WAITING UNBR UNO TTY TIME
DATE
INVENTORY 10060 X 241938 107380 root 13763 1 ttyp2 14:48:57
Nov 19
The following table describes the owner information the LIST.QUEUE command displays when you
specify the DETAIL option.

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 Windows only. The high integer of the i-node of the file that is holding the lock.
INBR On Windows, the low integer of the i-node of the file that is holding the lock.
On UNIX, 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.

170
 LIST.QUEUE

Column heading Description

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.

The next table describes the output for the LIST.QUEUE command with the DETAIL option for
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 held. X is an exclusive lock, S is a shared lock.
INBRH Windows only. 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.

Examples
The following example illustrates the output from the LIST.QUEUE command when you do not
specify any parameters.
:LIST.QUEUE
FILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATE
INVENTORY 11060 X clair 6031 2 pts/2 11:05:44 Aug 04
---------------------------------------------------------------------
FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATE
INVENTORY 11060 X clair 6130 4 ttyp1 11:05:54 Aug 04
INVENTORY 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 root
FILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATE
INVENTORY 11060 X clair 6031 2 pts/2 11:35:46 Aug 04
---------------------------------------------------------------------
FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATE
INVENTORY 11060 X root 6259 5 ttyp2 11:35:56 Aug 04
The next example illustrates the LIST.QUEUE command output when you specify a file name:
:LIST.QUEUE FILENAME INVENTORY
FILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATE
INVENTORY 11060 X root 6259 5 ttyp2 11:38:16 Aug 04
---------------------------------------------------------------------
FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATE
INVENTORY 11060 X clair 6188 1 ttyp3 11:38:36 Aug 04
INVENTORY 11060 X clair 6031 2 pts/2 11:38:46 Aug 04

171
Chapter 11: Managing UniData locks

The final example shows the output from the LIST.QUEUE command when you specify a user
number:
:LIST.QUEUE 6763
FILENAME RECORD_ID M OWNER UNBR UNO TTY TIME DATE
INVENTORY 11060 X clair 6758 5 pts/3 14:16:26 Aug 04
---------------------------------------------------------------------
FILENAME RECORD_ID M WAITING UNBR UNO TTY TIME DATE
INVENTORY 11060 X clair 6763 6 ttyp1 14:16:46 Aug 04

Parent topic: Listing locks

Clearing locks
If you break out of a process that is running, if a process is killed, or if a system resource is not
unlocked by a UniBasic program, locks can remain after they should have been released. If a lock
remains set, other users experience difficulty accessing a record, file, or resource. As other processes
attempt to access the locked item, message queue congestion can result if the process that set the
lock is no longer logged on 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 receive
messages that indicate that the file or record is locked.
▪ Performance suffers, either because the item that is locked is heavily used or because a message
queue 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 are
held by other users. Use the following sections to learn how to clear locks with these commands.

• SUPERCLEAR.LOCKS command
The SUPERCLEAR.LOCKS command enables you to release semaphore locks on system
resources (such as tape drives).
• SUPERRELEASE command
The SUPERRELEASE command enables you to release locks are set on records.
• Clearing locks
Use these steps to identify and clear unneeded locks.

SUPERCLEAR.LOCKS command
The SUPERCLEAR.LOCKS command enables you to release semaphore locks on system resources
(such as tape drives).

Syntax
SUPERCLEAR.LOCKS usrnbr [locknum]

Parameters
The following table describes each parameter of the syntax.

172
 SUPERRELEASE command

Parameter Description
usrnbr The process ID (pid) that holds the lock. This number is UNBR in the
LIST.LOCKS display.
[locknum] The number of the locked system resource. If you do not specify locknum the
command clears all locks set by usrnbr.

Example
The following example shows the effects of SUPERCLEAR.LOCKS:
:LIST.LOCKS
UNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE
1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01 Jun 03
3 15692 1172ump01 tyv4 semaphor -1 0 66 X 16:27:01 Jun 03
:
:SUPERCLEAR.LOCKS 15692 -1
:LIST.LOCKS
UNO UNBR UID UNAME TTY FILENAME INBR DNBF RECORD_ID M TIME DATE
1 15454 1172ump01 tyv1 semaphor -1 0 65 X 16:21:01 Jun 03
:

Parent topic: Clearing locks

SUPERRELEASE command
The SUPERRELEASE command enables you to release locks are set on records.

Syntax
SUPERRELEASE usrnbr [inbr devnum ] [record.id]

Parameters
The following table describes each parameter of the syntax:

Parameter Description
usrnbr The process ID (pid) that holds the lock. This number is UNBR in the
LIST.LOCKS display.
[inbr devnum] Windows only. The i-node number and device number for the file that has the
lock set. These numbers are INBRH, INBR and DNBR in the LIST.READU display.
[record.id] Windows only. The identifier for the record to clear. This number is RECORD ID
in the LIST.READU display.
[locknum] UNIX only. The number of the locked system resource. If you do not specify
locknum the command clears all locks set by usrnbr.

Note: If you run SUPERRELEASE and specify only usrnbr, you release all record locks held by the
process ID corresponding to usrnbr.

Examples
The following example shows the effect of SUPERRELEASE:
Windows example:

173
Chapter 11: Managing UniData locks

UNIX example:
:LIST.READU
UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME
DATE
1 4178 1172 clair ttyp2 INVENTOR 24193 10738 10060 X 13:28:40 Sep
24
2 4180 1172 clair ttyp1 INVENTOR 24193 10738 10055 X 13:30:20 Sep
24
:SUPERRELEASE 4180
:LIST.READU
UNO UNBR UID UNAME TTY FILENAME INBR DNBR RECORD_ID M TIME
DATE
1 4178 1172 clair ttyp2 INVENTOR 24193 10738 10060 X 13:28:40 Sep
24

Parent topic: Clearing locks

Clearing locks
Use these steps to identify and clear unneeded locks.
1. Use the UniData LIST.READU and LIST.LOCKS commands to display the locks currently set
on the system. Use LIST.QUEUE to identify locks for which processes are waiting. Note locks
that meet the following criteria:
▪ They are set on files or records that users cannot currently access.
▪ They have been set for a long period (shown by the time and date on the list).
▪ They were set by users who are not currently on the system. On UNIX, this is shown
by comparing the lists with the UniData LISTUSER command or the UNIX who or ps
commands).
2. Note the information for clearing. For record locks, note UNBR, INBR, DNBR, and RECORD NO. For
semaphore locks, note UNBR and lock number. To clear record locks, proceed to step 3. To clear
semaphore locks, proceed to step 4.
3. Release the record locks by logging on as an Administrator on Windows or as root on UNIX. Use
the UniData SUPERRELEASE command to clear record locks. If possible, specify only a UNBR to
clear all the locks that belong to a process ID.

Warning: Some situations that retain locks can also cause file corruption (for example, a udt
process is inadvertently killed). Consider checking the file with guide to make certain it is not
corrupted.

4. UNIX only. Clear the semaphore locks by logging on as an Administrator on Windows or as root on
UNIX and using the SUPERCLEAR.LOCKS command.
5. Check for message queue congestion.

174
 Clearing locks

Some conditions that cause locks to remain set also cause message queue congestion when
other processes attempt to access the locked item. Refer to Managing ipc facilities (UNIX only), on
page 300 for step-by-step instructions for identifying and clearing congested message queues.
Parent topic: Clearing locks

175
Chapter 12: Managing UniData users
This section outlines considerations for adding users to your system and assigning users to groups,
and describes how to use UniData and operating system commands to view user processes for
troubleshooting, how to remove user processes when needed, and how to start and stop UniData.

Adding Windows users

To access UniData on your system, each user needs a valid Windows account, including an MS-DOS
logon ID and password.
In Pick systems, where each logon account must be a Pick account, shared logon IDs and passwords
are common. In contrast, UniData allows multiple relationships between user logon IDs and UniData
accounts. A user might have access to more than one UniData account, and many users can access a
single UniData account by using separate logon IDs. Therefore, we strongly recommend that you set
up a separate Windows account for each user. We recommend separate logon IDs for the following
reasons:
▪ It is easier to identify processes and locks belonging to an individual user, which facilitates
troubleshooting.
▪ You can define your users' responsibilities for protecting their passwords and your data by using
separate logon IDs.
Consider the following when adding Windows users:

• User groups
When you add a user account to your Windows system, you can assign the user to one or more user
groups.
• Home directories
On Windows platforms, you can define a home directory for each logon ID. This directory is the
user’s working directory when they log on.
• UDTADMIN_GROUP registry key
On Windows platforms, you can create a UDTADMIN_GROUP registry key that allows limited
administrator privileges for users who are not administrators.
• Logon scripts
You can create a logon script that is run whenever a user logs on to a Windows console or Telnet
session.

User groups
When you add a user account to your Windows system, you can assign the user to one or more user
groups.
In contrast to UNIX, Windows platforms allow a user to belong to many groups simultaneously, and
allows access to objects based on all groups to which the user is assigned.
When you install UniData on your Windows system, the installation procedure sets permissions on the
UniData directory structure. UniData grants permissions to two categories of users, Administrators,
and all other users.

176
 Home directories

To create user accounts, open the Control Panel and navigate to User Accounts. To add users to
groups and assign user rights, use Administrative Tools > Computer Management. For more
information, refer to your Windows documentation.

Parent topic: Adding Windows users

Home directories
On Windows platforms, you can define a home directory for each logon ID. This directory is the user’s
working directory when they log on.
You are not required to define a home directory. If you want, you can define the same home directory
for a group of users, or create a separate one for each user. The home directory does not have to be a
UniData account.
To define a home directory for a user, open the Control Panel, search for Administrative Tools, then
double-click it. Double-click Computer Management. Click Local Users and Groups, click Users,
double-click the user for which you are defining a home directory, and then click the Profile tab. Enter
the path to the user’s home directory in the Local Path box in the Home folder section, then click OK.
For more information, refer to your Windows documentation.

Parent topic: Adding Windows users

UDTADMIN_GROUP registry key

On Windows platforms, you can create a UDTADMIN_GROUP registry key that allows limited
administrator privileges for users who are not administrators.
Parent topic: Adding Windows users

UDTADMIN_GROUP registry key overview

You can run the UniData services as a Network Service account, Local Service account, domain, or
local user account with administrator privilege in addition to the local system account.
Creating the UDTADMIN_GROUP registry key allows members of the group who are not administrators
to perform the following UniData commands:

CLEAR.LOCKS DELETE.ENCRPYTION.KEY MIGRATE.SQL stopud

clearq DELETE.ENCRYPTION.WALLET newhome stopudt
confprod DELETE.TRIGGER newversion SUPERCLEAR.LOCKS
CONVERT.SQL deleteuser SET.TIME udfile
CREATE.TRIGGER fixtbl SETLINE udtlangconfig
dbpause log_install smmtrace UNSET.LINE
dbresume MAX.USER startud WALLET.REMOVE.KEY

This functionality does not override any Windows Administrator permission checks. Commands that
require that level of permission will still result in an error if performed by a UDTADMIN_GROUP registry
key user.

177
Chapter 12: Managing UniData users

Creating the UDTADMIN_GROUP registry key

By modifying the Windows registry, you can create the UDTADMIN_GROUP registry key in UniData.

About this task

When you add users who are not administrators to the group name located in the UDTADMIN_GROUP
registry key, those users can perform UniData administrator commands.
Group-Name is the name of the group or SID of the group. The group name is not case sensitive.
Group-Name examples can be created using:
▪ A local group name: UDTADMIN_GROUP REG_SZ udadmin
▪ A fully-qualified group name: UDTADMIN_GROUP REG_SZ Rocket1\udadmin
▪ The SID of a group: UDTADMIN_GROUP REG_SZ
S-1-5-21-3676036098-3438739627-2163621525-1027

Procedure
1. Determine the Group-Name that you will be using.
2. Run regedit.
3. Navigate to
HKEY_LOCAL_MACHINE\Software\Rocket Software\UniData\8.2
4. In the right panel, right-click and select New.
5. Select the string value for a new REG_SZ entry: UDTADMIN_GROUP
6. Set the string value to the group name determined in Step 1.
It should display as:
UDTADMIN_GROUP REG_SZ Group-Name, where Group-Name is the name or SID of the group.
7. Save the registry changes.
8. Restart UniData.

Logon scripts
You can create a logon script that is run whenever a user logs on to a Windows console or Telnet
session.
You must create the script in the directory that is identified by your Windows platform logon script
path. If you specify the script in the User Environment Profile window, UniData runs the script
whenever the user logs on to the system.
To specify a logon script for a user, open the Control Panel, search for Administrative Tools, then
double-click it. Double-click Computer Management. Click Local Users and Groups, click Users,
double-click the user for which you are defining a logon script, and then click the Profile tab. Enter the
path to the user’s login script, enter the path where the logon script resides in the User Profile Path
field, the script name in the Logon Script field, and then click OK.

Parent topic: Adding Windows users

178
 Adding UNIX users

Adding UNIX users

To access UniData on your system, each user needs a valid UNIX account, including a UNIX logon ID
and password.
In Pick systems, where each logon account must be a Pick account, shared logon IDs and passwords
are common. In contrast, UniData allows multiple relationships between user logon IDs and UniData
accounts. A user might have access to more than one UniData account, and many users can access
a single UniData account by using separate UNIX logon IDs. Therefore, we strongly recommend that
you set up a separate UNIX account for each user. We recommend separate logon IDs for the following
reasons:
▪ Since most operating systems impose limits on the number of processes that can be associated
with 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 facilitates
troubleshooting.
▪ You can define your users' responsibilities for protecting their passwords and your data by using
separate logon IDs.
Consider the following when adding UNIX users:

• Create logon IDs at the UNIX level

Although the basic process for creating a UNIX account is similar across UNIX versions, different
system configurations might use different utilities or third-party interfaces for the actual
mechanics.
• Assign users to groups
UNIX allows you to define each user as a member of one or more UNIX system groups.

Create logon IDs at the UNIX level

Although the basic process for creating a UNIX account is similar across UNIX versions, different
system configurations might use different utilities or third-party interfaces for the actual mechanics.
No UniData commands or procedures exist for setting up UNIX user accounts. Refer to your host
operating 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 should
not be a UniData account that contains production data or programs.

Warning: In some configurations, proprietary utilities are in use to automate many of the
steps for adding or deleting a user. Make sure that your utilities are clearly documented and
understood. If you have a utility that deletes a user’s home directory when that user’s account
is removed, for example, you could suffer data loss if you use shared home directories.

179
Chapter 12: Managing UniData users

Parent topic: Adding UNIX users

Assign users to groups

UNIX allows you to define each user as a member of one or more UNIX system groups.
File permissions allow differentiation of access between members of a group owner and users who are
not members of that group.
Refer to UniData and UNIX security, on page 110 and Managing UniData security, on page 95 for more
information about groups.

Note: The UNIX commands finger and groups display information about users. Refer to your host
operating system documentation for information about these commands.

Parent topic: Adding UNIX users

Monitoring user processes

For troubleshooting purposes, it is often necessary to identify and monitor processes that are owned
by a particular UniData user.
UniData includes a group of commands to display a list of current UniData sessions, to display a list
of users that are currently logged on to the system, and to display detailed information about process
activity for a specific user, or for all users. The following table summarizes these UniData commands.

UniData command Description

WHO ECL command; similar to the UNIX who command; displays a list of users that
are currently logged on to the system, including users who are not UniData
users.
LISTUSER ECL command; displays a list of current UniData sessions.
listuser UniData system-level command that you enter at the operating-system level
on UNIX or an MS-DOS window on Windows; displays the same information as
the ECL LISTUSER command.
udstat UNIX only. UniData system-level command; displays detailed activity statistics
about a single UniData process or about all UniData processes.
MYSELF ECL command; similar to the UNIX whoami command, displays login ID for the
current UniData session.

Note: You do not need to be logged on as an Administrator or root to run these commands.

The following screen shows the system response to the WHO, LISTUSER, and listuser commands.

180
 Stopping user processes

Notice that the output of the WHO command includes the user name but not the process ID. Also,
output from the LISTUSER command includes a series of identifications: UDTNO (UniData
user number), USRNBR (the pid), UID (the user’s uid number), and USRNAME. Displaying further
information about a UniData process typically requires the pid (USRNBR).

Stopping user processes

UniData includes commands that enable you to stop a user’s udt process if the process is hung, or
if you need to stop UniData while a user is still logged on. These commands are summarized in the
following table.

UniData command Description

stopudt Logs a user out of UniData; UniData allows a current write to complete, but
subsequent operations for that udt do not take place. On UNIX, stopudt
uses the kill -15 command.
deleteuser First attempts to gracefully exit and allow a write in progress to complete.
If the command is not successful in 5 seconds, force logs out a user, which
might interrupt a write in progress, potentially causing file corruption. On
UNIX, deleteuser issues the kill -15 command.

You can log yourself out using the stopudt command, but you must log on as an Administrator or
root to log out other users by using stopudt. You must log on as an Administrator or root to run
deleteuser.

Warning: Both of these commands can disrupt the consistency of your database, and
deleteuser can also corrupt data. Do not use these commands as a substitute for normal user
logout.

The UNIX kill command enables you to stop a process with various options. Use this command with
caution, since it can cause data inconsistency and file corruption. Refer to your host operating system
documentation for information about the kill command.

181
Chapter 12: Managing UniData users

Tip: You can use the UniData system-level command udstat on UNIX to check the activity of a
UniData process. If the process shows activity, stopping or deleting it could damage data. See the
UniData Commands Reference for examples of the udstat command. Communicate directly with
the owner, if possible, before you stop a udt process, because even if the process seems to be idle,
the terminal might 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 UniBasic
program. TIMEOUT forces the current udt process to log out after a specified number of seconds.
If you include TIMEOUT in the LOGIN paragraphs for your UniData accounts, you can provide some
improved security for terminals left idle.

Warning: Be careful with TIMEOUT. Because this command can cause a UniBasic program to
terminate at an INPUT statement rather than concluding normally, using TIMEOUT can cause
inconsistent data in your database.

182
Chapter 13: Managing printers in UniData
This section explains how UniData interacts with UNIX and Windows spooler software and describes
how to configure and access printers from within UniData.
See the following sections:
▪ Managing printers on Windows, on page 183
▪ Managing printers on UNIX, on page 197

Managing printers on Windows

• Configuring and troubleshooting a Printer
Use these conditions as guidelines for setting up a print device and for troubleshooting print device
problems.
• Spooling from UniData
Print requests from within UniData are generated by UniBasic commands (PRINT, PRINT ON), by
ECL commands (SPOOL, SP.EDIT) and by using the LPTR keyword in UniQuery.
• Defining a printer unit in UniData
Use the ECL SETPTR command to define printer units within UniData. This command maps
Windows printers to logical unit numbers within a UniData session.
• UniData printing commands
UniData includes a number of options that enable you to customize output from UniBasic
programs and reports.

Configuring and troubleshooting a Printer

Use these conditions as guidelines for setting up a print device and for troubleshooting print device
problems.
On Windows platforms, the term “printer” refers to a printer driver. The term “print device” refers to a
piece of hardware that can be accessed using one or more “printers.” In order for any user to print to a
print device from UniData, all the following conditions must be true.

Parent topic: Managing printers on Windows

Physical configuration
Configure a print device as follows:

183
Chapter 13: Managing printers in UniData

▪ The print device must be physically connected to your computer or network.

▪ If you are accessing the print device from a local printer you create, the driver for the print device
must be installed on the workstation or server from which you are printing.

Note: Depending on your network configuration, you may need to complete additional steps
before you can print successfully from your Windows platform. For instance, you may need to
install additional network software and then create a “printer” or “local printer” that identifies
the device using a network address. Refer to your Microsoft documentation, the documentation
for your network hardware and software, and your printer documentation for information
about connecting and troubleshooting a print device.

Troubleshooting
▪ Check cables and connections.
▪ Check power to print device and check print device for error conditions.
▪ Print a file to the print device. If you cannot print to the device from outside UniData, you will not
be able to print to it from within UniData. Missing printer drivers or restrictive permissions to a
device can result in print jobs failing.

Definition in Windows platforms

You can either print directly to a network print device or a print to a “local printer” from within
UniData.

Network print device

A network print device is a print device that is connected to a remote print server. When you print
to a network printer, the printer driver and the configuration are downloaded to your computer. To
connect to a network printer, from the Start menu click Devices and Printers, click Printers, and then
click Add Printers. The Add Printer wizard displays.
Select Add a network, wireless, or Bluetooth printer.
If you know the name of the printer, enter the path in the Name box.
If you are connecting to a printer on the internet or on your intranet, select the printer from the Select
a printer box. If you do not see the name of the printer you want to add, click The printer I want isn’t
listed.
Refer to your Microsoft documentation for instructions about adding a printer.

Local printer
A local printer is a driver you can create that identifies a print device. When you define a local printer,
your workstation becomes the print server for that printer. A local printer may point to a network print
device, but you define the printer configuration on your workstation.

Definition in UniData
Within a UniData session, the following commands and statements can access a printer:
▪ UniBasic PRINT statements (following PRINTER ON statements)
▪ UniQuery statements with the LPTR option

184
 Default printers

▪ SPOOL commands
▪ The SP.EDIT command
To write to a particular printer from a UniData session, you need to link the printer to an internal
print unit in UniData. Use the ECL SETPTR command with the DEST or AT option for this. For more
information, see Defining a printer unit in UniData, on page 188.

Default printers
If you do not map a print unit to a particular printer or queue, UniData checks for a default destination
for output of printing commands as follows:
▪ The printer or queue defined by the last previous SETPTR command in your current UniData
session.
▪ If there was no prior SETPTR command, the printer identified by the system environment variable
UDT_DEFAULT_PRINTER. Each UniData session checks for that variable at when users log on to the
system. If the variable was set, the defined printer is treated as the default printer throughout the
session.
▪ If there was no prior SETPTR command, and UDT_DEFAULT_PRINTER was not set, UniData checks
for the default printer on your Windows system.

Note: If you are a local user (your account information is on a local Windows machine rather
than a domain) and you log on through Telnet, and UDT_DEFAULT_PRINTER was not set, you
will see an error message when you attempt to display the default printer name with SETPTR 0.

Spooling from UniData

Print requests from within UniData are generated by UniBasic commands (PRINT, PRINT ON), by
ECL commands (SPOOL, SP.EDIT) and by using the LPTR keyword in UniQuery.
When a print request is generated, the following actions happen:
▪ UniData uses information from the print request to create a temporary file containing the output to
be printed.

Note: If you executed SETPTR and set the printer mode to 3 or 6, UniData creates the print file
in the _HOLD_ file of your current UniData account.

▪ UniData prints that file with Windows Win32 API calls, using information from the printer setup
(SETPTR for the printer to receive the output).
▪ After the output is printed, UniData deletes the temporary file.

Parent topic: Managing printers on Windows

UniData for Windows platforms specifics

UniData for Windows Platforms enables you to print to any printer you can access from outside of
UniData. The DEST or AT option of SETPTR enables you to print to a particular device. SETPTR
options control some output characteristics, and you can specify other characteristics by including
spooler options in a quoted string on the SETPTR command line.

185
Chapter 13: Managing printers in UniData

By using RAW spooler mode (the default in UniData), you can control formatting by using printer-
specific escape sequences rather than spooler options.

Creating a local printer

On Windows platforms, the term “printer” refers to a printer driver. The term “print device” refers to a
piece of hardware you can be access by using one or more “printers”. You can create a local printer to
print to a device local to your server or workstation. In some circumstances, you may wish to create a
local printer that points to a network print device, and print to that local printer rather directly to the
network device.
Complete the following steps to create a local printer.
1. From the Start menu, click Devices and Printers to Printers and Faxes, and then click Add a
Printer.
2. Click Add a local printer to indicate the printer is a local printer.

Note: Your Windows machine becomes the “server” for the printer you are creating. After you
add the printer, clickFile, then Server Properties to view and edit settings for this printer.

3. If your local printer identifies a device local to your workstation or server, scroll through the list of
ports and select the check box the one where the printer is connected. Click Next and proceed to
step 5.
4. If your local printer identifies a network print device, scroll through the list of Available Ports
to determine if the UNC identifier for the network print device is listed with “Local Port” as its
description. If so, proceed to step 5.
5. If the network print device is not on the list, or its description is not “Local Port,” click Create a
new port. Select Local Port from the Type list, and then click Next.
6. Select the manufacturer and model of your printer. If your printer came with an installation
disk, click Have Disk. If the manufacturer or model of your printer is not listed, see your printer
documentation for a compatible printer. Click Next.
7. Enter a name for the local printer in the Name Your Printer dialog box.

Warning: Do not use spaces in the printer name. Although Windows platforms allow spaces in
the name (for instance, “LASER PRINTER”), the UniData SETPTR command does not support
names that contain spaces. If you use a name containing spaces with the DEST or AT options
of SETPTR, the command fails.

8. You can share your printer with other users on the network. Enter a name for the shared printer,
or select Do not share this printer.

Note: You may share a local printer if you wish. However, sharing a local printer offers no
advantage in UniData. UniData only recognizes local printers created on the same Windows
system where you are running UniData. Also, UniData does not use the share name to
recognize a printer. Rather, UniData uses the printer name you entered previously.

9. Click Next after defining Sharing properties.

Tip: We recommend you print a test page to verify the printer setup. 

An icon for the printer appears in the Printers window.

10. Display the Properties sheet for the printer you just created. The following table summarizes the
dialog tab.

186
 Creating a form

Dialog tab Purpose

General Adds comments or location information, or changes printer driver.
Within UniData, the first 24 characters of comment entry displays as
Description in the output from LISTPTR or SP.STATUS.
Ports References a different network print device.
Scheduling Views or edits times the printer is available, job priority, and job handling.
Sharing Shares or unshares your printer.
Security Views or edits permissions, ownership, auditing.
Device Settings Maps forms to trays/feeders.

Note: Use caution modifying device settings. You can enter settings for a local printer that are
inconsistent with the underlying print device.

Note: You must haveFull Control permissions on a printer to assign a default form. Click
Security, and then click Permissions on the Property sheet to determine what permissions
you have.

11. To assign a default form to a printer, right-click the printer for which you want to set the default,
then click Printer Properties.
12. Click Preferences. Select the desired form from the Form Type list. If the form you want is not
included in the list, see Creating a form, on page 187. You can also choose copies, orientation,
and duplex options from this dialog box.

Note: Options you select on either this tab or theAdvanced tab only work if the network print
device supports them.

13. Click OK when your selections are correct.

Note: Although you can selectCopy Count from this tab, the value you select here is
overridden in UniData by the COPIES option of the SETPTR command.

Creating a form
Windows platforms store information about forms that are available on your current Windows system.
Not all the forms are available for all print devices, because each print device supports particular sizes
of stock and loading devices.
To view the list of forms available on your system, from the Start menu, click Devices and Printers.
Click the File menu, then click Server Properties, then click the Forms tab.
Select the Forms tab on the properties sheet, and complete the following steps to create a new form.
1. Select an existing form.
You create new forms by editing the characteristics of existing forms. Highlight a form, and then
select the Create a New Form check box.

Tip: To minimize editing, pick an existing form whose characteristics are similar to the new
form you are creating.

187
Chapter 13: Managing printers in UniData

2. Edit form characteristics.

When you select the Create a New Form check box, the name, paper size and margins are
enabled for editing. Follow the instructions on the properties page to edit and save the new form.

Note: Although you can create forms of varying sizes, you cannot select a particular form for
use on a particular printer unless the print device can support that size of stock. Refer to your
Windows documentation and the documentation for your print device for information about
constraints.

The new form now displays in the form list.

3. Click OK to exit the Forms tab.

Defining a printer unit in UniData

Use the ECL SETPTR command to define printer units within UniData. This command maps Windows
printers to logical unit numbers within a UniData session.

Syntax
SETPTR unit [width,length,topmargin,bottommargin] [,mode] [,options]
[,“spooler_options”]
With SETPTR, you can define up to 31 logical printer units in a single UniData session. Throughout
UniData, you can define up to 255, but only 31 can be defined in a single user session.

Parameters
The following table lists each parameter of the syntax.

Parameter Description
unit Logical printer unit number that is internal to UniData. You can map
this to a Windows printer with the DEST or AT option. Must range from 0
through 254; default is 0.
[width] The number of characters per line; must be from 0 to 1024; default is 132.
[length] The number of lines per page; must be from 1 to 32,767 lines; default is
60.
[topmargin] The number of lines to leave blank at the top of each page; must be from
0 to 25; default is 3.
[bottommargin] The number of lines to leave blank at the bottom of each page; must be
from 0 to 25; default is 3.
[mode] Allows you additional flexibility to direct output; default is 1; see separate
table.
[options] Report formatting and printer control options. For more information, see
“SETPTR Options.”
[“spooler_options”] Options that are valid with the Windows spooler. See separate table for
list of supported options. Supply these options in a quoted string.

188
 Defining a printer unit in UniData

Note: Users familiar with Pick conventions should be aware that printer unit numbers set with
SETPTR are not the same as Pick printer numbers. SETPTR allows you to define logical printer
units, which may be, but are not necessarily, linked to specific printers. UniData printer unit
numbers are used with the PRINT ON statement in UniBasic to allow multiple concurrent jobs. Pick
printers (forms) are specified with the DEST option of SP.ASSIGN.

The next table describes modes for the SETPTR command.

Mode Description
1 Directs output to a line printer only.
2 Must be used with DEVICE option; directs output to the serial device specified by the
DEVICE option.
3 Directs output to a _HOLD_ file only.
6 Directs output to both a _HOLD_ file and a printer.
9 Directs output to a line printer; suppresses display of the _HOLD_ entry name.

The next table describes options for the SETPTR command.

Option Description
BANNER [string] Modifies the default banner line (which is the Windows user ID). Depends
on MODE setting; also modifies _HOLD_ entry name.
BANNER UNIQUE [string] Modifies the default banner line, and automatically uses attribute 1
(NEXT.HOLD) in the dictionary for the _HOLD_ file to create unique entry
names for jobs sent to _HOLD_.
BRIEF Directs UniData NOT to prompt for verification upon execution of
SETPTR.
COPIES n Prints n copies of the print job. Does not work with mode 3.
DEFER [time] Delays printing until the specified time. Specify the time in HH:MM
format. Does not work with mode 3.
DEST unit (or AT unit) Directs output to a specific printer or queue. The unit may be either a
local printer or a network printer.
DEVICE name Used with mode 2 only. Directs output to the Windows device (for
instance, a COM port) identified by name.
EJECT Ejects a blank page at the end of each print job.
NOEJECT Suppresses the form feed at the end of each print job.
LNUM Prints line numbers in the left margin of each print job.
NFMT or NOFMT Suspends all UniData print formatting.
NHEAD or NOHEAD Suppresses the banner for each print job.
OPEN Opens a print file, and directs output to this file until the file is closed by
the SP.CLOSE command.

The next table describes spooler options you can specify in a quoted string.

Option Description
Orientation Paper orientation; must be PORTRAIT or LANDSCAPE. Defaults to the setting
in the Default Document Properties sheet for the printer.
PaperSource Default paper source; must match an available paper source listed on the
Device Settings tab of the printer’s Properties Sheet.

189
Chapter 13: Managing printers in UniData

Option Description
Duplex Must be NONE, HORIZONTAL, or VERTICAL; default is NONE.
If the print device does not support duplex printing, this option is ignored.
Jobs print single-sided and no error message displays.
Form Form to use (for instance, Letter). Must match an available paper size listed
on the Device Settings tab of the printer’s Properties Sheet.
Mode RAW or WINDOW. Default is RAW, meaning that printer-specific escape
sequences are required for all formatting.
Specifying formatting options (Form, Font, FontSize, Orientation, FontStyle,
DefaultSource, or Duplex) in a quoted string automatically switches Mode to
WINDOW.
Prefix stevPrinter-specific escape sequence, specified as the literal ASCII characters.
Valid in RAW mode only. For example, “PREFIX = \002”
Font Font name, for instance “Courier New”.
The UniData spooler creates a “logical font” using the values you provide
for Font, FontSize, and FontStyle. Windows platforms attempt to find an
appropriate font to use from the ones installed on your computer.
FontSize Font size in points (for instance, 8, 9, 10, 11).
The UniData spooler creates a “logical font” using the values you provide
for Font, FontSize, and FontStyle. Windows platforms attempt to find an
appropriate font to use from the ones installed on your computer.
FontStyle Must be Regular, Italic, Bold, Underline, or StrikeOut. Default is Regular.
The UniData spooler creates a “logical font” using the values you provide
for Font, FontSize, and FontStyle. Windows platforms attempt to find an
appropriate font to use from the ones installed on your computer.
LeftMargin Left margin of the page, in inches. For example, “LeftMargin = 1.0”
RightMargin Right margin of the page, in inches. For example, “RightMargin = 0.75”
TopMargin Top margin of the page, in inches.
TopMargin is measured beginning at the value of the SETPTR topmargin
option (default is 3 lines). If topmargin is 3 lines (the default) and TopMargin =
1, the first printed line is one inch below the third line on the page.
BottomMargin Bottom margin of the page, in inches.
BottomMargin is measured beginning at the value of the SETPTR
bottommargin option (default is 3 lines). If bottommargin is 3 lines (the
default) and BottomMargin = 1, the first printed line is one inch above the
third line from the end of the page.
Priority Must be from 1 to 99, where 1 is minimum priority and 99 is maximum.
JobState The only valid value is PAUSE, which stops all jobs to the print unit. You can
reverse this option from the Printers applet.

Parent topic: Managing printers on Windows

Examples
The following example illustrates the output from the LIST.READU command when you do not
specify any options.

190
 Examples

Notice the following points:

▪ The default print device (printer unit 0) is now mapped to the local printer LETTER. If you use the
PRINT command or LPTR with no print unit specified, UniData directs your print job to LETTER.
▪ Use SETPTR unit to display the current settings for a print unit.
▪ When you specify spooler options (TopMargin, BottomMargin), UniData automatically recalculates
the width and length taking these into account. When you specify formatting options in a quoted
string, UniData implicitly changes the spooler Mode from RAW (the default) to WINDOW.

191
Chapter 13: Managing printers in UniData

▪ You can specify spooler options in a quoted string either before or after SETPTR options like AT,
DEFER.
▪ You can map a printer unit to a network print device even if that device is not displayed in your
Printers dialog.

After you have defined printers with SETPTR, you can display a list with the LISTPTR command, as
shown below:

Only users with Full Control permissions on a printer can control the printer with PTRDISABLE
and PTRENABLE. Check Permissions on the Security tab of the Properties sheet for the printer to
determine who has permissions.
Notice that the argument for PTRDISABLE and PTRENABLE is the name of the printer (as specified with
DEST or AT in SETPTR).
You can use the ECL SP.STATUS command to display information about printers defined with
SETPTR and print jobs started from your UniData session.
The following example shows SP.STATUS output:

192
 Printing to the _HOLD_ file

The status of all the printers is Running, and the network print device has a deferred job.
Depending on how a print device was configured, users in console sessions may see printer
notification messages when a job completes.

Note: The Printing Notification only displays if you log on to a console session. If you log on to
UniData through Telnet, you will not see the notification.

Printing to the _HOLD_ file

Selecting SETPTR mode 3, 6, or 9 on the command line directs output from printing commands to
the _HOLD_ file. When you print to the _HOLD_ file, UniData actually creates two entries, one for the
printing command output and one for the SETPTR settings. UniData preserves the SETPTR settings
so you can print from the _HOLD_ file at a later time using the settings selected with SETPTR. The
following example shows the creation and contents of two _HOLD_ entries generated by a printing
command:

193
Chapter 13: Managing printers in UniData

Selecting a spooler mode

The UniData spooler interface enables you to print to an Windows printer using one of two spooler
modes: RAW or WINDOW.

RAW Mode
In RAW mode, the default, all formatting is controlled by printer-specific escape sequences you include
in your print job. UniData writes to the spooler device using the WritePrinter win32 API call. RAW mode
enables you to migrate existing applications and utilities without rewriting printing logic.

WINDOW Mode
In WINDOW mode, formatting is controlled by your selection of SETPTR options and spooler options.
You can print in WINDOW mode by specifying “Mode=WINDOW” on the SETPTR command line or by
including any of the spooler options (Form, Font, FontSize, Orientation, FontStyle, DefaultSource, or
Duplex) that only work in WINDOW mode.
In the following example, the spooler mode is changed from RAW (the default) to WINDOW. Notice that
UniData changes the width and length automatically:

194
 WINDOW Mode

In the next example, setting Font to COURIER implicitly changes the spooler mode to WINDOW, even
though the display does not indicate this. Notice that width and length were adjusted:

If you combine incompatible options on the SETPTR command line, the command fails with an error
message as shown in the following example:

195
Chapter 13: Managing printers in UniData

Redefining the default UniData print unit

To keep UniBasic applications general, developers typically use (or assume) printer unit 0, which is the
default. The SETPTR command enables you to redefine unit 0 to direct output from different parts of
an application to different physical printers or queues, or to change formatting options.
The following example is a very simple paragraph that redefines the default print unit for different
reports:

Submitting concurrent print jobs

With SETPTR, you can define up to 31 logical printer units in a single UniData session. You can
use this functionality to submit concurrent print jobs from a UniBasic application. One common
implementation follows:
▪ Define two logical printer units (for instance, 0 and 1) that point to different physical print devices.
▪ Direct all lines of a report to one printer with the UniBasic PRINT ON command (for instance, PRINT
ON 0 PRINT.LINE).
▪ Direct summary (break) lines to the second printer (PRINT ON 0 PRINT.LINE followed by PRINT ON
1 PRINT.LINE).
In this way, you can print a summary report and a detail report at the same time.

UniData printing commands

UniData includes a number of options that enable you to customize output from UniBasic programs
and reports.
See the UDT.OPTIONS Commands Reference for a complete listing of all available options.
The following table describes ECL commands related to printing.

196
 Managing printers on UNIX

Command Description
LISTPEQS Lists entries in the _HOLD_ file of the current account.
LISTPTR Displays the names of printers and the paths of devices associated with
them.
PTRDISABLE or Pauses a Windows printer. You must supply the printer name (the name
STOPPTR you used with the DEST or AT option) rather than the UniData logical print
unit number.
PTRENABLE or Resumes a Windows local printer. You must supply the printer name
STARTPTR (the name you used with the DEST or AT option) rather than the UniData
logical print unit number.
SETPTR Defines logical printer units within a UniData session.
SP.ASSIGN Sets characteristics of the default UniData print device, printer unit 0
(PickÒ compatible syntax).
SP.CLOSE Closes a print file.
SP.EDIT Views or prints files in the _HOLD_ directory
SP.KILL Cancels a job.
SP.OPEN Opens a continuous print job. This command is equivalent to the UniData
SETPTR,,,,,,OPEN command.
SP.STATUS Provides printer and queue information.
SPOOL Prints the contents of a record to the printer.

Note: See the UniBasic Commands Reference for the syntax of these ECL commands.

Parent topic: Managing printers on Windows

Managing printers on UNIX

• UniData and UNIX spoolers
All printing from within UniData is performed by your UNIX system spooler. UniData does not
include its own spooler; the UniData printing commands form an interface to UNIX spooler
commands.
• UniData printing commands
UniData includes a number of commands that enable you to customize output from UniBasic
programs and UniQuery reports.
• Configuring and troubleshooting a printer
In order for any user to print to a printer from UniData, all the following conditions must be
true. Use these conditions as a guideline for setting up a printer and for troubleshooting printer
problems.
• SETPTR
The SETPTR command enables you to define “logical printer units” within a UniData session.
• Environment variables
UniData provides two environment variables that affect printing.
• Examples
There are a number of ways you can use SETPTR.
• Decoding a UniData print statement
To research printing problems within UniData, it is sometimes helpful to determine what
arguments UniData is passing to your UNIX spooler.

197
Chapter 13: Managing printers in UniData

UniData and UNIX spoolers

All printing from within UniData is performed by your UNIX system spooler. UniData does not include
its own spooler; the UniData printing commands form an interface to UNIX spooler commands.
Different versions of UNIX include different spooling systems. There are two major types: the BSD
spooling system, which includes the lpd, lpc, and lpr commands, and the ATT spooling system, which
includes the lp command. The spooling system for any UNIX version is likely to be derived from one
or the other of these types, although each UNIX version may include platform-specific features.
Also, some UNIX versions include the user interfaces from both spooling system types, although
underlying processing is accomplished by one or the other type. Refer to your host operating system
documentation for information about the spooler on your UNIX system.
Users can specify any UNIX spooler command that is supported on their system by using the ECL
command SETOSPRINTER, and defining the spooler configuration file.

Parent topic: Managing printers on UNIX

Configuring the spooler

UniData includes a spooler configuration file, UDTSPOOL.CONFIG, located in udthome/sys. This
file contains information for the interface between the UniData SETPTR command and the UNIX-level
print commands. The UDTSPOOL.CONFIG file contains interface information for the lp command
on each system. For some systems, UDTSPOOL.CONFIG also contains information for the lpr
command.
The following example illustrates the UDTSPOOL.CONFIG file:

198
 Configuring the spooler

Notice the following points about the UDTSPOOL.CONFIG file:

▪ The file contains two entries, one for lp and one for lpr. Each entry lists the spooler command
options that correspond to typical SETPTR options. Within each entry, the “DEFAULT” line
indicates options that the spooler should always include.
▪ In the first entry for lp, the lp command is identified as DEFAULT. This identification directs UniData
to use lp as the spooler command unless you specify another command.
You can modify the UDTSPOOL.CONFIG file by using any UNIX text editor. You can add spooler
commands, 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 to
display an error message each time you invoke your spooler command, you can specify U_IGNORE
next to the unsupported option. In the following example, the NHEAD option in the lp command has
a value of U_IGNORE. Therefore, UniData ignores the NHEAD option, even if you specify it with the
SETPTR or SP.ASSIGN commands:

199
Chapter 13: Managing printers in UniData

Enabling and disabling printers

The PTRENABLE and PTRDISABLE commands issue platform-dependent UNIX commands to
enable and disable a printer, respectively. You may add the appropriate UNIX commands to the
UDTSPOOL.CONFIG file for your platform, as shown in the following example:

200
 SETOSPRINTER Command

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 by
using the LPTR keyword in UniQuery. When a print request is generated, the following actions happen:
▪ UniData uses information from the print request to create a temporary file that contains the
output to be printed. This temporary file is created by default in the /tmp directory. If you define
the UniData configuration parameter TMP, UniData creates the print file in the location that is
specified by TMP. You can override this setting by setting the environment variable TMP at the UNIX
prompt 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 for
the logical printer to receive the output) to create a UNIX spooler command.
▪ The UNIX spooler command accepts the temporary file as input. (Notice that the printed output
may not reflect changes 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

UniData includes a number of commands that enable you to customize output from UniBasic
programs and UniQuery reports.

Note: See the UDT.OPTIONS Commands Reference for a complete listing of all available options.

Command Description
LIMIT Displays the current spooler setting that is used for printing.

201
Chapter 13: Managing printers in UniData

Command Description
LISTPEQS or SP.LISTQ Prints the status of the output request. These commands are equivalent
to UNIX lpstat -o.
LISTPTR Prints the names of printers and paths of devices that are associated
with them. This command is equivalent to UNIX lpstat -v.
PTRDISABLE, STOPPTR, Disables a UNIX printer or queue. These commands are equivalent to
or SP.STOPLPTR your spooling system’s disable command. You must supply a printer
or queue ID that is defined to your spooler. Do not supply a UniData
logical print unit number.
PTRENABLE, STARTPTR, Enables a UNIX printer or queue. The commands are equivalent to
or SP.STARTLPTR your spooling system’s enable command. You must supply a printer
or queue ID that is defined to your spooler. Do not supply a UniData
logical print unit number.
SETOSPRINTER Selects a UNIX spooler command.
SETPTR Defines logical printer units within a UniData session and displays the
current spooler setting.
SP.ASSIGN Defines logical printer units within a UniData session (Pick® compatible
syntax).
SP.CLOSE Closes a print file.
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.
SPOOL Prints the contents of a record to the printer.

Note: See the UniData Commands Reference for the syntax of these ECL commands.

Parent topic: Managing printers on UNIX

Configuring and troubleshooting a printer

In order for any user to print to a printer from UniData, all the following conditions must be true. Use
these conditions as a guideline for setting up a printer and for troubleshooting printer problems.
Parent topic: Managing printers on UNIX

Physical connection
The printer must be physically connected to your computer.
▪ Check cables and connections.
▪ Check power to the printer, and check the printer for error conditions.
▪ Use the UNIX cat command to write a text file to the printer in serial mode; verify that all contents
of the file print successfully. For example, assume you have a file that is called textfile and a printer

202
 Troubleshooting

that is attached to /dev/tty01; enter cat textfile > /dev/tty01 at the UNIX prompt to test the
connection.

Refer to your host operating system documentation and your printer documentation for information
about connecting and troubleshooting a printer.

Troubleshooting
▪ Use the UNIX lpstat command to determine if the printer is defined. Check your documentation
to 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, spooling
to the device class sends the job to the first available member of that class, which may not be the
desired printer.

Note: Refer to your host operating system documentation for information about your spooling
system. Because different UNIX versions include different spooling systems, procedures for
defining 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 be
a discrete destination or a member of a device class.
▪ Use the UNIX lpstat command to determine if the printer is defined. Check your documentation
to 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, spooling
to the device class sends the job to the first available member of that class, which may not be the
desired printer.

Note: Refer to your host operating system documentation for information about your spooling
system. Because different UNIX versions include different spooling systems, procedures for
defining a printer to a spooler vary.

Definition in UniData
In order to access a specific printer (or queue) from a UniData session, you need to link the printer, or
queue, to an internal print unit in UniData.
Use the ECL SETPTR command for this. See SETPTR, on page 203.

Note: If you do not define a specific printer or queue with SETPTR, UniData directs output from
UniBasic PRINT statements (following PRINTER ON statements), or from UniQuery statements
with the LPTR option, to the default printer or queue on your system.

SETPTR
The SETPTR command enables you to define “logical printer units” within a UniData session.

203
Chapter 13: Managing printers in UniData

A logical printer unit is a combination of a printer destination, a form type, page dimensions, and more
options. By varying form type and options, you can define more than one logical printer unit for a
single physical printer.
With SETPTR, you can define up to 31 logical printer units in a single UniData session. Throughout
UniData, you can define up to 255, but you can define only 31 in a single user session.

Syntax
SETPTR unit [width,length,topmargin,bottommargin] [mode]
[“spooleroptions”] [options]

Parameters
The following table lists the parameters of the SETPTR syntax.

Parameter Description
unit Logical printer unit number; internal to UniData; you can map this unit
number to a UNIX printer or queue with the DEST and FORM options. 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 be
within the range 0-25; default is 3.
[bottommargin] The number of lines to leave blank at the bottom of each page; must be
within the range 0-25; default is 3.
[mode] Enables more flexibility to direct output; default is 1; see separate table.
[“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 interprets and
passes to the UNIX spooler. See separate table.

Note: Users familiar with Pick conventions should be aware that printer unit numbers set with
SETPTR are not the same as Pick printer numbers. SETPTR enables you to define logical printer
units, which may be linked to specific printers. UniData printer unit numbers are used with the
PRINT ON statement in UniBasic to allow multiple concurrent jobs. Pick printers (forms) are
specified 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.

The next table describes options for the SETPTR command.

204
 Environment variables

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 uses attribute 1
(NEXT.HOLD) in the dictionary for the _HOLD_ file to create unique
entry names for jobs that are sent to _HOLD_.
BRIEF Directs UniData not to prompt for verification upon execution of
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 for
specifying time. You need the documentation for the UNIX at
command.
DEST unit (or AT unit) Directs output to a specific printer or queue. The unit must be a
valid destination at your site. Refer to your spooler documentation,
and use the UNIX lpstat command for information about valid
destinations.
DEVICE filename Used with mode 2 only. Directs output to the UNIX device whose
special file is filename.
EJECT Ejects a blank page at the end of each print job.
NOEJECT Suppresses the form feed at the end of each print job.
FORM form Assigns a specified form to each print job. The form 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.

Parent topic: Managing printers on UNIX

Environment variables
UniData provides two environment variables that affect printing.
Parent topic: Managing printers on UNIX

Disabling printer validation

You can bypass validation of DEST and FORM in SETPTR against the UNIX spooler’s list of logical
printers by setting the NOCHKLPREQ environment variable. (UniData concatenates DEST and FORM
before validation, since many logical printers can access a single physical printer or queue.) On
systems with hundreds of print units that are defined in the UNIX spooler, the UniData validation can
take so much time that it is a processing bottleneck. In such cases, setting NOCHKLPREQ removes the
bottleneck. Use the following commands to set NOCHKLPREQ:
Bourne or Korn Shell:
NOCHKLPREQ=1;export NOCHKLPREQ

205
Chapter 13: Managing printers in UniData

C shell:
setenv NOCHKLPREQ 1
Consider setting this variable in each user’s .login or .profile.

Warning: If you disable validation, you may encounter unexpected results, including lost print
jobs, by specifying invalid DEST/FORM combinations. It is safest to disable checking if you run your
SETPTR commands in a paragraph or a UniBasic program rather than manually, and if you test all
options before implementing them in production.

Defining an alternate search path

The LPREQ environment variable enables you to provide an alternate search path for DEST/FORM
validation. UniData automatically searches the default directory for your UNIX environment (for
instance, on an HP-UX system, the directory /usr/spool/lp/request). If you wish to use a
different directory, use LPREQ.

Examples
There are a number of ways you can use SETPTR.
Parent topic: Managing printers on UNIX

Redefining the default UniData print unit

To keep UniBasic applications general, developers typically use (or assume) printer unit 0, which is the
default. The SETPTR command enables you to redefine unit 0 to direct output from different parts of
an application to different physical printers or queues, or to change formatting options. The following
example redefines the default print unit for different reports:
:CT VOC OUTPUT
VOC:
OUTPUT:
PA
SETPTR 0,80,60,,,1,BRIEF,DEST laser
RUN BP REPORT_PRINT
SETPTR 0,80,40,,,1,BRIEF,DEST laser,FORM invoice
RUN BP INVOICE_PRINT
:
Notice the following points:
▪ Both “laser” and “laserinvoice” must be valid destinations that are defined to your UNIX spooler. If
you have defined NOCHKLPREQ, invalid destinations cause print jobs to fail. If you did not define
NOCHKLPREQ, invalid destinations cause the SETPTR command in the paragraph to fail.
▪ If “laser” is a single printer rather than a queue, the two SETPTR commands both access a single
physical printer. This type of definition is acceptable.

Submitting concurrent print jobs

With SETPTR, you can define up to 31 logical printer units in a single UniData session. You can
use this functionality to submit concurrent print jobs from a UniBasic application. One common
implementation follows:
▪ Define two logical printer units (for instance, 0 and 1).

206
 Printing to a UNIX device

▪ Direct all lines of a report to one printer with the UniBasic PRINT ON command (for instance,
PRINT ON 0 PRINT.LINE).
▪ Direct summary (break) lines to the second printer (PRINT ON 0 PRINT.LINE followed by
PRINT ON 1 PRINT.LINE).
In this way, you can print a summary report and a detail report at the same time.

Printing to a UNIX device

Use mode 2 of the SETPTR syntax to direct output to a UNIX device. The following sample command
shows the correct syntax for this option:
SETPTR 0,,,,,2,DEVICE /dev/tty9
When you use mode 2, UniData sets the following options by default:
▪ NOEJECT
▪ NOFMT
▪ NOHEAD
▪ NOMESSAGE
▪ OPEN
When you use mode 2, UniData disables the following options:
▪ BANNER
▪ BANNER UNIQUE
▪ BRIEF
▪ COPIES
▪ DEFER
▪ EJECT
You must use the DEVICE option with mode 2, and you must specify the output device. The device can
be a terminal, a serial printer, a tape drive, or a disk file. If writing to an actual device, you must specify
the 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 spooler
command, by specifying the options as a quoted string on the SETPTR command line. The following
sample command uses the spooler options for banner title (-t) and for copies (-c) directly, rather than
the UniData options:
SETPTR 0,,,,,1,"-tACCOUNTS,-c2",DEST laser
Using a quoted string is helpful when you receive unexpected results from UniData SETPTR options,
or if your default spooler supports more options than UniData accepts.

Tip: Use the ECL LIMIT command or the SETPTR command to display the default spooler
command in your UniData release, and then refer to your host operating system documentation
for supported options for that command.

207
Chapter 13: Managing printers in UniData

Decoding a UniData print statement

To research printing problems within UniData, it is sometimes helpful to determine what arguments
UniData is passing to your UNIX spooler.
If your system has a C compiler, you can code and compile a C program that functions as a “dummy”
spooler. This program interprets UniData commands and reports arguments, but does not actually
perform any spooling. By running the dummy program instead of your default spooler command, you
can test UniBasic PRINT statements or UniQuery reports to determine how UniData interprets your
printing configuration. Complete the following steps to set up the test:

Parent topic: Managing printers on UNIX

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.
.
.
.
:SETPTR
Unit 0
Width 132
Length 60
Top margin 3
Bot margin 3
Mode 1
Options are:
Spooler & options: lp -c
:
In the output for the LIMIT command, look for “U_LPCMD, System spooler name.” In this example,
the current command is lp -c. In the output for the SETPTR command, “Spooler & options” appears at
the bottom of the screen.

2. Create the C program

The following C program, called prtarg.c, captures the arguments that a UniData or UniBasic
printing command sends to your UNIX spooler. Use vi or any UNIX text editor to create the program in
a work directory of your choice.
int argc;
char *argv[ ];
{
int i;
for (i = 0; i<argc; i++)
printf("Argument number %u is ->s\n",i,argv[i]);
return(0);
}

208
 3. Compile the C program

Save the file as prtarg.c.

3. Compile the C program

When you compile the prtarg.c program, you want to produce an executable whose name matches
your default spooler command. In the above example, the spooler command was lp. For some UNIX
versions, the command may be different. Use the cc -o command to compile the program, as shown
in the next example:
# cc -o /usr/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 so
that UNIX locates the dummy version before the real version. The work directory where the dummy
version resides must appear at the beginning of your execution path.
The following sample commands show how to redefine the path:
C shell:
set path=(/users/test/work $path)
Bourne or Korn shell:
PATH=/users/test/work:$PATH;export PATH
Once the path is redefined, your dummy spooler runs in place of the default version.

5. Test UniData printing

With your execution path redefined, log on to a UniData account and test printing commands. The
following screen shows sample output from the dummy spooler for a UniQuery report statement that
includes the LPTR keyword, and from a UniBasic PRINT statement:
:SETPTR 0
Unit 0
Width 80
Length 60
Top margin 3
Bot margin 3
Mode 1

Options are:
Destination laser
Spooler & options: lp -c -dlaser
:LIST VOC WITH F1 = PA LPTR
Argument number 0 is ->lp
Argument number 1 is ->-c
Argument number 2 is ->-dlaser
Argument number 3 is ->/tmp/PRT2a18917
:
:CT BP PRINTON
BP:

PRINTON
PRINTER ON
PRINT “HELLO WORLD”

209
Chapter 13: Managing printers in UniData

END
:RUN BP PRINTON
Argument number 0 is ->lp
Argument number 1 is ->-c
Argument number 2 is ->-dlaser
Argument 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 actual
spooler command runs rather than the dummy spooler program.

210
Chapter 14: Managing cataloged programs
This section describes the behavior of global, direct, and local cataloging for UniBasic programs. It
also describes how to create an alternate global catalog space by using the newhome command.

UniBasic source and compiled programs

UniData stores UniBasic source code in DIR-type files in the UniData account where the source is
developed. The default location for storing UniBasic source code files is the BP file, which UniData
creates as an empty file when you create a UniData account. Developers store UniBasic source code
files as records in the BP file.

Note: In a UniData DIR-type file, like BP, each “record” is a file.

Each UniData account can contain numerous DIR files for UniBasic source.

UniBasic compiled programs

When you issue the BASIC command to compile a UniBasic program, UniData stores the compiled
code in the same DIR file where the source code resides. The compiled code is a record whose name is
the same as the source record, prefixed with an underscore.
See the UniData Commands Reference and Developing UniBasic Applications for information about the
BASIC command.
The following example shows the contents of a program file:
:LIST BP
TEST
_TEST
TEST2
_TEST2
EXAMPLE3
_EXAMPLE3
EXAMPLE5
_EXAMPLE5
8 records listed
Records beginning with an underscore are compiled programs. Other records are UniBasic source
files.

Tip: Use the ECL RUN command to run a compiled program. Refer to the UniData Commands
Reference and Developing UniBasic Applications for information about the RUN command.

Cataloging UniBasic programs

Cataloging UniBasic programs simplifies program execution and can improve efficiency of system
resource use by allowing multiple users to access a single copy of a compiled program from shared
memory. Use the ECL CATALOG command to catalog one or more UniBasic programs.

211
Chapter 14: Managing cataloged programs

Note: See the UniData Commands Reference and Developing UniBasic Applications for information
about cataloging and the CATALOG command.

Compiled UniBasic programs can be cataloged directly, locally, or globally.

• Direct cataloging
• Local cataloging
• Global cataloging

Direct cataloging
Points to remember about direct cataloging are:
▪ Compiled code is located in the program file in the UniData account where the program was
compiled and cataloged.
▪ The VOC file in the account contains a pointer to the compiled code in the program file. Users in the
same account can 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 recatalog
the code if they recompile.
▪ When a user runs a directly cataloged program, UniData loads a copy of the program into the
address space of the user.

Parent topic: Cataloging UniBasic programs

Local cataloging
Points to remember about local cataloging are:
▪ Compiled code is located in the CTLG directory in the UniData account where the program was
cataloged, as well as in the program file. CTLG is a DIR-type UniData file, and each record is a
compiled UniBasic program.
▪ The VOC file in the account contains a pointer to the compiled program in the CTLG. Users in the
same account can 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 compiled
code into the CTLG.
▪ When a user runs a locally cataloged program, UniData loads a copy of the program into the
address space of the user.

Parent topic: Cataloging UniBasic programs

Global cataloging
Points to remember about global cataloging are:
▪ If you run the CATALOG command without specifying local or direct cataloging, your program is
globally cataloged.

212
 Global cataloging

▪ Compiled code is located in a system-wide global catalog. The default global catalog is udthome/
sys/CTLG.
▪ Developers must recatalog a program after it is recompiled it to place a new copy of the compiled
code into the global catalog.

Note: A UniData installation can have more than one global catalog space. The environment
variable UDTHOME determines which global catalog space a particular UniData session
accesses. See Creating an alternate global catalog space, on page 220 for more information
about creating multiple global catalog spaces.

▪ A system-wide global catalog is a DIR-type file, with 26 subdirectories named a through z. Compiled
code is located in the subdirectory corresponding to the first letter of the program name. Compiled
programs that begin with non-alphabetic characters are stored in a subdirectory named X. The
cataloged program name can be the same as the source and object, or you can specify a different
name when you run CATALOG.

Tip: If you are using global cataloging, consider your program naming conventions. Since the
compiled code is placed in subdirectories according to name, you may have an unbalanced
situation if many your program names begin with the same letter (for instance, a general ledger
application where all the files begin with “gl”).

▪ A globally cataloged program is available to users in all UniData accounts.

▫ When you 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 that
copy.
▫ If not, sbcs loads a copy into one of its shared memory segments for the user to run.
▪ The sbcs daemon or service handles any object file that is located in the udthome/sys/CTLG
file system, regardless of how the program is accessed.
▪ The sbcs daemon or service can manage up to 20 shared memory segments for globally cataloged
programs. The size of each segment is determined by the SBCS_SHM_SIZE parameter in the
UniData configuration file. The default value for SBCS_SHM_SIZE is 1,048,576 bytes (1 MB), which
is set when you install UniData. If this size is insufficient, users encounter runtime errors. You can
increase the segment size if you do not exceed the configuration parameter SHM_MAX_SIZE.
▪ For UNIX 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
range from 4 - 8 MB.
▪ Refer to UniData configuration parameters, on page 381 for more information about
SBCS_SHM_SIZE and SHM_MAX_SIZE.

Note: On Windows platforms, globally cataloged programs can not start with a Windows reserved
word and a period, such as AUX.TEST. Calls that are prefixed with Windows reserved words will
cause unexpected consequences. Consult Windows documentation for a list of reserved words.

Parent topic: Cataloging UniBasic programs

213
Chapter 14: Managing cataloged programs

Managing global catalogs

UniData provides a group of files and commands that manage global catalogs. These files and
commands accomplish the following:
▪ Identify the contents of a global catalog space
▪ Verify consistency between UniBasic source and a globally cataloged program
▪ Activate newly cataloged programs and subroutines
▪ Display use of globally cataloged programs

Contents of a global catalog

UniData maintains two files that store contents of a global catalog. The global catalog table, called
CTLGTB, is a dynamically maintained file that shows the current contents of the global catalog.
You can list the catalog table from a UniData account, as shown in the following example:

The _MAP_ file also contains information about the contents of a global catalog. In addition to the
information in CTLGTB, _MAP_ includes the size of each compiled program, the date it was cataloged,
and the last date it was 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:

214
 Verifying a program version

By default, the CTLGTB file and the _MAP_ file are located in the same directory as the global catalog:
udthome/sys.

Tip: The CTLGTB file and the _MAP_ file are UniData hashed files. You can display records in these
files with standard ECL and UniQuery commands to determine if particular programs are in the
global catalog.

Verifying a program version

The VCATALOG command checks the date/time stamp of a UniBasic source file against the compiled
program in the global catalog. If the UniBasic source file was modified after the program was
cataloged, the program does not verify.

Syntax
VCATALOG filename catalog.name program.name

Parameters
The following table describes each parameter of the syntax.

Parameter Description
filename Name of the file that contain the program (BP, for instance).
catalog.name Name given to the program when you run CATALOG. For example, the
command CATALOG BP TRIAL TEST creates a global catalog entry
named TRIAL from a program called TEST. So catalog.name is TRIAL.

215
Chapter 14: Managing cataloged programs

Parameter Description
program.name Name of the program source file. In the example in the previous row 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 UNIX example shows output from VCATALOG:

:VCATALOG BP TEST
Program '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 TEST
Program '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 TEST
Program 'TEST' verifies.
:
In the example, notice that recataloging the program did not make the program verify. This result
indicates that the source code was changed, but was not recompiled or recataloged. After the source
code was recompiled and recataloged, the program verified successfully.
For more information about the VCATALOG command, see the UniBasic Commands Reference.

Activating newly cataloged programs and subroutines

This section describes how to activate newly cataloged programs and subroutines.
• Main programs
When you globally catalog a UniBasic main program, UniData copies the new compiled code into
the global catalog. If a version of the program exists in shared memory, marks that version as
obsolete.
• Subroutines
If 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.

Main programs
When you globally catalog a UniBasic main program, UniData 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 run
the program after the new version is cataloged get the new version. Once all users exit the previous
version, UniData removes the copy of that version from shared memory.

Note: A user that runs a main program continues to run that version until it completes.

Parent topic: Activating newly cataloged programs and subroutines

216
 Subroutines

Subroutines
If 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 prevents inconsistent execution of a subroutine during one execution of the main
program. Under certain circumstances, however, a user or system administrator can override the
default behavior. Overrides are dangerous in a production environment, but may be useful in a
development or test environment.

Parent topic: Activating newly cataloged programs and subroutines

NEWVERSION keyword
The NEWVERSION keyword for the CATALOG command enables a user that is logged on as an
Administrator on Windows or as root on UNIX to dynamically replace a globally cataloged subroutine.
If a subroutine is cataloged with NEWVERSION, any user that execute the main program accesses the
new version of the subroutine with the next CALL or EXECUTE of the subroutine, rather than waiting
until the main program completes.
Consider the following sequence of events:
1. A user 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 is
used for both calls (step 2 and step 4). With the next execution of MAIN, the newly cataloged SUBR is
used.
If SUBR is recataloged after step 1, with the NEWVERSION keyword, then there are three possible
results:
▪ CATALOG happens after step 1 but before step 2. In this case, the newly cataloged SUBR gets
accessed in both step 2 and step 4.
▪ CATALOG happens after step 2, but before step 4. In this case, the prior version of SUBR gets
accessed in step 2, and the newly cataloged version gets accessed in step 4.
▪ CATALOG happens after step 4. In this case, the prior version gets accessed in both step 2 and step
4. With the next execution of MAIN, the newly cataloged SUBR is accessed.

Warning: Using the NEWVERSION keyword to CATALOG a subroutine can produce inconsistent
results for users who are currently running the main program. For example, the number of
arguments 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
:

newversion system-level command

The UniData system-level command newversion enables a user that is logged on as an
Administrator on Windows or as root on UNIX to dynamically replace a cataloged subroutine (just as
the NEWVERSION keyword does), but limits the behavior to a selected user or users.

217
Chapter 14: Managing cataloged programs

Syntax
newversion path userno...

Parameters
The following table describes each parameter of the syntax.

Parameter Description
path Absolute path of the cataloged subroutine.
userno... Process 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 screens show examples of the newversion command:

UNIX example:

In the example, the newly cataloged subroutine is dynamically available to user02, the owner of pid
10846. If user02 is executing a main program that calls a subroutine, the next call to the subroutine
accesses the newly cataloged version. For all users other than user02, the default behavior remains
in effect. The newly cataloged subroutine is activated with the next execution of the main program,
not the next subroutine call. Notice that, in the example, the subroutine is globally cataloged; this
command works with locally or directly cataloged routines as well.
Windows example:

218
 NEWPCODE command

In the example, the newly cataloged subroutine is dynamically available to cgustafso, the owner of
user number 7560. If cgustafso is running a main program that calls a subroutine, the next call to
the subroutine accesses the newly cataloged version. For all users other than cgustafso, the default
behavior remains in effect. The newly cataloged subroutine is activated with the next execution of
the main program, not the next subroutine call. Notice that, in the example, the subroutine is globally
cataloged; this command works with locally or directly cataloged routines as well.

NEWPCODE command
The ECL NEWPCODE command dynamically activates a cataloged subroutine. This command is useful
if a developer uses a UniBasic shell program to modify, recompile, recatalog, and retest a UniBasic
program without exiting to ECL.

Syntax
NEWPCODE path
path is the absolute path of a cataloged subroutine. The following example shows one use of the
NEWPCODE command executed in a UniBasic program:
* PROGRAM MAINPROG
* NEWPCODE EXAMPLE
EXECUTE "MAINPROG2"
EXECUTE "BASIC BP MAINPROG2"
EXECUTE "CATALOG BP MAINPROG2 DIRECT"
EXECUTE "NEWPCODE /usr/ud82/sys/CTLG/m/MAINPROG2"
EXECUTE "MAINPROG2"
END
In the example, a user executing MAINPROG accesses the current version of MAINPROG2 in the first
statement. Including the NEWPCODE command before the next execution of MAINPROG2 causes the
program to access the newest version. (In the example, MAINPROG2 was recompiled and recataloged
after the first step, so the next execution accesses the newly cataloged MAINPROG2.)

Tip: If you are developing programs with the AE editor, the N option of the FI command equates
to the NEWPCODE command. For example, FIBCFN compiles a program and catalogs it (locally)
with NEWPCODE. You need to use F (force) in conjunction with the N option. Refer to the online
help for the AE editor or Developing UniBasic Applications for more information.

Note: The NEWPCODE command is effective only in the udt session where it is executed. Although
NEWPCODE is an ECL command, a user cannot affect a different user or even a different window
with NEWPCODE.

Listing programs in use

The UniData system-level sbcsprogs command enables any user with access to a UNIX shell prompt
to display a list of globally cataloged programs that are currently in use, with counters for the number
of processes currently accessing each one.

Syntax
# sbcsprogs [-fpath | -ppid]
If you specify the -f option with the path to a globally cataloged program, sbcsprogs returns all the
udtnos that have that program attached, as shown in the following example:
<bronco-73 109> sbcsprogs -f/bronco3/ud82/sys/CTLG/p/P1

219
Chapter 14: Managing cataloged programs

Program Name Reference Count Obsolete

/bronco3/ud82/sys/CTLG/p/P1 1 0
PID:545004
/bronco3/ud82/sys/CTLG/p/P1 1 1
PID:991428
If you specify the -p option with a pid, sbcsprogs returns all objects attached to that pid, as shown
in the following example:
<bronco-73 113> sbcsprogs -p545004

Programs Referenced by process 545004

Program 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:
# sbcsprogs
Program 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
In the example, two users are executing AE, and two are executing AE_AE. The sbcs daemon
maintains the counter, incrementing it as users execute a program and decreasing it as users
complete execution. When the counter for a routine reaches zero, sbcs removes the copy of the
compiled program from shared memory, making the space available for other programs as needed.

Tip: If you run sbcsprogs regularly throughout your processing cycle, you can learn which
programs are used most heavily. This information is useful if you are troubleshooting an
application performance problem.

Note: The reference counter is not decremented when a user terminates abnormally (for example,
when a process is killed). Because of this, the count may be inaccurately high, causing excess
memory to remain held. Stopping and restarting UniData resets the counter and releases memory.

Creating an alternate global catalog space

The system-level newhome command creates a new UniData account containing an alternate global
catalog space for use in development and testing.

Files and directories created by newhome

UniData creates or overlays the directory indicated by path.
This directory contains only the subdirectory sys, which contains the following files and directories:

220
Files and directories created by newhome

221
Chapter 14: Managing cataloged programs

The following directories make up the program catalog spaces:

▪ D_CTLGTB
▪ CTLGTB
▪ D_CTLG
▪ CTLG, including subdirectories a through z and X for storing globally cataloged programs.
newhome does not create the entire directory structure that exists in the default UniData home
directory, and it does not copy UniBasic executables developed at your site.

Creating an alternate global catalog space

Follow the steps below to create an alternate global catalog space.
1. At the operating system prompt, change to the directory in which you intend to locate the new
UniData account.
2. Execute the newhome command, indicating the path to the new account.
In the following example, a new directory, testenv, will be created under the directory you
created in the previous step.
UNIX example:

222
 Creating an alternate global catalog space

:!$UDTBIN/newhome testenv

Creating new udt home /home/claireg/demo/testenv ...

The new UDTHOME is established, now only the sys directory

is there and it contains all the UniData system cataloged
programs, such as AE editor, NFA sever, etc.. To make it be
effective, the environment variable UDTHOME needs to be set
to point to the new UDTHOME.

Note: (If the udtbin directory is in your path, you do not have to precede the command with
udtbin.)

Windows example:
:!newhome testenv
Creating new udt home \UniData82\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. Decide which UniData accounts should access the new global catalog space. For each account,
modify the VOC entry for CTLGTB. The entry should point to the new global catalog space, as
shown in the following example.

Note: You do not need to log on as an Administrator on Windows or as root on UNIX to edit
the VOC entries; however, you need write permissions on the VOC file in each account.

Notice that this example uses a soft pointer to @UDTHOME. This ensures that the VOC always
points to the correct catalog space. Refer to UniData and the UNIX file system (UNIX only), on
page 326 for information about setting soft pointers in VOC entries.
:AE VOC CTLGTB
Top of "CTLGTB" in "VOC", 3 lines, 45 characters.
*--: P
001: F
002: @UDTHOME/sys/CTLGTB
003: @UDTHOME/sys/D_CTLGTB
Bottom.
*--:
4. Modify UDTHOME for users. You need to reset the UDTHOME environment variable for each user
who needs to access the alternate global catalog space. The value of UDTHOME defined during a
particular UniData session determines the global catalog space a user accesses.

Note: Even if the VOC file of an account is set up to point to the alternate global catalog
(CTLGTB), a user whose UDTHOME is set to the default value accesses the default global
catalog space.

On UNIX, you can modify the UDTHOME variable in a user’s .login or .profile. Simply use vi or any
UNIX text editor to change the variable setting. The user must then log out and log back on to
make the change effective. Users with access to a UNIX shell prompt can reset the UDTHOME
environment variable with the setenv command. The value set at the UNIX prompt overrides
the .login or .profile:
% printenv UDTHOME
/disk1/ud82
% setenv UDTHOME /home/carolw/demo/testenv

223
Chapter 14: Managing cataloged programs

% udt
UniData Release 8.2.1 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. After resetting UDTHOME to point to the new space, start UniData from an account that has
access to the site-specific programs that you want to access from the new account, and recatalog
those programs. Because you have reset the UDTHOME environment variable, UniData places the
recataloged programs in the new space.
On UNIX, you can also use the following series of UNIX commands to copy all globally cataloged
programs to the new catalog space. Be sure to replace original_udthome and new_udthome with
the paths to your old and new catalog spaces:
%cd original_udthome/sys/CTLG
find * -type f -print | cpio -pm new_udthome/sys/CTLG
6. Use the alternate global catalog space.
The following example shows the output of the sbcsprogs command when two global catalog
spaces are used:
% sbcsprogs
Program Name Reference Count
... 1
/home/carolw/demo/testenv/sys/CTLG/a/AE
/home/carolw/demo/testenv/sys/CTLG/a/AE_UPS 1
/disk1/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 catalog
spaces.

Using an alternate global catalog space

Once you have created an alternate global catalog space using the newhome command, complete the
following 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 correct
UDTHOME to ensure that the alternate global catalog space is used.
The following example illustrates an entry for “demo_newhome” that points to the newhome
path.
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. UNIX only: Before you start a UniData session, set the UDTHOME environment variable. For
information about setting environment variables, see Setting an Environment Variable, on page
328.

Note: Executing SETENV within a connection does not change the default UDTHOME for a
user, and the user will still access the default global catalog space.

224
 Using an alternate global catalog space

3. Windows only: You can specify a specific UDTHOME for telnet users using XAdmin. For more
information, see Modifying the UDTelnet session parameters, on page 44.

225
Chapter 15: Account-based licensing
This section describes how to use UniData’s account-based licensing system.
Using account-based licensing, the number of purchased licenses can be divided to different accounts
or group of accounts. These account groups are referred to as logical account IDs. The number of
licenses can be configured to allocate to each logical account ID, and then UniData will automatically
manage 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 apply
to installations that do not have device licensing enabled.

Note: Account-based licensing does not support device licensing across multiple account groups.

Managing the license configuration

To 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 following
example 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, which
can 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 specified
for 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 account
ID.
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 of
licenses purchased. If the sum of logical account database seats is less than the number of purchased
licenses, the remaining licenses will be used by the Default group. The Default group is a catch-all that
is 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 the
UniData demo account by default.

226
 Managing account-based licensing with listuser -a

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:
• Verifying the acct_licn.def file
Use the listuser -a check command to check the syntax of the acct_licn.def file and
report any errors.
• Listing the acct_licn.def file
Use the listuser -a list command to list the contents of the acct_licn.def file.
• 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 take
effect.

Verifying the acct_licn.def file

Use the listuser -a check command to check the syntax of the acct_licn.def file and
report any errors.
If a syntax error exists in the acct_licn.def file, UniData ignores all definitions in the file and starts
UniData 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 the
acct_licn.def file:
[root@den-vm-t19 include]# listuser -a check
Checking "/usr/ud82/include/acct_licn.def" ......
Everything is OK.

Parent topic: Managing account-based licensing with listuser -a

Listing the acct_licn.def file

Use the listuser -a list command to list the contents of the acct_licn.def file.

Parent topic: Managing account-based licensing with listuser -a

227
Chapter 15: Account-based licensing

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 take
effect.
The following example shows how to reload the file using the listuser -a reload command:

Note: If reloading the acct_licn.def encounters an error, UniData does not replace the
current configuration.

If you change the number of licenses allocated to an account and the number of users currently logged
on exceeds that number, UniData displays an error. Users need to log out of the account until the limit
is not exceeded before UniData loads the new configuration.

Parent topic: Managing account-based licensing with listuser -a

228
Chapter 16: Managing and using tape devices
(Windows only)
This section describes UniData commands for identifying and accessing Windows tape devices.

Tip: When you define tape devices within UniData, you must use the Universal Naming Convention
(UNC) format for device names. Refer to your Microsoft documentation for information about UNC
format.

Note: Due to internal constraints, while some individual functions may work as expected, UniData
does not support use of UNC paths to reference files on Windows platforms.

UniData tape handling commands

UniData includes a number of ECL and UniBasic commands for reading data from a tape and writing
data to a tape.
The ECL commands are summarized in the following table.

Command Description
SETTAPE Defines a logical tape unit in UniData; must precede any other tape commands.
T.ATT Links a logical tape unit to a UniData process; must precede any reads/writes
involving the tape.
T.BAK Moves a tape backward by a specified number of files.
T.CHK Reads a tape created by T.DUMP and checks for damage.
T.DET Releases a logical tape unit when a UniData process is finished with it.
T.DUMP Copies the contents of a file or active select list to tape.
T.EOD Moves a tape unit to end of file.
T.FWD Moves a tape unit to the beginning of the next file.
T.LOAD Loads records from a tape created with T.DUMP.
T.RDLBL Reads and displays the first 80 characters of the tape label on a tape created
with T.DUMP.
T.READ Reads and displays the next record from tape.
T.REW Rewinds a tape to the beginning.
T.SPACE Moves a tape forward a specified number of spaces.
T.STATUS Displays current tape device assignments.
T.UNLOAD Rewinds and unloads a tape.
T.WEOF Writes an end-of-file mark on a tape.

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.

229
Chapter 16: Managing and using tape devices (Windows only)

Command Description
RESIZET Changes the block size that is used by the WRITET statement.
REWIND Rewinds a tape to the beginning.
WEOF Writes an end-of-file mark to a tape.
WRITET Writes the value of a specified expression as a record on a tape.

Note: See the UniBasic Commands Reference for information about these UniBasic commands.

SETTAPE
The SETTAPE command defines logical tape units in your UniData environment.

Syntax
SETTAPE unit.no [dn.path.nr][dn.path.r][blocksize]

Description
This command establishes a link between a UniData internal tape unit number and a tape device. You
can use SETTAPE to relate unit number to tape devices or disk files.
Any user can run SETTAPE unit.no to display the current settings for a tape unit. However, you
must log on as an Administrator to define a tape unit or modify settings.
Once a tape unit has been defined by using SETTAPE, it can be accessed by users in any UniData
account on your system. The tape unit definition remains the same unless it is changed by an
Administrator.

Parameters
The following table describes the parameters of the SETTAPE syntax.

Parameter Description
unit.no Internal UniData tape unit number. Must be from 0 to 9. The default tape
unit is 0.
[dn.path.nr] Device name, in UNC format, or full path and file name of disk file for no
rewind device driver for unit.no.
[dn.path.r] Device name, in UNC format, or full path and file name of disk file, for
rewind device driver for unit.no.
[blocksize] Tape block size in bytes. It must be a multiple of 512. If you do not
specify blocksize, the default value is 4096.

Writing to a device
To relate a tape unit number to a tape device, use the full UNC format for the device name in the
SETTAPE command syntax. The following example shows how to identify a tape device with
SETTAPE:
:SETTAPE 0 \\.\TAPE0 R\\.\TAPE0 16384

230
 Steps for tape device use

Writing to a file
To relate a tape unit number to a disk file, use the full path and file name in the SETTAPE command
syntax. The disk file must already exist. The following example shows how to identify a disk file with
SETTAPE:
:SETTAPE 1 A:\TAPEFILE RA:\TAPEFILE 4096

Steps for tape device use

The following steps must take place, in order, for successful tape device use from UniData.

1. Define tape units

A user with Administrator privilege must run the SETTAPE command to define up to 10 tape units for
the UniData environment.

Note: Remember that the tape unit number must be from 0 through 9. These are logical tape unit
numbers within UniData. The SETTAPE command maps these to Windows device names.

Warning: When you define tape units, be sure to define unit 0. Some of the UniData tape handling
commands require unit 0 to be defined so that it can be used as a default.

When you define a tape device or modify a definition, you create or update an entry in the text file
udthome\sys\tapeinfo.

2. Attach a Tape Device

You must attach a logical tape device to your process before you can access it. The T.ATT command
attaches a tape device. Any user can run T.ATT from the ECL prompt or from within a UniBasic
program. The following screen shows some typical outputs from T.ATT:
:T.ATT 5
No information for unit 5 yet, ask your system administrator for help.
T.ATT failed.
:T.ATT 1
unit 1 is attached by another process
It is lock number 65 in LIST.LOCKS.
Try again later, T.ATT failed.
:T.ATT 2 BLKSIZE 16384
tape unit 2 blocksize = 16384.
:
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 successive times to change the tape block size and also the tape length. If you
do not specify BLKSIZE, T.ATT uses the default tape block size specified in SETTAPE.
▪ Only one process can attach a tape unit at any time. You can attach more than one tape unit to a
single process, but you cannot attach the same tape unit to more than one process.
▪ You can use the ECL T.STATUS command to list all defined tape units, and see which ones are
attached and which are available. The following screen shows sample output from T.STATUS:

231
Chapter 16: Managing and using tape devices (Windows only)

Notice that the “tape devices” for tape units 1 and 2 are disk files. A:\TAPEFILE is a FAT file, while 1
is an NTFS file. When you use a disk file as a tape device the functionality is naturally limited to simple
loads and unloads, but this might be useful for demonstration or testing.

Warning: Do not specify a disk drive (for instance, A:) as a tape device. SETTAPE might succeed,
but you will be unable to write to the disk drive. If you wish to dump files to disk, create disk files
and then specify the disk files as tape devices.

3. Read from, or write to, the tape device

When a tape unit is attached, you can access it from ECL or within a UniBasic program. The following
example shows typical outputs when a process with tape unit 1 attached runs the ECL T.DUMP
command:

Notice the following points about the example:

▪ You cannot write to a tape device unless it is attached with T.ATT. If you have attached more than
one device, you must specify the device to write to or read from. If you have attached only one
device, UniData accesses the device you attached.

1
\USERS\DEFAULT\TAPEFILE

232
 4. Release the tape device

▪ With T.DUMP, you can write from an active select list.

▪ If you supply a single-digit value (for instance, 4) UniData interprets the digit as the conversion
code, and attempts to attach the default device (unit 0).

Note: When you access a tape device, the operation fails if the device is not properly connected
or if the device does not have a tape mounted. The UniData T.ATT and SETTAPE commands
do not detect device configuration problems, so you may be able to define and attach a device,
but be unable to complete your access to it.

4. Release the tape device

When you have finished using a tape device, use the T.DET command to release the device so that
another UniData process can use it. If you have attached more than one device, you must release
each one separately. If you have attached only one, the T.DET command releases the one you have
attached. You can execute T.DET from ECL or from within a UniBasic program.

233
Chapter 17: CallC and CallBasic (Windows only)
UniData provides the UniBasic CALLC command for running functions that are written in C, C++, or
Delphi from UniData, and the CallBasic API for running UniBasic subroutines from external programs.
This chapter describes commands and procedures for using these tools.

Note: For more information about the syntax and use of the CALLC command, see the UniBasic
Commands Reference.

Dynamic Link Libraries (DLLs) and UniData

Both the CALLC implementation and the CallBasic implementation in UniData for Windows Platforms
use the Microsoft Windows Dynamic Link Library (DLL) facility. This facility allows separate pieces of
code to call one another without being permanently bound together. Linking between the separate
pieces is accomplished at runtime (rather than compile time) through a Dynamic Link Library (DLL)
interface. Both the CALLC interface (for calling external functions from UniData) and the CallBasic
interface (calling UniData functions from external code) are implemented as DLLs.
▪ For CALLC, developers create a DLL and then call that DLL from UniData. Special VOC entries for
each function that is called from a DLL communicate interface information to UniData.
▪ For CallBasic, developers link their code with UniData.LIB (located in the UniData bin directory)
and then make calls into the UniData DLL. The .LIB file supplies interface information.
Because linking between caller and DLL is accomplished at run time, either the caller or the DLL can be
modified independently. For UniData, this behavior means that you can upgrade your UniData version
without the need to relink with external routines, and you can update your external DLL without the
need to relink UniData.
A DLL is language independent. Many software development environments for Windows can produce
a DLL.

Note: Consult the documentation for your software development environment for information
about linking code into a DLL.

Calling external routines from UniData

Many applications use functions that are written in high-level languages like C++ for purposes such as
environment definition, security, or low-level data transfers (similar to the UniBasic GET and SEND
functions). Through the CALLC command, UniData enables you to access such functions from within a
UniBasic application using CALLC commands.

Note: When you use CALLC, your functions are executed by a udt process. They are not visible to
the end user at all.

Requirements for CALLC

If you want to use CALLC to access functions in an external DLL you need a full software development
kit for the language you are using. (A base compiler may not be sufficient).

234
 Steps for CALLC

Tip: Refer to your host operating system documentation and your hardware vendor if you have
questions about your development environment.

Steps for CALLC

To use CALLC, complete the following steps:
1. Code the function.
Code the external program using C, C++, or Borland Delphi. Make certain that all the functions to
be called from outside the program are exported in one of the following ways:
▪ A _declspec( dllexport ) statement.
▪ An EXPORTS statement. The EXPORTS statement lists the names and optionally the ordinal
values of the functions exported by the DLL. When you specify ordinal values, they must be in
the range 1 through n, where n is the number of functions exported by the DLL.
See Examples, on page 237 for information about exporting functions.
2. Compile and link.
Compile the function or functions and link the code into a DLL.

Warning: UniData for Windows Platforms takes full advantage of the Win32 environment. The
UniData DLL is a 32-bit DLL, and any DLLs you call via CALLC must also be 32-bit DLLs. You
cannot call a 16-bit DLL from UniData.

3. Create VOC entry.

Create a VOC entry for every function that you can call from the DLL. You must create an E type
record in the VOC file in every UniData account where you will be calling the functions. The VOC
entry contains information that enables UniData to locate and execute the called function.
The following sections provide additional detail about the CALLC implementation on UniData for
Windows Platforms.

CALLC and UDT.OPTIONS 88

There are two ways one function can call another in a stack-based architecture:
▪ Pascal calling convention
▪ _cdecl calling convention
The Pascal style calling convention is the default for UniData.

Note: For C and C++, the default calling convention is _cdecl. For Delphi, the default calling
convention is Pascal. You can use the Pascal convention in C or C++, and you can use the
_cdecl convention in Delphi; consult the documentation for your development environment for
information about choosing a calling convention.

UDT.OPTIONS 88 allows CALLC to function correctly with both _cdecl and Pascal style calling
conventions. The following table describes the behavior of CALLC commands with this option turned
on or off:

235
Chapter 17: CallC and CallBasic (Windows only)

UDT.OPTIONS 88 _cdecl convention Pascal convention

OFF (default) CALLC fails, terminating the CALLC executes.
UDT
ON CALLC executes CALLC fails, terminating the
udt.

Warning: As the preceding table indicates, calling a function with the wrong UDT.OPTIONS 88
setting almost certainly terminates a udt session and may produce other undesirable results.

CALLC syntax and data types

The UniBasic CALLC command has the following syntax:
rtn = CALLC function(arg1,arg2,...argn)
The following table describes each parameter of the syntax.

Parameter Description
rtn Return value from CALLC. Must be a valid data type.
function The name of the external function being called.
arg1,....argn Arguments to the external function. Each must be a valid data type.

Valid data types for return values and arguments are listed in the following table.

Data type Description

CHAR Signed byte.
INT Integer (32-bit signed).
POINTER 32-bit signed long word.
SHORT Short (16-bit) integer.
LONG Long integer.
STRING Pointer to a null-terminated character string in a 34K buffer.
CHAR_PTR Pointer to a null-terminated character string.
INT_PTR Pointer to a 32-bit signed long word.
SHORT_PTR Pointer to a 16-bit integer.
LONG_PTR Pointer to a 32-bit integer.
DOUBLE Double.
DOUBLE_PTR Pointer to a double.
BSTRING Pointer to a binary string descriptor.
NONE Use for functions that do not return anything (for instance, VOID).

E type VOC entries

An E (executable) type VOC entry identifies the DLL for an external function being called using CALLC,
and identifies the data types for its arguments and return value.

236
 Examples

Tip: On UniData for UNIX, this information is stored in the cfuncdef_user file.

The following table defines the attributes required for an E type VOC entry.

Attribute Description
@ID Function name.
Attribute 1 VOC entry type; must be E.
Attribute 2 Location of DLL. Must be a fully qualified path, a path relative to the current
working directory, or a name that can be located through the user’s Path
environment variable.
Attribute 3 Function name in the DLL.
Attribute 4 Data type for return value.
Attribute 5 Data type for first argument.
Attributes 6 - n Data types for second through nth arguments.

The following screen shows the VOC entry for a function named callcpp_subr1:
:CT VOC callcpp_subr1
VOC:
callcpp_subr1:
E
CALLC_DEMO\CALLC_CPP\callcpp_test.dll
callcpp_subr1
INT
INT
SHORT
LONG
CHAR
STRING
POINTER
:
Notice that this subroutine expects six arguments, and returns an INT. The subroutine is accessed
from a dynamic linked library called callcpp_test.dll.

Warning: We recommend that you keep your development environment clearly separate from
your production environment when developing a CALLC application. Separating environments is
useful in any case, but can be critical because difficulties in the external functions can terminate
udt sessions and potentially damage data.

Examples
At this release, UniData includes examples that demonstrate the components of CALLC for each of
three supported languages: C, C++, and Delphi. Each example includes a subdirectory that contains
the source code, make file, and DLL for the external routines. Each example also includes a UniBasic
program that calls a function or functions from its DLL. The following section describes the CALLC
examples.

237
Chapter 17: CallC and CallBasic (Windows only)

CALLC example programs

The subdirectories for the three CALLC examples are all included in the CALLC_DEMO folder,
which is in the demo folder in your UniData directory. The following window shows the structure of
CALLC_DEMO:

Note: The example components (particularly the UniBasic programs) are greatly oversimplified.
They are meant to illustrate the relationships between components in the CALLC implementation,
not to illustrate particular coding techniques.

C example
The C example contains the components shown on the following window:

238
 C example

The example also includes the UniBasic program EXAMPLE_C, in the BP file in the demo account.
Notice that, in the C example, a single program source file was compiled and linked to form the DLL.
One function, called ps, can be called from the DLL. The function accepts a process ID, opens the
Registry, and collects information about that process. The information is returned to the UniBasic
program that called the ps function.
The next example shows a portion of the source code in psdll.c:
.
.
.
#define DllExport _declspec( dllexport )
#define DllImport _declspec( dllexport )
.
.
.
struct _TIME_FIELD
{
INT Hours;
INT Mins;
INT Secs;
INT mSecs;
};

DllExport int ps( int processid, char *process_name, char

*process_creator,
char *processor_time, int *vmemory )
{
HANDLE

239
Chapter 17: CallC and CallBasic (Windows only)

hProcess, hProc\
essToken;
.
.
.
Notice the following points:
▪ The program was written using the _cdeclspec statement to export a function. (See the two lines
that begin #define and the line that begins DllExport int ps).
▪ The DllExport specifies that a function called ps can be called from the DLL, and defines the
arguments for the ps function.
The next example shows the VOC entry for the ps function:
:CT VOC ps
VOC:
ps:
E
CALLC_DEMO\CALLC_C\psdll.dll
ps
INT
INT
STRING
STRING
STRING
INT_PTR
:
The following example is a portion of the sample UniBasic program that calls the ps function:
.
.
.
PRINT "TURNING ON UDT.OPTIONS 88; REQUIRED FOR C"
PERFORM "UDT.OPTIONS 88 ON"

PRINT "THE ID OF MY CURRENT UNIDATA PROCESS IS: ":@USERNO

PRINT "PASSING THE ID TO THE C ROUTINE."
pid = @USERNO
pname = ‘’
cname = ‘’
ptime = ‘’
virt_mem = 0

RESULT = CALLC ps(pid, pname, cname, ptime, virt_mem)

PRINT "THE C ROUTINE RETURNED: ":RESULT
IF RESULT >= 0 THEN
PRINT
.
.
.
END ELSE
PRINT "AN ERROR HAS OCCURRED IN THE C ROUTINE."
END
PRINT "TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING"
PERFORM "UDT.OPTIONS 88 OFF"

STOP
END
Notice the following points:
▪ The function name in the CALLC statement matches the name in the E type VOC entry.

240
 C++ example

▪ By default, the calling convention for a C program is the _cdecl convention. Therefore,
UDT.OPTIONS 88 must be turned on.
▪ Error handling is based on the RESULT from the C function rather than the STATUS of the CALLC
statement. The statement can complete successfully (STATUS of 0) even if the C function has
encountered an error.
The next example shows output from the sample program:

C++ example
The following screen shows the components of the C++ example:

241
Chapter 17: CallC and CallBasic (Windows only)

In this example, three functions are compiled and linked into a single DLL. The file callcpp.def lists
the functions that can be called from the DLL:
LIBRARY callcpp_test
DESCRIPTION 'For CALLC test on .cpp files'
EXPORTS
callcpp_subr1 @1
callcpp_subr2 @2
callcpp_subr3 @3

Tip: The example was developed using Visual C++. Consult the documentation for your
development environment for information about file naming conventions and procedures for
creating a DLL.

Notice the following points:

▪ The EXPORTS statement is used to export the three functions that can be called from the DLL.
▪ The names of the functions you can call do not need to match the names of the source files,
provided they are correctly defined.
The UniBasic program EXAMPLE_CPP calls one of the three functions from callcpp_test.dll. A
segment of this program is shown in the next example:
.
.
.
PRINT "TURNING ON UDT.OPTIONS 88 FIRST; NEEDED FOR C++"
EXECUTE "UDT.OPTIONS 88 ON"
RESULT = CALLC callcpp_subr3(int,short,long,char,string,filename)
PRINT "THE SUBROUTINE RETURNED: ":RESULT
.
.
.

242
 C++ example

PRINT "TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING"

EXECUTE "UDT.OPTIONS 88 OFF"
STOP
END
Notice the following points:
▪ Because the default calling convention for C++ is the _cdecl convention, UDT.OPTIONS 88 must be
turned on.
▪ The program prints the value returned by the function (a value of 0 or greater is successful) rather
than the STATUS of the CALLC command. The CALLC command can complete successfully,
returning a STATUS of 0, even if a problem occurred in the C++ function.
▪ The name of the function in the CALLC command must match the name in the E type VOC entry,
which also matches the name in the callcpp.def file.
Notice that the program calls a single function (callcpp_subr3) from the DLL. The next screen shows
the VOC entry for callcpp_subr3:
:CT VOC callcpp_subr3
VOC:
callcpp_subr3:
E
CALLC_DEMO\CALLC_CPP\callcpp_test.dll
callcpp_subr3
INT
INT
SHORT
LONG
CHAR
STRING
STRING
:

Tip: You can link a number of external functions into a single DLL, if this makes sense from an
application point of view. Each function has its own VOC entry. You can then access one or several
functions in the same UniBasic program through CALLC statements.

The following screen shows a portion of the program source for callcpp_subr3:

The next screen shows output from the sample UniBasic program:

243
Chapter 17: CallC and CallBasic (Windows only)

:RUN BP_SOURCE EXAMPLE_CPP

THIS UNIBASIC PROGRAM PASSES A GROUP OF ARGUMENTS TO A
C++ ROUTINE, WHICH WRITES THE VALUES TO AN OUTPUT FILE.
TURNING ON UDT.OPTIONS 88 FIRST; NEEDED FOR C++
HERE ARE THE INPUT ARGUMENTS FOR THE ROUTINE.
THE int ARGUMENT IS: -1.347
THE short ARGUMENT IS: -12345678
THE long ARGUMENT IS: 3
THE char ARGUMENT IS: 1
THE string ARGUMENT IS: 12345
RESULTS ARE WRITTEN TO THE OUTPUT FILE NAMED: outfile
THE SUBROUTINE RETURNED: 0
EXECUTION COMPLETE.
THESE ARE THE RESULTS FROM THE OUTPUT FILE.
value of int argument : -1
value of short argument : -24910
value of long argument : 3
value of char argument : 1
value of string argument: 12345
TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING
Notice that, in the output, the C++ function has returned the correct values based on the input
arguments and data types.

Pascal style example

The following screen shows the components of the Pascal style example:

244
 Pascal style example

Tip: The example was developed using Borland Delphi Developer Version 2.0. Consult the
documentation for your development environment for information about naming conventions and
requirements for creating a DLL using Delphi.

In this example, there is a single program source file called calldelphi.dpr. A segment of this file
follows:
.
.
.
{ This function returns the larger number of the two input intergers }
function Pascal_subr2(X, Y: Integer): Integer; stdcall;
begin
if X > Y then Pascal_subr2 := X else Pascal_subr2 := Y;
end;
exports
Pascal_subr1 index 1,
Pascal_subr2 index 2;
begin
end.
.
.
.
Notice that two Pascal functions are defined within the source file. The exports statements allow
both functions to be called from the DLL. The sample UniBasic program EXAMPLE_DELPHI calls
Pascal_subr2, as shown in the following program segment:
.
.
.
LOOP WHILE I < 6 DO
ret = CALLC Pascal_subr2(NUM1,NUM2)
PRINT “THE FIRST NUMBER IS: ":NUM1:" AND THE SECOND NUMBER IS: "
:NUM2
PRINT "THE BIGGER ONE IS:":ret
NUM1-=473
NUM2+=473
I+=1
REPEAT
.
.
.
The next screen shows the output from the sample UniBasic program:
:RUN BP_SOURCE EXAMPLE_DELPHI
THIS UNIBASIC PROGRAM CALLS A DELPHI (PASCAL-STYLE)
ROUTINE THAT COMPARES TWO NUMBERS AND REPORTS THE
LARGER ONE.
TURNING OFF UDT.OPTIONS 88; REQUIRED FOR PASCAL STYLE
STARTING WITH TWO NUMBERS; CALLING THE SUBROUTINE AND
REPORTING THE RESULT, THEN CHANGING THE NUMBERS.
THE FIRST NUMBER IS: 5000 AND THE SECOND NUMBER IS: 4000
THE BIGGER ONE IS:5000
THE FIRST NUMBER IS: 4527 AND THE SECOND NUMBER IS: 4473
THE BIGGER ONE IS:4527
THE FIRST NUMBER IS: 4054 AND THE SECOND NUMBER IS: 4946
THE BIGGER ONE IS:4946
THE FIRST NUMBER IS: 3581 AND THE SECOND NUMBER IS: 5419
THE BIGGER ONE IS:5419
THE FIRST NUMBER IS: 3108 AND THE SECOND NUMBER IS: 5892
THE BIGGER ONE IS:5892

245
Chapter 17: CallC and CallBasic (Windows only)

THE FIRST NUMBER IS: 2635 AND THE SECOND NUMBER IS: 6365
THE BIGGER ONE IS:6365
:
Notice the following points:
▪ Because the default calling convention for Delphi is the Pascal convention, UDT.OPTIONS 88 must
be turned off before the CALLC statement.
▪ In this example, the return from the function is the larger of the two numbers passed as arguments.
There is no particular error handling.

Accessing UniData from an external program

The CallBasic application programming interface (API) enables you to access a UniData database by
calling UniBasic subroutines from an external program written in C or other high-level languages. The
CallBasic API is particularly useful for applications like automated processes that gather data and then
write the data into a UniData database. The main body of the application may be written in another
language, and the application uses a UniBasic subroutine, called through CallBasic, to write the data
into UniData hashed files in correct format.

Note: When you use CallBasic, your UniBasic routines are called from an external program.
UniBasic and UniData are invisible to the users of the external program.

Requirements
The components required to use the CallBasic API are:
▪ Development environment—Your system should have a full software development kit for the
language you are using. (A base compiler is not sufficient).

Tip: Consult your host operating system documentation and your hardware vendor if you have
questions about your development environment.

▪ Application programs—You must code and compile the application that will call UniBasic. Since
you will be calling into the UniData DLL, you must link your code with UniData.LIB.
▪ Cataloged UniBasic subroutines—You must code, compile, and globally catalog your UniBasic
subroutines.

How CallBasic works

The CallBasic API includes four functions:
▪ udtcallbasic_init( )—This function initializes UniData and CallBasic. It serves the purpose of
opening a “UniData session” for your application. Your program must execute this function once
and only once.
▪ U_callbas( )—This function calls a UniBasic subroutine, passing arguments, and returns the
address of the buffer containing the results. You may execute this function numerous times in
your application, each time you want to call a UniBasic subroutine. The syntax for U_callbas is
supported if the calling language is C.

246
 Examples

▪ udtcallbasic( )—This function calls a UniBasic subroutine, passing arguments, and returns
a pointer to the results. The syntax of this function is required if the calling language is not C,
because the definition of the return buffer is consistent between the external program and the
call with udtcallbasic. The user is responsible for allocating memory for the buffer to store
results. You may execute this function numerous times in your application when you want to call a
UniBasic subroutine.
▪ udtcallbasic_done( )—This function clears all UniData-related temporary files and other
resources, and ends the interface between the application and UniData. You must execute this
function once in your application. You must also include this function in any error exits in your
application that may be taken after udtcallbasic_init.

Note: See Developing UniBasic Applications for a detailed description of the CallBasic functions
and their requirements.

Examples
At this release, UniData supplies two simple examples that illustrate the CallBasic functionality.

CallBasic example 1
This example consists of a C routine that calls a UniBasic subroutine to display two arguments. The C
routine (which also includes C++ syntax for function declarations) is located in the CALLBASIC_DEMO
subdirectory of the UniData demo account, in the EXAMPLE1 folder. The UniBasic subroutine is
located in the BP file of the UniData demo account.
The following sections of this chapter use the C routine and UniBasic subroutine from this example.

CallBasic example 2
This example consists of a Windows application written in Visual C++ that allows users to add,
update, find, or delete records from a small UniData hashed file. The C++ program accesses the
UniData file with CallBasic. The components of this example are in the BP file and in the subdirectory
CALLBASIC_DEMO (EXAMPLE2 folder), both in the UniData demo account.

Warning: Do not execute the second example from a Telnet session; the example is a Windows
application. Also, note that the examples only illustrate the relationship between components of
CallBasic. They are not intended to demonstrate optimum coding technique.

Sample programs
The following C program, called callbasic_example1.c, is an extremely simplified example that
illustrates the components required for CallBasic:

C program example
The following C program, called callbasic_example1.c, is an extremely simplified example that
illustrates the components required for CallBasic:

247
Chapter 17: CallC and CallBasic (Windows only)

248
 C program example

Notice the following points about callbasic_example1.c:

C and C++ syntax

The example shows the correct syntax for declaring the UniBasic functions in both C++ (#ifdef CPP)
and C.

Header files
You must include stdio.h and windows.h.

Initializing CallBasic
This statement initializes CallBasic, effectively starting a udt session for your C program:
udtcallbasic_init(0, 0);
Notice that it is executed once and only once in the C program.

249
Chapter 17: CallC and CallBasic (Windows only)

Warning: If you initialize CallBasic more than one time or you do not initialize at all, you will
encounter errors and your program may fail with an exception.

Calling a UniBasic subroutine: U_callbas

In this statement, we call the subroutine and assign the return to a variable.
char *rtn;
.
.
.
/* Call the subroutine */
sts = U_callbas(&rtn, "EXAMPLE", 2, args);
Notice the definition of rtn in the program (character pointer) and the usage of rtn in the U_callbas
statement (address). The difference between definition and usage is because, when you use
U_callbas, the system allocates memory for the return variable. Passing the address of rtn allows
U_callbas to pass back the address of the allocated memory.
Remember you can call more than one UniBasic subroutine, using the U_callbas function, as long as
you do so between initializing and closing CallBasic.

Freeing memory
Each U_callbas execution allocates memory; you must free the memory after conclusion of the
subroutine. If you do not free the memory, your application is said to have a “memory leak” which
can cause significant performance degradation over time. On Windows platforms, variables returned
by UniData are allocated from the process heap rather than from the C-Runtime heap. Because of
this, you must use the HeapFree API, rather than the free( ) function, to free the memory allocated by
UniData, as shown below:
if (sts == 0){
printf("Return value from UniBasic subroutine is %s\n",rtn);
/* Variable rtn returned by UniData come
from the process heap, not the C-Runtime
heap. It cannot be free'd with free().
They must be free’d with HeapFree().
*/
HeapFree(GetProcessHeap(), 0, rtn);
Notice that you need to free the memory if the function completes successfully; UniData frees the
memory if the function fails.

Calling a UniBasic subroutine: udtcallbasic

The following program segment allocates memory for the return variable, then calls the subroutine:
/* Allocate memory for return variable */
rtn = (char *)malloc(256);
printf("\nExecuting UniBasic subroutine using udtcallbasic()...\n");
/* Call the UniBasic subroutine using udtcallbasic. */
sts = udtcallbasic(rtn, "EXAMPLE", 2, args[0], args[1]);
if (sts == 0){
printf("Return value from UniBasic subroutine is %s\n", rtn);
}
/* Free memory */
free(rtn);
/

250
 Freeing memory

When you use the udtcallbasic function, your calling process is responsible for allocating and freeing
the memory for the return variables. If your process fails to free the memory, your application is said
to have a “memory leak”, which can cause significant performance degradation over time.

Freeing memory
When your process allocates the memory for the return variable, you can use free( ) to free it. Notice
that the program segment illustrates this technique as well:
/* Allocate memory for return variable */
rtn = (char *)malloc(256);
printf("\nExecuting UniBasic subroutine using udtcallbasic()...\n");
/* Call the UniBasic subroutine using udtcallbasic. */
sts = udtcallbasic(rtn, “EXAMPLE”, 2, args[0], args[1]);
if (sts == 0){
printf("Return value from UniBasic subroutine is %s\n", rtn);
}
/* Free memory */
free(rtn);

Ending CallBasic
The last step in the C program is:
/* Close everything properly */
udtcallbasic_done(sts);
Remember that this function closes the UniData session for the C program, closing all UniData
temporary files and releasing all resources held by UniData for this C program.

Warning: If you do not exit UniData cleanly, you may lose consistency of data, and you may
damage files.

UniBasic subroutine example

The following UniBasic subroutine, called EXAMPLE, is a very simplified routine showing the
requirements for CallBasic.
SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)
PRINT "THE FIRST ARG IS ":ARG1
PRINT "THE SECOND ARG IS ":ARG2
RETNVAL="RETURN"
RETURN
END
Notice the following points about the UniBasic subroutine.

Arguments
The arguments for the UniBasic subroutine match what is sent from the C program. Here is the
U_callbas call to the subroutine:
sts = U_callbas(&rtn, “EXAMPLE”, 2, args);
Here’s the udtcallbasic call to the subroutine:
sts = udtcallbasic(rtn, “EXAMPLE”, 2, args[0], args[1]);
And here’s the first line of the subroutine:

251
Chapter 17: CallC and CallBasic (Windows only)

SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)

Additional information
The UniBasic subroutine must be created, compiled, and cataloged in a UniData account. The routine
may be globally, directly, or locally cataloged. However, if you catalog the routine directly or locally,
you must execute the C program from the UniData account where the subroutine is cataloged.
Regardless how you catalog the UniBasic subroutine, you must execute the C program from a valid
UniData account.

Steps for CallBasic

Complete the following steps to access UniData from an external program with CallBasic.

Warning: We recommend that you keep your development environment clearly separate from
your production environment when developing a CallBasic application. Separating environments
is useful in any case, but can be critical because difficulties in the external programs can terminate
udt sessions and potentially damage data.

1. Code and compile the application program

Refer to the documentation for your application development environment for information about
compiling the external program. Make sure that:
▪ Your declarations for the UniBasic functions use the correct syntax for your programming
language.
▪ You link your code with the UniData.LIB file. The UniData.LIB file is located in the UniData bin
directory.
The following segment from the makefile for callbasic_example1.c shows linking with the UniData.LIB
file:
LINK32=link.exe
# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib
comdlg32.lib a\
dvapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib
odbccp32.lib\
/nologo /subsystem:console /machine:I386
# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib
comdlg32.lib advapi\
32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib
odbccp32.lib c:\u\
nidata\bin\unidata.lib /nologo /subsystem:console /machine:I386
LINK32_FLAGS=kernel32.lib user32.lib gdi32.lib winspool.lib
comdlg32.lib\
advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib\
odbccp32.lib c:\unidata\bin\unidata.lib /nologo /subsystem:console\
/incremental:no /pdb:”$(OUTDIR)/callbasic_example1.pdb” /machine:I386\
/out:”$(OUTDIR)/callbasic_example1.exe”
:

Note: See the Sample programs, on page 247 for a listing of callbasic_example1.c. The
sample program and makefile are also in the CALLBASIC_DEMO folder in your UniData demo
account.

252
 2. Code, compile, and catalog the UniBasic subroutine

2. Code, compile, and catalog the UniBasic subroutine

Remember that you can catalog the UniBasic subroutine globally, locally, or directly. The following
example shows compiling and directly cataloging the sample subroutine EXAMPLE in the UniData
demo account:
:AE BP EXAMPLE
Top of "EXAMPLE" in “BP”, 7 lines, 136 characters.
*--: P

001: SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)^M

002: PRINT "THE FIRST ARG IS ":ARG1^M
003: PRINT "THE SECOND ARG IS ":ARG2^M
004: RETNVAL="RETURN"^M
005: RETURN^M
006: END^M
007: ^M
Bottom.
*--: FIBC

Filed "EXAMPLE" in file "B" unchanged.

Compiling Unibasic: BP\EXAMPLE in mode 'u'.

compilation finished
In D:\UniData\sys\CTLG\a\AE at line 995 EXAMPLE has been cataloged, do
you want\
to overwrite(y/n)? Y
:

Note: Before proceeding further, be sure that both your C program and your UniBasic subroutine
are thoroughly tested.

3. Use the new executable

To run the new executable and call the UniBasic subroutine, your working directory must be a UniData
account where the subroutine is cataloged. You can execute your routine from the operating system
prompt, and you must specify the full path of the executable, or include its location in your PATH
environment variable.
The following window shows the results of executing the callbasic_example1 executable from
the demo directory:

253
Chapter 17: CallC and CallBasic (Windows only)

Note: If your UniBasic subroutine is globally cataloged, you can use CallBasic from any UniData
account. You do not need to be in the UniData account where the subroutine was written.

254
Chapter 18: Monitoring and tuning UniData
(Windows only)
This section outlines considerations that can affect UniData performance on your Windows platform
and describes UniData-specific procedures for monitoring performance.

Monitoring your Windows system

The Performance Monitor provides great flexibility for monitoring the behavior of your Windows
system. From the Start menu, click Control Panel, then double-click Administrative Tools, and then
click Performance.

Note: A description of the Microsoft Performance Monitor is outside the scope of UniData
documentation. Refer to your operating system documentation for information about how to use
the Performance Monitor.

We recommend that you monitor your system performance regularly to develop baseline expectations
throughout your processing cycle. The performance history of your system provides information
that you can use to implement new procedures (such as scheduling certain jobs to run off-hours or
purchasing more resources), as well as to identify problems quickly to minimize downtime.

Tip: You can select an individual udt session and monitor detailed information about its use of
system resources, in addition to monitoring UniData as a whole.

UniData performance factors

Within UniData applications, the major performance factors are: database design, file sizing, and
program coding efficiency.

Database design considerations

▪ Structure your database so records do not exceed a size limit of 4 K bytes.
▪ When possible, avoid long, multivalued, variable-length records.
▪ Locate the most frequently accessed attributes near the beginning of a record.
▪ As far as possible, keep key lengths numeric and small in length.

Using alternate key indexes

Using alternate key indexes speeds query access in a hashed file, but can slow down updates. Consider
this factor when you create indexes. The more indexes that are created for a file, the longer an update
takes.
When the maximum length value is too small for the fields being indexed, index overflows occur.
Index overflows can degrade performance for query as well as update access. The solution for index
overflows is to delete all the indexes for a file and rebuild them with a longer maximum length value.

255
Chapter 18: Monitoring and tuning UniData (Windows only)

Tip: To identify index overflow problems, use the UniData LIST.INDEX tool. Consider running
LIST.INDEX periodically. See Using UniData for information about alternate key indexes.

Sizing static hashed files

Performance loss results if UniData hashed files are allowed to overflow. Level 2 overflow, which
occurs when primary keys outgrow a block, has a particularly serious performance impact. Level 1
overflow, which occurs when data overflows a block, eventually affects performance as well.
For information about file sizing commands, see UniData Commands Reference.

Sizing dynamic hashed files

Dynamic hashed files differ from static hashed files in that they split and merge with respect to a
minimum modulo. Splitting prevents level 2 overflow conditions, because a group splits whenever
the percentage occupied by keys exceeds a preset value. Merging supports efficient access to the file,
because maintaining the file at a low modulo makes searches faster. For information about dynamic
file sizing commands, see the UniData Commands Reference.

UniBasic coding tips

The efficiency of your UniBasic application has a significant impact on UniData performance. Use the
following guidelines when designing and coding.

Use modular programming

▪ Use inserts and include files consistently.
▪ Open frequently used files to COMMON to reduce physical file opens.

Use efficient commands

▪ Use the EQUATE command where possible.
▪ Use CASE statements instead of IF, THEN, ELSE structure whenever possible. Avoid nested IF,
THEN, ELSE.
▪ Use UniData @variables.
▪ Minimize new assignment of variables.
▪ Eliminate GOTO statements.
▪ Use GOSUB instead of external CALLs when appropriate; use CALL when multiple programs access
the same code.
▪ When using CALLs:
▫ Avoid opening files; pass through COMMON or an argument list.
▫ Minimize local variables in subroutines.
▫ Use inserts, COMMON, and argument lists whenever possible.
▪ Use A += B instead of A = A + B.

256
 Use dynamic arrays and matrices appropriately

▪ When extracting data sequentially from a string, use LOOP and REMOVE.
▪ Avoid unnecessary shell commands; minimize PERFORM, EXECUTE, and MDPERFORM statements.
▪ To run another UniBasic program, use CALL or CHAIN.
▪ Avoid repeated ITYPE( ) function calls.
▪ Minimize use of EXECUTE “SELECT.....” by:
▫ Using UniBasic SETINDEX, READFWD, READBCK.
▫ Using the UniBasic SELECT command.

Use dynamic arrays and matrices appropriately

▪ When you are accessing small strings and variables, use dynamic arrays.
▪ If you are handling a large number of attributes and multivalued strings, use matrices.

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.

Manage locks carefully

▪ Use the LOCKED clause with a loop.
▪ Remember to release locks promptly.

UniBasic profiling
UniData allows users to generate execution profiles that track call counts and execution times for
UniBasic programs, internal subroutines, and program calls. You can use these profiles to identify
sections of your UniBasic application that are called most frequently, and then focus optimization
efforts in those areas.
To create UniBasic execution profiles, complete the following steps.

1. Compile the programs with -G

To include information about internal subroutines in the profile reports, compile UniBasic programs
with the -G option.

257
Chapter 18: Monitoring and tuning UniData (Windows only)

2. Run the programs with -G

To profile a UniBasic program, run the program with the -G option. See Developing UniBasic
Applications for information about compiling and running programs.

3. Review the profile output

UniData stores profile output in the NTFS directory where the UniBasic program was run. Output files
are called profile. pid and profile.elapse.pid where pid is the process ID (USRNBR in LISTUSER
output) of the user’s UniData process.
The following example shows a portion of a profile report for a sample UniBasic program:

In this example, the main program is called TIME_TST. It has three internal functions, named A, B, and
C.

Note: profile.pid reports execution times as CPU execution time, while

profile.elapse.pid reports “real” time.

Each profile display includes two sections. The top section presents summary information, and the
bottom section presents detail. The following table describes the fields in the top section of a UniBasic
Profile display. One line exists for each function of the program.

258
 3. Review the profile output

Field Description
%time Percentage of the total run time of the program that is used by the
function
cumsecs Running sum of seconds the function and those listed above it used
within a cycle
seconds Number of seconds used by the function in a cycle
calls Number of times the function was invoked in a cycle
name Name of the function

UniData sorts program functions by execution time, and assigns an index to each function for ease
of reporting. For each index, UniData computes information about functions that call, or are called
by, the function corresponding to the index. The detail section of a profile contains this information,
which is grouped by index. The next table describes the fields in the detail section.

Field Description
index Assigned by UniData. The indexes are assigned in descending order of
execution time for the functions of the program. The index in column
1 identifies the routine of interest for the group of data (the current
index function).
%time Reported for the current index function; percentage of the execution
time that is used by the current index function and its descendants.
self Time that is spent by the function either calling, or being called by, the
function that is identified by the current index.
descendants Time that is spent by the descendants of the function.
called For “parents” of the current index function, the number of times the
function calls the current index function. For descendants of the
current index function, the number of times the function is called by
the current index function.
called+self Reported for the current index function. The number of times the
function is called by others, plus the number of times the function calls
itself recursively.
name Function name.
index Index value that is assigned to the function.

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 function A, which is identified by index
number 2. “Parent” functions, or functions that call A, are listed above it; “descendants”, or functions
that are called by A, are listed beneath it.
In the example, the report indicates that 97.6% of the execution time for the entire program is used by
A. The function is called five times, all by the main program, BP/TIME_TST. In turn, A is responsible for
all 60 of the calls to B, and 15 of the 1,215 calls to C.

259
Chapter 18: Monitoring and tuning UniData (Windows only)

UniData performance monitoring

UniData performance monitoring is integrated with the Microsoft Performance Monitor to provide
an easy interface and significant reporting flexibility to system administrators. Because you can
monitor UniData-specific parameters and Windows system-wide parameters with the same tool,
you can monitor combinations of parameters simultaneously. This capability allows you to explore
relationships between UniData processing and underlying system behavior. The Performance Monitor
allows you to generate reports, logs, or a graphical display.

Note: Examples for this manual use a graphical display. Consult your operating system
documentation for detailed information about all the output options for the Microsoft
Performance Monitor.

The following sample window shows the appearance of the graphical display:

You can run the Microsoft Performance Monitor in either of two ways:
▪ From the Start menu, click Control Panel, then double-click Administrative Tools, and then
double-click Performance Monitor.
▪ From the Start menu, click All Programs, then click Rocket U2, then click U2 Extensible
Administration Tool. When you have connected to the desired host from the U2 Extensible
Administration Tool, double-click Performance Monitor.
You can select output options by clicking “+” on the toolbar icon of the performance monitor. UniData
monitoring categories are included in the list of Objects for each view option. The following example
illustrates the counters that you can add to the performance monitor:

260
 UniData user statistics

Select any of the UniData statistics by clicking its entry in the Pre-defined Category list. The following
sections describe each group of UniData statistics.

Tip: The UniData Objects are listed in alphabetical order in theObject list, and the statistics you
can monitor for each category are listed alphabetically in the Counter list for each object.

UniData user statistics

If you choose UniData, a window similar to the following example appears:

261
Chapter 18: Monitoring and tuning UniData (Windows only)

This option displays the current, average, minimum, and maximum number of UniData users on the
system.

UniData file I/O statistics

When you select UniData File I/O from the Object list, a window similar to the following appears:

262
 UniData file I/O statistics

Tip: You can scroll through the list of Items to see all values.

The following table describes the counters that you can monitor for File I/O, and indicates
considerations for performance.

Field Description
File Open Number of files at the operating system level. On Windows
platforms, if the average value in this field is more than 5 (opens
per second), performance might suffer.
File Close Number of file closes at the operating system level, from
UniBasic CLOSE commands.
TempFile Close When requests for file opens exceed the limit of open files per
process, UniData temporarily closes the least-recently-accessed
open file.
Record Read Number of records that are read by UniData commands (other
than UniQuery).
Record Write Number of records that are written by UniData commands
(other than UniQuery).
Record Delete Number of records that are deleted by UniBasic commands.

263
Chapter 18: Monitoring and tuning UniData (Windows only)

Field Description
Level 1 Overflow Number of level 1 overflows. Compute the total activity by
summing Record Read, Record Write, Record Delete. If Level 1
Overflow is more than 10 % of the total activity, use guide to
analyze your files and resize them appropriately.
Level 2 Overflow Number of level 2 overflows. If Level 2 Overflow is more than
2% of total activity, use guide utility to identify files in level 2
overflow and resize them appropriately.

Tip: You can scroll through the list of Items to see all values.

UniData dynamic file statistics

If you choose Dynamic File, a window similar to the following example appears:

The following table describes information that is displayed by the Dynamic File category.

264
 UniData index statistics

Item Description
Group Split Number of times a group in a dynamic file splits. If your
application shows that unusual activity and your performance
is suffering, consider analyzing and possibly reconfiguring some
of your dynamic files. Increasing SPLIT.LOAD makes a file split
less often.
Group Merge Number of times a split pair of groups merges back together. If
your application shows unusual activity and your performance
is suffering, consider analyzing and possibly reconfiguring some
of your dynamic files. Increasing MERGE.LOAD makes a file
merge more often.

UniData index statistics

When you choose UniData Index Statistics from the Object List, you will see a window similar to the
following example:

Tip: You can scroll through the list of Items to see all values.

265
Chapter 18: Monitoring and tuning UniData (Windows only)

The following table describes the Counters that you can monitor for UniData Index Statistics, and
presents tuning recommendations.

Table 1: Index counters

Field Description
Node Read Number of index node reads. A node is a component of the B+ tree
structure, and a node is analogous to a block in a hashed file.
Node Write Number of index node writes a Node is a component of the B+ tree
structure, and a node is analogous to a block in a hashed file.
Node Merge Number of times two nodes merge; this takes place when entries
in one or both nodes decrease.
Node Split Number of times an index node splits in two; this happens when
entries in the original node increase. An unusual amount of split/
merge/reuse activity indicates that one or more indexes are not
properly sized. To identify these indexes, and then delete and
rebuild them, use the ECL LIST.INDEX command.
Node Reuse Number of times a node that was previously freed by a node
merge is used for a node split.
Log Read Number of reads from an index log file. These reads occur when
an index which was disabled is re-enabled and updated with the
contents of the index log.
Log Write Number of writes to an index log file. These writes occur while an
index is disabled, as UniData tracks changes by recording them in
the index log.
Overflow Read Number of times UniData reads from an index overflow node.
When the number of keys in an index node exceeds a set limit, the
system creates overflow nodes. When the alternate key length
of the index is too small for the selected attribute, the overflow
condition is created. Reads to and writes from overflow nodes
slow system performance.
Overflow Write Number of times UniData writes an overflow node. If overflow
activity (reads and writes) exceeds 5% of system activity (Index
Node Reads and Index Node Writes), use ECL LIST.INDEX
command to identify which indexes are overflowed, and delete
and rebuild them using a larger key length. (The default key length
is 20 characters).

UniData program control statistics

If you choose UniData Program Control from the list of Objects, you will see a window similar to the
following example:

266
 UniData program control statistics

Tip: You can scroll through the list of Counters to see all values.

The following table describes the Items that you can monitor for UniData program control, and
indicates performance considerations.

Field Description
Local Call Displays the current, average, minimum, maximum, and total
number of UniBasic program control statement executions.
Global Call Number of calls to globally cataloged UniBasic programs. In
production environment, this number should be much higher than
Local Call. If a program is globally cataloged, then users share a
single copy of the object code in memory, which reduces both
memory requirements and physical I/O load.
CallC Call Number of calls to an external C function, From UniBasic CALLC
statements.
CHAIN Call Number of UniBasic CHAIN statement run.
GOSUB Call Number of UniBasic GOSUB commands run.
LOOP and GOTO Number of UniBasic LOOP and GOTO commands run.
EXECUTE Call Number of external UniData command executions (From UniBasic
EXECUTE commands).

267
Chapter 18: Monitoring and tuning UniData (Windows only)

Field Description
PCPERFORM Call Number of PCPERFORM statements, which run shell or host
operating system tasks. PCPERFORM statements are expensive
on Windows platforms because creating a process is slow. If
PCPERFORM Call is consistently more than 1 per second, analyze
your application and consider replacing PCPERFORM logic with C
routines.
SLEEP Call Number of UniBasic SLEEP command executions. A sudden
increase in this number might indicate that a number of users are
attempting to get a lock on a record.

UniData dynamic array statistics

If you choose UniData Dynamic Array, a window similar to the following example appears:

Tip: You can scroll through the list of items to see all values.

The Items are counts for executions of UniBasic commands that are described in the following table.

268
 UniData lock statistics

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.
MATCHFIELD Number of dynamic array substring matches, from MATCHFIELD
command.
MATPARSE Number of dynamic array matrix parses, from MATPARSE command.
REMOVE Number of dynamic array element removals, from REMOVE command.
REPLACE Number of dynamic array replacements, from REPLACE command.

UniData lock statistics

When you choose UniData Lock Statistics from the Object list, you will see a window similar the
following example:

269
Chapter 18: Monitoring and tuning UniData (Windows only)

Tip: You can scroll through the list of Items to see all values.

The following table describes the Counters that you can monitor for UniData Lock Statistics, and
indicates performance considerations.

Field Display
Record Lock Number of user-level record locks set by commands such as
READL and READU.
Record Unlock Number of user-level locks that are released by commands such
as RELEASE.
Semaphore Lock Number of user-level resource locks set by commands such as
LOCK and T.ATT.
Semaphore Unlock Number of user-level resource locks released by commands such
as T.DET or ULOCK.
Shared Group Lock Number of user-level resource locks released by commands such
as T.DET or ULOCK.

270
 UniData sequential I/O statistics

Field Display
Excl. Group Lock UniData-level exclusive lock on an entire group. For most
applications, the number of shared group locks exceeds the
number of exclusive group locks. If the number of exclusive
group locks is larger than the number of shared group locks, one
or more files might be overflowed. Identify these files with guide
utility.
Shared Index Lock UniData-level read-only lock on an index.
Excl. Index Lock UniData-level exclusive lock on an index. For most applications,
the number of shared index locks exceeds the number of
exclusive index locks. If the number of exclusive index locks
is larger than the number of shared index locks, one or more
index files might be overflowed. Identify these indexes with
LIST.INDEX ECL command.
End-of-File Lock UniData file level physical lock.
Lock Failure Number of times a process attempts to get a user-level lock
and fails because the record is already locked. If performance is
suffering, analyze your application for lock handling.

Note: In some circumstances, the output display might indicate that more records are being
unlocked than are being locked. This behavior is a function of how UniData gathers the statistics
and does not indicate a problem.

UniData sequential I/O statistics

If you choose UniData Sequential I/O option, a window similar to the following example appears:

271
Chapter 18: Monitoring and tuning UniData (Windows only)

The Sequential I/O counter displays the current, average, minimum, maximum, and total number of
UniBasic sequential file operations.
The following table describes the items the Sequential I/O counter displays.

Item Description
OPENSEQ Number of sequential file opens by using the UniBasic OPENSEQ
command.
CLOSESEQ Number of sequential file closes by using the UniBasic CLOSESEQ
command.
READSEQ Number of sequential file reads by using the UniBasic READSEQ
command.
WRITESEQ Number of sequential file writes by using the UniBasic WRITESEQ
command.
OSOPEN Number of sequential file opens by using the UniBasic OSOPEN
command.
OSCLOSE Number of sequential file closes by using the UniBasic OSCLOSE
command.
OSREAD Number of sequential file reads by using the UniBasic OSREAD
command.
OSWRITE Number of sequential file writes by using the OSWRITE command.

272
 UniData data conversion statistics

Item Description
COMO Write Number of COMO file writes.

UniData data conversion statistics

If you choose UniData Data Conversion option, a window similar to the following example appears:

The Data Conversion option displays the current, average, minimum, maximum, and total number of
UniBasic data conversion function calls.
The following table describes the items the Data Conversion Counters display.

Item Description
ASCII The UniBasic ASCII function converts a string in EBCDIC format to the
corresponding ASCII value.
CHAR The UniBasic CHAR function changes a numeric expression to its ASCII
character string equivalent.
EBCDIC The UniBasic EBCDIC function converts the ASCII data to its
corresponding EBCDIC value.

273
Chapter 18: Monitoring and tuning UniData (Windows only)

Item Description
FMT The UniBasic FMT function formats data through a specific format
mask for display purposes.
ICONV The UniBasic ICONV function converts string or numeric data to an
internal representation format based on conversion codes.
OCONV The UniBasic OCONV function converts string or numeric data from
internal format to output format based on conversion codes.
SEQ The UniBasic SEQ function converts the character expression to a
single ASCII code value.

ECL process monitoring commands

On Windows platforms, UniData includes three ECL commands that you can invoke to collect and
display statistics for their current UniData processes. The commands are:
▪ ENABLE.USERSTATS—This command turns on statistics collection for the user’s current process.
Running this command starts statistics collection for that process, which continues until the user
exits UniData or runs the DISABLE.USERSTATS command.
▪ DISABLE.USERSTATS—This command turns off statistics collection for the user’s current
process. Users can turn statistics collection back on by running ENABLE.USERSTATS, but all
totals are zeroed out each time a user turns off statistics collection.
▪ LIST.USERSTATS—If the user turned on statistics collection with ENABLE.USERSTATS,
LIST.USERSTATS displays a snapshot of the statistics for the user’s process that were collected
since that time. If the user did not turn on statistics collection, or turned it off before running
LIST.USERSTATS, this command displays a list of statistics collected for the entire system since
the last time the Windows system was shut down and restarted.

Warning: If you are using the Performance Monitor to monitor overall UniData behavior, and one
or more users run ENABLE.USERSTATS, those processes will not be counted in Performance
Monitor output. Statistics for a udt process are recorded in only one place at one time, and the ECL
Statistics commands override the performance monitor.

The statistics reported by LIST.USERSTATS are virtually identical to those monitored with the
Performance Monitor, although they are organized differently. The following example shows the
output of LIST.USERSTATS for a single udt process:
:LIST.USERSTATS
File I/O Statistics
Physical File Opens........ 8
Logical File Opens......... 0
File Closes................ 9
Temp File Closes........... 0
Dynamic File Split......... 255
Dynamic File Merge......... 0
Record Reads............... 101
Record Writes.............. 20060
Record Deletes............. 1
Level 1 Overflow........... 25363
Level 2 Overflow........... 0
Program Control Statistics
Private Code Calls......... 1
Shared Code Calls.......... 0
Shared Code Failures....... 0
CALLC Calls................ 0
Chain Calls................ 0

274
 Examples

Gosub Calls................ 20000

Goto Calls................. 0
Execute Calls.............. 3
Pcperform Calls............ 0
Dynamic Array Statistics
DELETE..................... 0
FIND....................... 0
INSERT..................... 0
LOCATE..................... 0
MATPARSE................... 0
MATCHFIELD................. 0
COUNT...................... 0
EXTRACT.................... 20000
FIELD...................... 0
REMOVE..................... 0
REPLACE.................... 0
INDEX...................... 0
Lock Statistics
Record Locks............... 255
Record Unlocks............. 255
Semaphore Locks............ 0
Semaphore Unlocks.......... 0
Shared Group Locks......... 178
Exclusive Group Locks...... 21626
Shared Index Locks......... 0
Exclusive Index Locks...... 0
Lock Failures.............. 0
Index Statistics
Index Reads................ 0
A few differences in counter names exist between the Performance Monitor and LIST.USERSTATS.
These differences are described in the following table.

Table 2: Counter names

Performance Monitor LIST.USERSTATS

Global Call Shared Code Calls
Local Call Private Code Calls
(Not reported) Shared Code Failures (Number of times a process that is called
a globally cataloged program and the system found insufficient
memory to load the program.) This number should be zero.

Examples
This section contains examples that illustrate ways of using the Windows and UniData Performance
Monitoring tools.
The following window shows how you can combine monitoring a system parameter (for instance, CPU
time) and a type of UniData activity (for instance, level 1 and level 2 overflow writes):

275
Chapter 18: Monitoring and tuning UniData (Windows only)

Notice that overflow writes are associated with an increase in CPU utilization.
The next window shows monitoring CPU use for a udt process and for the Windows system as a whole:

Notice that the udt process corresponds to some, but not all, of the periods of high CPU utilization.
Monitoring one process against the whole system can help differentiate UniData impacts from impacts
of other processes.

276
Chapter 19: Accessing UNIX devices (UNIX only)
This chapter describes UniData commands for identifying and accessing UNIX tape devices. This
chapter also describes commands for reading and writing to other UNIX devices, which you can use for
transferring data and also for debugging UniBasic applications.

UniData tape handling commands

UniData includes a number of ECL and UniBasic commands for reading data from a tape and writing
data to a tape. The following table summarizes these ECL commands.

Command Description
SETTAPE Defines a logical tape unit in UniData; requires root access; must
precede all other tape commands.
T.ATT Links a logical tape unit to a UniData process; must precede any reads/
writes involving the tape.
T.BAK Moves a tape backward 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.

277
Chapter 19: Accessing UNIX devices (UNIX only)

SETTAPE
The ECL SETTAPE command enables you to define logical tape units in your UniData environment.
This command establishes a link between a UniData internal tape unit number and a UNIX file. You
can use SETTAPE to relate unit numbers to tape devices or UNIX disk files.
Any user can run SETTAPE unit.no to display the current settings for a tape unit. However, you
must 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 your
system. The tape unit definition remains the same unless it is changed by root.

Syntax
SETTAPE unit.no [dn.path.nr][dn.path.r][blocksize]
The following table describes the parameters of the SETTAPE syntax.

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 use

Follow 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 UniData
environment.
The tape unit number must be within the range 0-9. These numbers are logical tape unit numbers
within 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 handling
commands require unit 0 to be defined so that it can be used as a default.

When you define a tape device or modify a definition, you create or update an entry in the ASCII text
file 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 command
attaches a tape device. Any user can run T.ATT from the ECL prompt or from within a UniBasic
program. The following example shows typical output from T.ATT:
:T.ATT 7
No information for unit 7 yet, ask your system administrator for help.

278
 3. Read from or write to the tape device

T.ATT failed.
:T.ATT 1
tape unit 1 blocksize = 4096.
:T.ATT 1 BLKSIZE 16384 TAPELEN 2
tape unit 1 blocksize = 16384 length = 2MB
:T.ATT 1
unit 1 is attached by another process
It 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 specify
BLKSIZE, 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 a
single process, but you cannot attach the same tape unit to more than one process.
▪ You can use the ECL T.STATUS command to list all defined tape units to find out which ones
are attached and which ones are available. The following example shows sample output from
T.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 following
example shows typical output when a process with tape unit 4 attached runs the ECL T.DUMP
command:

279
Chapter 19: Accessing UNIX devices (UNIX only)

Notice the following points about the example:

▪ You cannot write to a tape device unless it is attached with T.ATT. If you have attached more than
one device, you need to specify the device to write to or read from. If you have attached only one
device, UniData accesses the device 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 connected
or if no tape is mounted. The UniData T.ATT and SETTAPE commands do not detect device
configuration problems, so you may be able to define and attach a device, but be unable to
complete your access to it.

Tip: Because of the differences in Pick® operating systems and manufactured tapes, we
suggest you use the HDR.SUPP keyword when you are using the T.DUMP command, and when
you 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 another
process can use it. If you have attached more than one device, you need to release each one
separately. If you have attached only one, the T.DET command releases it. You can run T.DET from
ECL or from within a UniBasic program.

UniData LINE commands

UniData includes a group of commands that enable you to read from and write to UNIX tty-type
devices. These commands are used to define and attach line devices for use by the UniBasic GET and
SEND commands. GET and SEND allow UniBasic programs to read data from or write data to serial
devices such as scales or bar code readers.

280
 Communicating with GET and SEND

Note: You can use GET and SEND and the LINE commands to communicate with a printer or
terminal.

The following table describes the UniData commands.

Command Description
SETLINE Defines a UNIX tty device within UniData; requires root access; must
precede 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 an
attached line.
LINE.DET Releases a device.
LINE.STATUS Displays current line device assignments.
UNSETLINE Removes a UNIX device definition set with SETLINE. Requires root
access.

Note: See the UniData Commands Reference for detailed information about the UniData LINE
commands.

Communicating with GET and SEND

You must follow these steps to use to use the UniBasic GET and SEND commands:

1. Define a tty device in UniData

Use the SETLINE command to create a pointer in UniData to any valid UNIX tty device. Use
LINE.STATUS to verify pointers and determine which lines may be attached to processes. You must
log on as root to create or modify a pointer. The following example shows an example of SETLINE
and LINE.STATUS:

Note: To access a tty device from UniBasic, the device must be assigned a tty number.

281
Chapter 19: Accessing UNIX devices (UNIX only)

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 UniBasic
program, to reserve a line for your process. Again, you can use LINE.STATUS to verify the line, as
shown below:

Note: Once you attach the line, you can run the ECL PROTOCOL command to define its
transmission characteristics. When you modify these characteristics, be aware that the values you
specify remain in effect until modified again by another PROTOCOL command. You may wish to
run PROTOCOL after every LINE.ATT, to ensure that the transmission characteristics are correct
for your application.

3. Access the line

In your UniBasic application, use the GET command to retrieve data from your tty device and the
SEND command to direct data to the device.
See the UniBasic Commands Reference for detailed information about GET and SEND.

4. Release the line

Use the ECL LINE.DET command from the ECL prompt or within your UniBasic application to release
the tty device.

Dual-terminal debugging in UniBasic

If you are debugging a UniBasic application that performs terminal I/O, it is often more efficient
to display debugger messages on a separate screen from the application. The following table
summarizes ECL commands for dual-terminal debugging.

282
 Setting up dual-terminal debugging

Command Description
SETDEBUGLINE Sets a pointer to the terminal or window where you want debugger
messages to display.
DEBUGLINE.ATT Connects to the terminal or window you specify with
SETDEBUGLINE.
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 for
dual-terminal debugging, and see Using the UniBasic Debugger for information about the UniBasic
debugger.

Setting up dual-terminal debugging

Complete 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 is
running to the terminal where you want messages to display. The following screen shows an example:
:SETDEBUGLINE /dev/pty/ttyv4
:
Notice that you must specify the full path for the device special file for your display terminal.

3. Connect to the display terminal

Use the DEBUGLINE.ATT command to connect to the terminal you defined.

4. Conduct the debugging session

The following two screens show dual-terminal debugging. On the first screen, a UniBasic program is
run with the -D option:
:DEBUGLINE.ATT
:RUN BP EXAMPLE -D
On the second screen, the messages from the UniBasic debugger appear:

283
Chapter 19: Accessing UNIX devices (UNIX only)

:MYSELF
ump01 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 the
pointer to the display terminal.

284
Chapter 20: Managing memory (UNIX only)
This chapter describes UniData commands and utilities for configuring, monitoring, and
troubleshooting shared memory. The chapter also lists UniData error messages that are related to
shared memory, and presents suggestions for resolving the errors.
The following commands and utilities enable you to monitor the use of shared memory on your
system and provide suggestions for configuration and tuning.

UniData monitoring/configuring tools

The udtconf utility enables you to automatically set all udtconfig parameters, including those
parameters for shared memory. Although shared memory requirements are highly application and
platform dependent, udtconf can provide suggestions for udtconfig parameters and provide
information about the actual state of your system.

Syntax
udtconf
You do not have to log on as root to run udtconf, but the utility reads information from the
udtconfig file, which is located in /usr/ud82/include, and from the UNIX kernel. If you do not
log 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 exception
is to assess the impact of the Recoverable File System (RFS) system buffer. In this case, run udtconf
from a UNIX prompt while UniData is running.

udtconf main display

The following example shows the main screen of the udtconf utility:

285
Chapter 20: Managing memory (UNIX only)

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, the
udtconf utility displays warning messages. Make sure that the kernel parameter for semaphore undo
structures, usually semmnu, is adequate to support the number of authorized users before running
udtconf.
Settings for the udtconfig parameters NUSERS, SHM_GNTBLS, N_GLM_GLOBAL_BUCKET,
GLM_MEM_SEGSZ, N_TMQ, and N_PGQ are based on the number of authorized users. Although
udtconf displays warning messages if kernel parameters are not adequate to support these settings,
the udtconfig file is updated with these values. In this case, UniData may not start.

Calculating udtconfig parameters

If you change a value in the udtconf screen, udtconf can automatically calculate values for
udtconfig parameters 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 a
UniData configuration parameter cannot be supported by a kernel parameter setting, UniData
displays a warning message at the bottom of the screen for each conflicting parameter, as shown in
the following example:

When all configuration parameters have been checked, UniData displays the message Shared
memory related configuration values are OK!

286
 Saving configuration parameters

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 udtconfig
file.

Recalculating the size of the CTL

Press Ctrl+L from any udtconf screen to recalculate the size of your global control table, CTL. This
table changes size if you change shared memory parameters such as SHM_GNTBLS, SHM_GNPAGESZ,
and so forth. If the table size is greater than the kernel parameter shmmax (and the udtconfig
parameter SHM_MAX_SIZE), UniData will not start.

Viewing current and suggested settings

To view current and suggested UNIX kernel settings, press Ctrl+P. The following example shows
sample output:

udtconf suggests values assuming that UniData is the only software product on your system. If that
is true, if the current kernel settings for semaphore undo structures, shared memory segments, and
so forth, are at least equal to the suggested values, it should not be necessary to rebuild your kernel.
If you have more applications that are running, you need to consider the combined effect of UniData
and 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 save
the changes by using Ctrl+V before you exit the program.

287
Chapter 20: Managing memory (UNIX only)

Setting shared memory parameters

The shmconf utility enables you to set udtconfig parameters for shared memory automatically.
Unlike udtconf, you cannot set udtconfig parameters that do not apply to shared memory
through shmconf. Although its usability for this purpose is platform-dependent and application-
dependent, the utility provides configuration suggestions and information about the actual state of
your system.

Syntax
shmconf
You do not need to log on as root to run shmconf, but the utility reads information from udtconfig
parameters and from the UNIX kernel. If you do not log on as root, you may not have sufficient access
to the kernel, and the results are unreliable.
In general, you should run shmconf with UniData users logged off and UniData shut down. The one
exception is to assess the impact of the RFS system buffer. In this case, run shmconf from the UNIX
prompt while UniData is running.

Note: Only one user at a time may run shmconf.

shmconf: main display

The following screen shows a sample of the first output screen from shmconf:

Note: Most of the figures that are displayed are current values that are read from UniData
configuration parameters. The value of SHMMAX, however, is empirically determined by the
shmconf program, which tests to determine the largest shared memory segment available on the
system.

288
 shmconf: viewing current and suggested settings

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 have
insufficient swap space.

shmconf: viewing current and suggested settings

To view current and suggested UNIX kernel settings, press Ctrl+P. The following screen shows sample
output:

Note: shmconf suggests values assuming that UniData is the only software product on your
system. If that is true, if the current kernel settings for semaphore undo structures, shared memory
segments, and so forth, are at least equal to the suggested values, it should not be necessary
to rebuild your kernel. If you have more applications that are running, you need to consider the
combined 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 the
UniData configuration parameter SHM_MAX_SIZE), UniData will not start.

shmconf: Recalculating other parameters

shmconf also enables you to recalculate parameters that are related to shared memory. Press Ctrl+A
from any screen to do so.

289
Chapter 20: Managing memory (UNIX only)

Note: shmconf recalculates parameters, but does not update the udtconfig file unless you
specify Ctrl+V (saVe).

Shared memory and the Recoverable File System

If you are using the Recoverable File System (RFS), UniData reserves the amount of shared memory
that is required for the system buffer. UniData reserves this memory during startup, and it is not
available to the smm or sbcs daemons. If your system was running close to its limits in terms of
memory resources without RFS, allocating the system buffer can have a significant impact. For
instance, you may see an increase in error messages that indicate smm could not create or attach a
shared memory segment.

Analyzing UniData configuration parameters

The system-level systest command checks all parameters in the udtconfig file, which is located
in /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 platform
dependent. Do not use this parameter unless advised by Technical
Support.
[-sn] Changes memory map display by about n MB. Highly platform
dependent. Do not use this parameter unless advised by Technical
Support.
[-u] Creates or updates the UniData the configuration parameters
NFILES and/or SHM_ATT_ADD. Use with extreme caution.
[-f filename] Creates a file name that you specify containing the UniData
configuration parameters systest recommends for the number of
authorized 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 against
recommendations for the Recoverable File System. If you will not be
using recoverable files, specify the -cn option.

Note: The -m and -s options of systest function differently on different platforms and also function
differently depending on machine activity. These options help you assess the effects of redefining
memory addresses on your system. However, different UNIX versions handle memory allocation so
differently that these options may not produce meaningful output. Do not use them unless advised
by Technical Support.

You must log on as root to run systest. Users do not need to log out of UniData.

290
 Checking and changing UniData configuration parameters

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 current
settings in your UNIX kernel.

Checking and changing UniData configuration parameters

Complete the following steps to update UniData configuration parameters with new values systest
suggests. You want to do this if, for instance, you upgraded your license for more users or you added
physical memory to your system.
1. Use the -f filename option of systest to create an output file in the format of the UniData
configuration file (/usr/ud82/include/udtconfig).
2. Run the UNIX diff command using the file that was created in step 1 and the udtconfig file to
determine the changes suggested by systest.
3. Save a copy of your udtconfig file, then manually update the production udtconfig file to
reflect those changes you want to make. Check your work carefully.
4. Make sure users are logged out of UniData.
5. Stop UniData with stopud, and start UniData with startud, to make the changes effective.
The following screen shows typical output from steps 1 and 2:
# systest -f udtconfig.new
# diff /usr/ud82/include/udtconfig udtconfig.new
13c13
< NUSERS=40
---
> NUSERS=125
34c34
< SHM_GNTBLS=40

291
Chapter 20: Managing memory (UNIX only)

---
> SHM_GNTBLS=125
36c36
< SHM_GPAGESZ=1024
---
> SHM_GPAGESZ=256
96c96
< SB_FLAG=1
---
> SB_FLAG=0
120,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 to
change 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 not
running RFS, use the -n option. Use the -r option are running RFS, as shown below:

Note: The recommended values that are returned by systest are generic UNIX suggestions and
may not be appropriate for your operating system. Kernel configuration varies among UNIX
versions. Refer to your host operating system documentation for detailed information about your
UNIX kernel.

sms
The sms command displays information about use of global and local pages by smm.

Syntax
sms [-h | -g[n] | -G[n] | -L[n] | -l | -Sn | -d]

292
 sms

You do not need to log on as root to run sms. See the UniData Commands Reference for detailed
information about the parameters of the sms command syntax.
sms -h displays the current settings of shared memory-related configuration parameters, as shown
in the following example:
# sms -h
Shmid 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 = 25
SHM_NFREES = 1
SHM_FIL_CNT = 2048
JRNL_BUFSZ = 53248
The following example shows a sample output from the sms command with no options:

The following table interprets the example.

Field Description
GCTs (50) The number of shared memory segments the system is configured to
support. Read from the configuration parameter SHM_GNTBLS.
LCTs (50) The combined number of udt processes the system is configured to
support at one time. Read from the configuration parameter NUSERS.

293
Chapter 20: Managing memory (UNIX only)

Field Description
11502 The shared memory segment ID for a segment that was created. This
number also appears in the ipcstat display. Note: The “GCT number”
is read from left to right, top to bottom. In the example, only GCT
number 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 these
utilities 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 a
particular GCT. This option enables you to determine which udt process is using each global page in
the segment. The following screen shows an example:

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 number
of pages in the segment (32) from the udtconfig parameter
SHM_GNPAGES.
24230,24230 The UNIX process ID of the udt process that is using each global
page.
-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 smm
daemon.

Syntax
gstt
The following example shows the output from the gstt command:

294
 Learning about local control tables

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

Learning about local control tables

The lstt command displays information about local control tables in shared memory. Each local
control table tracks resource use for a udt (or sql) process.

Syntax
lstt [-l n | -L pid]
The following example shows the output from lstt with no options:

295
Chapter 20: Managing memory (UNIX only)

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

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

For more information about the parameters of the lstt syntax, see the UniData Commands
Reference.

UNIX monitoring tools

The UNIX sar, vmstat, swap, and swapinfo commands provide useful information for memory
and swap space management. The availability and syntax of these commands is platform-dependent.
Refer to your host operating system documentation for information about these commands.

UniData configuration parameters

When you design your configuration for smm, account for sbcs, the system buffer (if you are using
RFS), and other applications on your system.
UniData and memory, on page 55 lists the UniData configuration parameters that control how smm
creates and assigns memory structures. These parameters are also listed in UniData configuration
parameters, on page 381.

296
 UNIX kernel parameters

UNIX kernel parameters

UniData and memory, on page 55 describes UNIX kernel parameters that control creation and
allocation of shared memory structures. An exhaustive list of such parameters is beyond the scope of
this manual, since the parameters, their names, and the processes for adjusting them vary for different
UNIX versions. Refer to your host operating system and vendor documentation for information specific
to your system.

Note: Depending on the UNIX version, some kernel parameters can be defined either as fixed
values or by internal calculations that are performed by the system. In some versions, you can tune
the kernel while the system is running, while others require you to reboot to make the changes
effective. Some UNIX versions (AIX, for example) handle kernel configuration dynamically and do
not offer the capability to change the parameters directly.

UniData error messages for smm

This section lists error messages that are received when smm is unable to respond to a request for
memory resources. These messages are seen by the requesting process, so no central location exists
for 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.MSG
file. The message text is often necessary for distinguishing among possible problems.
▪ Consider the context in which the message appears.
▫ If you are configuring UniData for the first time, the error messages provide information 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 or
rebuilding the UNIX kernel. Programming errors or coding structure errors may masquerade as
shared memory errors; these errors should be corrected by correcting the software rather than
reconfiguring your system.
▫ If your system has been running smoothly with no recent changes, and you begin to see error
messages, identify and resolve external causes (such as swap space occupied by temporary
files) before reconfiguring UniData or rebuilding the UNIX kernel.
▪ Consider the resource needs of other applications that are running on your system. Your system
resources must support UniData and all other applications.
The following table lists error messages, describes their meaning, and offers suggestions for resolving
them.

Error message Description

Error on attaching CTL (errno=xxx) A process cannot attach CTL (Control Table List). This error is a
fatal error. You may need to stop UniData and attempt to restart
it. Be sure to save all logs and error logs.

297
Chapter 20: Managing memory (UNIX only)

Error message Description

Error on attaching shm (xxx, xxx, A process cannot attach a shared memory segment. The process
xxx), errno=xxx asked for a segment larger than the system maximum or
exceeded the per-process limit for shared memory segments.
Increase UNIX kernel parameters (shmmax, shmmni, and
shmseg) and/or increase the UniData configuration parameter
SHM_GNTBLS.
Error on creating CTL (errno=xxx) UniData cannot create the CTL. This error happens when
the size of CTL is larger than the maximum size of a shared
memory segment. You can increase the maximum size of a
shared memory segment (shmmax in the UNIX kernel and
the configuration parameter SHM_MAX_SIZE), or decrease
the size of CTL by decreasing the configuration parameters
SHM_GNTBLS and NUSERS.
Error on creating a shared A shared memory segment of the requested size cannot be
memory segment (size=xxx), created. Typically the requested size is larger than the maximum
errno=xxx size on the system. Adjust the UNIX kernel shmmax and the
UniData configuration parameter SHM_MAX_SIZE to increase
the maximum size of a shared memory segment.
Error on forming shared memory Some shared memory segments are created by using
key (errno=xxx) information in files in the directory /usr/ud82/include.
Check to be sure /usr/ud82/include exists; check
permissions; restore the path from backup if it was removed.
No more GCTs You are out of GCTs (Global Control Tables), which means you
already have as many segments (self-created segments and
smm segments) as your system currently supports. Consider
increasing shmmni in the UNIX kernel, or increasing the UniData
configuration parameter SHM_GNTBLS.
No more LCTs You are out of LCTs (Local Control Tables). Consider increasing
the UniData configuration parameter NUSERS. Make sure the
kernel parameter semmnu is larger than NUSERS.
No more core You are out of main memory. Check your swap space; check
recent software changes for inappropriate memory handling;
increase swap space or add more physical memory to your
system.
No more entries in CI table in The CI table in the specified LCT is full. A process used its
LCT-xxx limit of local sections. A local section is a local page or several
contiguous local pages. Consider increasing the UniData
configuration parameter SHM_LCINENTS.
No more entries in MI table in The MI table in the specified LCT is full. A process used its limit
LCT-xxx of 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 in The PI table in the specified LCT is full. Your application has
LCT-xxx too many forked processes. Your application may not be
structured in the correct manner. Consider increasing the
UniData configuration parameter SHM_LPINENTS.
No more shared memory ids You are out of shared memory ids. Adjust the UNIX kernel
parameter shmmni to increase the limit.
smm can’t get the first GSM errno = smm cannot acquire the first shared memory segment to build
22 the necessary control tables because shmmax is not large
enough. Increase the kernel parameter shmmax.

298
 UniData error messages for smm

Error message Description

Error on malloc a space (size=xxx), Memory allocation error. The requested size is too large. Install
errno=xxx more physical memory or increase swap space.

299
Chapter 21: Managing ipc facilities (UNIX only)
This chapter describes commands and procedures that monitor the use of message queues and
semaphores, and describes how to clear message queues and remove queues when necessary to
correct problems.
This chapter includes instructions for monitoring shared memory use; however, shared memory is
described more fully in Managing memory (UNIX only), on page 285.

Message queues, shared memory, and semaphores

The UniData system-level ipcstat command displays a list of message queues, shared memory
segments, and UNIX system semaphores currently in use on your system. Output from ipcstat
resembles that from the UNIX ipcs command, but the ipcstat display also identifies the facilities
in use by UniData.

Syntax
ipcstat [-s | -m | -q]
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 shared
memory segments.

Note: The output from ipcstat provides queue numbers, semaphore numbers, and segment
numbers. You need this information to research ipc problems. For example, you need the queue
numbers 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 these
message 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:
IPC status from /dev/kmem as of Mon Feb 20 03:32:58 2017
T ID KEY MODE OWNER GROUP
Message Queues:
q 0 0x3c18080d -Rrw--w--w- root root -> unknown
q 1 0x3e18080d --rw-r--r-- root root -> unknown
q 6291487 0x00000000 --rw-rw-rw- root root -> smm R8.2
(reply)
q 7340070 0x00000000 --rw-rw-rw- root root -> sbcs R8.2
(fromsbcs)
q 7340102 0x00000000 -Rrw-rw-rw- root root -> sbcs R8.2
(tosbcs)
q 7340123 0x00000000 --rw-rw-rw- root root -> sbcs R8.2
(newversion)

300
 Message queues, shared memory, and semaphores

q 6291558 0x00000000 -Rrw-rw-rw- root root -> smm R8.2

(request)
q 7340166 0xdce08211 -Rrw------- root root -> udaudd R8.2
(queue)
Shared Memory:
m 0 0x411801a9 --rw-rw-rw- root root -> unknown
m 1 0x4e0c0002 --rw-rw-rw- root root -> unknown
m 2 0x411c458e --rw-rw-rw- root root -> unknown
m 3 0x00a5c581 --rw------- sfmdb sfmdb -> unknown
m 4 0x06347849 --rw-rw-rw- root root -> unknown
m 5 0x0c6629c9 --rw-r----- root root -> unknown
m 6 0x4920bb9c --rw-r--r-- root root -> unknown
m 589831 0x45186c93 --rw-rw-rw- root root -> smm R8.2
(ctl)
m 3342344 0x00000000 --rw-rw-rw- root root -> smm R8.2
(glm)
m 9 0x011c2596 --rw-rw-r-- root root -> unknown
m 163850 0xa90c0046 ----------- root root -> unknown
m 1376267 0x00000000 --rw-rw-rw- root root -> smm R8.2
(shmbuf)
m 884748 0xdce08201 --rw-rw-rw- root root -> udaudd R8.2
(mctrl)
m 589837 0x00000000 --rw-r--r-- root root -> sbcs R8.2
Semaphores:
s 0 0x4f18062e --ra------- root root -> unknown
s 1 0x411801a9 --ra-ra-ra- root root -> unknown
s 2 0x4e0c0002 --ra-ra-ra- root root -> unknown
s 3 0x411c458e --ra-ra-ra- root root -> unknown
s 4 0x01090522 --ra-r--r-- root root -> unknown
s 5 0x00a5c581 --ra------- sfmdb sfmdb -> unknown
s 6 0x00a5c582 --ra------- sfmdb sfmdb -> unknown
s 7 0x00a5c583 --ra------- sfmdb sfmdb -> unknown
s 8 0x00a5c584 --ra------- sfmdb sfmdb -> unknown
s 9 0x00a5c585 --ra------- sfmdb sfmdb -> unknown
s 10 0x00a5c586 --ra------- sfmdb sfmdb -> unknown
s 11 0x00a5c587 --ra------- sfmdb sfmdb -> unknown
s 12 0x311c02cc --ra-ra-ra- root root -> unknown
s 13 0x011c247f --ra-ra-r-- root root -> unknown
s 14 0x011c02b9 --ra-ra-r-- root root -> unknown
s 15 0x4920bb9c --ra-r--r-- root root -> unknown
s 8208 0x410c029d --ra-ra-ra- root root -> unknown
s 229393 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213010 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213011 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213012 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213013 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213014 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213015 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213016 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213017 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213018 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213019 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)

301
Chapter 21: Managing ipc facilities (UNIX only)

s 213020 0x00000000 --ra-ra-ra- root root -> smm R8.2

(latch)
s 213021 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213022 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213023 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213024 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213025 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213026 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213027 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213028 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213029 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213030 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213031 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213032 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213033 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213034 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213035 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213036 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213037 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213038 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213039 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213040 0x00000000 --ra-ra-ra- root root -> smm R8.2
(latch)
s 213041 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213042 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213043 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213044 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213045 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213046 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213047 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213048 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213049 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213050 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213051 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)

302
 Message queues, shared memory, and semaphores

s 213052 0x00000000 --ra-ra-ra- root root -> smm R8.2

(live detection semaphore)
s 213053 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213054 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213055 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213056 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213057 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213058 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213059 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213060 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213061 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213062 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213063 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213064 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213065 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213066 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213067 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213068 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213069 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213070 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213071 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213072 0x00000000 --ra-ra-ra- root root -> smm R8.2
(live detection semaphore)
s 213073 0x00000000 --ra-ra-ra- root root -> smm R8.2
(ctl)
s 213074 0x00000000 --ra-ra-ra- root root -> smm R8.2
(super-rls)
s 73811 0xdce082b1 --ra-ra-ra- root root -> udaudd R8.2
(audit)
s 16468 0xdce082b2 --ra-ra-ra- root root -> udaudd R8.2
(audit)
s 16469 0xdce082b3 --ra-ra-ra- root root -> udaudd R8.2
(audit)
s 16470 0xdce082b4 --ra-ra-ra- root root -> udaudd R8.2
(audit)
s 16471 0xdce082b5 --ra-ra-ra- root root -> udaudd R8.2
(audit)
s 16472 0xdce082b6 --ra-ra-ra- root root -> udaudd R8.2
(audit)

Note: Resources that are identified as “unknown” do not indicate a problem. These resources are
in use by the operating system or by other applications rather than by UniData daemons.

303
Chapter 21: Managing ipc facilities (UNIX only)

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 77 for examples of these log files.

Note: Occasionally, UniData problems result from another process inadvertently removing one
of the UniData message queues. You can compare the log files with ipcstat output to find
out if this is the cause of a hang or system failure. If a queue is removed, the initial list from the
appropriate log includes the queue, but ipcstat does not include the queue.

Removing ipc structures

Certain types of system failures cause ipc facilities that are associated with UniData to be left after
UniData was been shut down. This problem can occur if the system crashes or if one of the daemons
is inadvertently killed. In such cases, restarting UniData fails because of the remaining ipc structures.
You may see symptoms like the following:
▪ The startud command fails.
▪ A message displays in the startud window that indicates smm is still running.
▪ Running showud indicates udsmm is not running.
If you encounter these symptoms, complete the following steps:

1. Check for remaining facilities

Enter the UniData ipcstat command at the UNIX prompt. If the output shows structures that are
associated 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 startup
failure.

Tip: Occasionally icpstat fails to complete. You can obtain the information that you need by
running the UNIX ipcs command and comparing the output with smm.log and sbcs.log to
identify UniData structures.

2. Stop UniData
If showud indicates that none of the UniData daemons is running, proceed to step 3. Otherwise, run
the stopud command. This command stops the daemons appropriately. Then proceed to step 3.

304
 3. Decide how to proceed

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 ipc
facilities that are associated with UniData processes. The following screen shows the output from
udipcrm:
# $UDTBIN/udipcrm
ipcrm: msqid(1106): not found
ipcrm: msqid(1107): not found
ipcrm: msqid(1108): not found
ipcrm: msqid(1109): not found
...
ipcrm: shmid(4308): not found
ipcrm: shmid(2709): not found
ipcrm: shmid(513): not found
ipcrm: shmid(414): not found
ipcrm: semid(708): not found
#
The “not found” messages appear because resources forced out by udipcrm try to send messages to
ones that are already gone.
After successfully completing udipcrm, you should be able to restart UniData. Proceed to step 6; you
do not need to complete step 5.

5. Remove ipc facilities with UNIX ipcrm

The UNIX ipcrm command removes specific ipc facilities by specifying their identifiers. For this
reason, ipcrm is easy to use if you are removing only a few facilities.
Refer to your host operating system documentation for detailed information about the ipcrm
command. You must log on as root to run it. You need the output from ipcstat to identify the
resources to remove. Note the type (column 1 of ipcstat output; must be m, q, or s) and the ID
(column 2 of ipcstat output).
The following screen shows an example of ipcstat - q output:
# $UDTBIN/ipcstat -q
IPC status from /dev/mem as of Thu Jan 5 07:22:12 MST 2012
T ID KEY MODE OWNER GROUP
Message Queues:
q 0 0x4107001c -Rrw-rw---- root printq -> unknown
q 45088769 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 45088770 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 48234499 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 44040196 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 45088773 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 39845894 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 48234503 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 46137352 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 40894473 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 44040202 0xffffffff -Rrw-rw-rw- root system -> smm R8.1.1 (request)
q 42991627 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 44040204 0xffffffff -Rrw-rw-rw- root system -> cm R8.1.1

305
Chapter 21: Managing ipc facilities (UNIX only)

q 44040205 0xffffffff --rw-rw-rw- root system -> tm R8.1.1

q 42991630 0xffffffff --rw-rw-rw- root system -> smm R8.1.1 (reply)
q 45088783 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 44040208 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 40894481 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 46137362 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 41943059 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 5242900 0xffffffff --rw-rw-rw- root system -> unknown
q 45088789 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 50331670 0xffffffff --rw-rw-rw- root system -> udt R8.1.1
q 5242903 0xffffffff --rw-rw-rw- root system -> unknown
q 44040216 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 39845913 0xffffffff --rw-rw-rw- root system -> sbcs R8.1.1 (fromsbcs)
q 39845914 0xffffffff --rw-rw-rw- root system -> sbcs R8.1.1
(newversion)
q 60817435 0xffffffff --rw-rw-rw- root system -> tm R8.1.1
q 40894492 0xffffffff -Rrw-rw-rw- root system -> sbcs R8.1.1 (tosbcs)
q 53477405 0xffffffff --rw-rw-rw- root system -> sm R8.1.1
q 17825822 0xffffffff --rw-rw-rw- root system -> unknown
q 17825823 0xffffffff --rw-rw-rw- root system -> unknown
q 50331680 0xffffffff -Rrw-rw-rw- root system -> rm R8.1.1 (request)
q 39845921 0xffffffff --rw-rw-rw- root system -> rm R8.1.1 (reply)
#

Warning: Exercise extreme caution when removing ipc resources. Removing the wrong ones will
cause problems elsewhere on the system.

6. Restart UniData
Once you remove the ipc facilities that were left over, you should be able to restart UniData with the
startud command. UniData should restart normally.

Note: If UniData will not start, repeat steps 1 through 6. If UniData still will not start, the problem
is unrelated to ipc facilities. Examine the error logs in udtbin (smm.errlog and sbcs.errlog)
and resolve all indicated error conditions.

306
Chapter 22: Performance monitoring and tuning
(UNIX only)
This chapter outlines factors that can affect UniData performance on your UNIX platform, lists generic
UNIX tools for monitoring components of your system, and describes UniData-specific procedures for
monitoring performance.

UNIX performance considerations

Optimizing performance for any application on a UNIX platform may involve tuning and balancing
among the four components of a UNIX system:
▪ Disk I/O Subsystem—Controls physical input/output to disk drives.
▪ Virtual Memory Subsystem—Manages memory allocation, swapping, and paging.
▪ Process Scheduling Subsystem—Controls how processes use system resources.
▪ Network Subsystem—A collection of computers, terminal servers, peripherals, and workstations
that allows users to share data and resources.
The following table outlines the significance of these areas for UniData.

Component Relationship to UniData performance

Disk I/O Subsystem Significant performance factor for UniData as for many
database systems. Although UniData includes many features
to increase I/O efficiency, optimizing configuration and
implementing disk striping (if available) may improve
performance.
Virtual Memory Subsystem Not a performance factor in most cases; If memory is
insufficient, UniData processes usually fail.
Process Scheduling Subsystem Not a significant performance factor if you consider elementary
scheduling factors.
Network Subsystem May be a significant performance factor because of impacts on
I/O performance

UNIX performance monitoring

Monitor your performance regularly to develop baseline expectations throughout your application’s
processing cycle. The performance history of your system provides information that you can use to
implement new procedures (such as scheduling certain jobs to run off-hours or purchasing more
resources) as well as to identify problems quickly to minimize downtime.

Tip: Consider setting up a cron job to gather performance statistics at scheduled intervals. Refer
to your host operating system documentation for information about the cron command.

Tools
The following table lists UNIX commands useful for performance monitoring and describes
information available from each.

307
Chapter 22: Performance monitoring and tuning (UNIX only)

UNIX Command Description

uptime Displays number of users and average system load (number of
processes in the run queue).
iostat Monitors CPU activity and disk I/O activity. Useful for
identifying disk bottlenecks and for balancing disk load.
vmstat Monitors CPU activity and memory usage. Useful for
identifying memory shortages.
ps Displays information about active processes.

Note: Command names, syntax, and options for performance monitoring tools differ among UNIX
versions. Refer to your host operating system documentation for information specific to your
system.

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 indicate
memory shortages. Poor performance that is associated with processes that are blocked for I/O may
indicate disk I/O problems.

iostat
Results that may indicate I/O problems include: CPU in system state more than 50% consistently; CPU
has high idle time despite heavy system load; CPU is never idle; disk activity is unbalanced.

UniData performance factors

Within UniData applications, the major performance factors are: database design, file sizing, and
program coding efficiency.

Database design considerations

▪ Structure your database so that records do not exceed a size limit of 4 K.
▪ When possible, avoid long, multivalued, variable-length records.

308
 Using alternate key indexes

▪ Locate the most frequently accessed attributes near the beginning of a record.
▪ As much as possible, make record keys numeric and short in length.

Using alternate key indexes

Using alternate key indexes speeds query access in a hashed file, but can slow file updates. Consider
this factor when you create indexes. The more indexes that are created for a file, the longer an update
takes.
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. Consider
running 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 occurs
when primary keys outgrow the block, has a particularly serious performance impact. Level 1
overflow, which occurs when data overflows the block, eventually affects performance as well.
For information about file sizing commands, refer to Sizing dynamic hashed files, on page 309 and to
the UniData Commands Reference and Using UniData.

Tip: Consider using cron to run the UniData system-level checkover command in each of your
UniData 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 a
minimum modulo. Splitting prevents level 2 overflow conditions because a group splits whenever
the percentage occupied by keys exceeds a preset value. Merging supports efficient access to the file
because maintaining the file at a low modulo makes searches faster.
For information about dynamic file sizing commands, refer to Managing UniData files, on page 117 and
to the UniData Commands Reference.

UniBasic coding tips

The efficiency of your UniBasic application has a significant impact on UniData performance. Use the
following guidelines when designing and coding.

309
Chapter 22: Performance monitoring and tuning (UNIX only)

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 programs
access the same code.
▪ When using CALLs:
▫ Avoid opening files; pass data through common areas or an argument list.
▫ Minimize the number of local variables in subroutines.
▫ Use inserts, common areas, and argument lists whenever possible.
▪ Use A += B instead of A = A + B.
▪ 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.

310
 Manage locks carefully

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 profiling
UniData enables users to generate execution profiles that track call counts and execution times for
UniBasic programs, internal subroutines, and program calls. You can use these profiles to identify
sections of your UniBasic application that are called most frequently, and then focus optimization
efforts in those areas.
Complete the following steps for UniBasic execution profiles.

1. Compile the programs with -G

Compile UniBasic programs with the -G option to include information about internal subroutines in
the profile reports.

2. Run the programs with -G

To profile a UniBasic program, run the program with the -G option. See Developing UniBasic
Applications for information about compiling and running programs.

3. Review the profile output

Profile output is stored in the UNIX directory where the UniBasic program was run. Output files are
called profile.pid and profile.elapse.pid where pid is the process ID of the user’s UniData
process.
The following screen shows a sample profile for a UniBasic program:

311
Chapter 22: Performance monitoring and tuning (UNIX only)

In this example, the main program is called MAIN_PROG. It has three internal functions, named
SUBRA, SUBRB, and SUBRC.

Note: profile.pid reports execution times as CPU execution time, while

profile.elapse.pid reports “real” time.

Each profile display includes two sections. The top section presents summary information, and the
bottom section presents detail. The following table describes the fields in the top section of a UniBasic
Profile display. There is one line for each function of the program.

Field Description
%time Percentage of the total run time that is used by the program or
subroutine.
cumsecs Running sum of seconds for this program or subroutine and all
called 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 ease
of reporting. For each index, UniData computes information about functions that call, or are called
by, the function corresponding to the index. The detail section of a profile contains this information,
which is grouped by index. The next table describes the fields in the detail section.

312
 UniData performance monitoring: udtmon

Field Description
index An identifying number that is assigned by UniData to the program
or subroutine. UniData assigns the indexes in descending order
of execution time. The index in column 1 identifies the routine of
interest for the group of data (the current index function).
%time Percentage of the total program runtime that is used by the
program or subroutine and its descendants.
self Time that is spent by the program or subroutine either calling, or
being called by, the program or subroutine that is identified by the
current 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 number
of times this index is called by the parent that is listed in the name
field.
called+self—line that contains the index; lists number of times the
routine is called and the number of times it calls itself.
called/total—lines below the index number analyze children and
descendants; lists number of times this index calls the child that is
listed in the name field.
name Name of the program or subroutine analyzed in this row of the
report subsection.
index Index value that is assigned to the program or subroutine that is
listed 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 index
number 2. “Parent” functions, or functions that call SUBRA, are listed above it; “descendants,” or
functions 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 by
SUBRA. The function is called once by the main program, BP/MAIN_PROG.

UniData performance monitoring: udtmon

The UniData Monitor Utility, udtmon, enables you to monitor various characteristics at the system
level. Many of these characteristics can impact performance. Invoke the UniData Monitor Utility by
entering the UniData system-level command udtmon at a UNIX prompt.

313
Chapter 22: Performance monitoring and tuning (UNIX only)

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 the
appearance of a graphic display and a text display, respectively:

314
 UniData performance monitoring: udtmon

Note: In Graphic mode, Display provides a series of lines that reflect the current number
of operations that are covered by the display. You can configure this display by using the
Configuration 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 display
since Monitor/Profile was started. Data is reported in operations per second. The default display
interval 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. The
screen looks like the following example:

315
Chapter 22: Performance monitoring and tuning (UNIX only)

Note: When you highlight an option on the menu, a brief description displays at the bottom of the
screen.

udtmon: UniData user statistics

When you select UniData User from the Display menu, the following screen appears:

316
 udtmon: file I/O statistics

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 for
performance.

Field Description
File Open Number of file opens at the operating system level, from UniBasic OPEN
commands. On UNIX, if the average value in this field is more than 10
(opens per second), performance may suffer. Consider opening files in
named common, and using pointers for subsequent access.
File Close Number of file closes at the operating system level, from UniBasic
CLOSE 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. If
the average value in this field is consistently more than zero, consider
increasing the kernel parameter that defines the number of open files
per process, and increase the UniData configuration parameter NFILES.
Record Read Number of records that are read by UniData commands (other than
UniQuery). For most applications, Record Read is greater than Record
Write.
Record Write Number of records that are written by UniData commands (other than
UniQuery).
Record Delete Number of records that are deleted by UniBasic commands (other than
UniQuery).
Level 1 Overflow Number of operations (reads, writes, and deletes) to records in level
1 overflow blocks. Compute the total activity by adding Record Read,
Record Write, and Record Delete. If you are using only static files and
Level 1 Overflow is more than 10% of the total activity, use guide to
analyze your files and resize them appropriately.

317
Chapter 22: Performance monitoring and tuning (UNIX only)

Field Description
Level 2 Overflow Number of operations (reads, writes, and deletes) to records in level
2 overflow. If Level 2 Overflow is more than 2% of total activity, use
checkover or guide to identify files in level 2 overflow and resize
them appropriately.

udtmon: program control statistics

Selecting Program Control from the Display menu produces a screen similar to the following
example:

The following table describes the fields in the Program Control display, and indicates performance
considerations.

Field Description
Local Call Number of calls to locally cataloged UniBasic programs. Locally
cataloged UniBasic programs involve heavy I/O activity and
increased memory demand, because each local call loads a copy
of the executable in memory. In a development environment,
using locally cataloged programs may be normal. In a production
environment, if more than 5% of calls are to locally cataloged
programs, examine your application and globally catalog
programs for more efficient memory use.
Global Call Number of calls to globally cataloged UniBasic programs. In a
production environment, this number should be much higher
than Local Call. If a program is globally cataloged, users share a
single copy of the object code in memory, which reduces both
memory requirements and physical I/O load.
CALLC Call Number of calls to an external C function, from UniBasic CALLC
statements.
CHAIN Call Number of UniBasic CHAIN statements run.

318
 udtmon: dynamic array statistics

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 consider
replacing PCPERFORM logic with C routines.
SLEEP Number of UniBasic SLEEP command executions. A sudden
increase in this number may indicate that a number of users are
attempting to get a lock on a record.

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.

319
Chapter 22: Performance monitoring and tuning (UNIX only)

Field Description
MATCHFIELD Number of dynamic array substring matches, from MATCHFIELD
command.
MATPARSE Number of dynamic array matrix parses, from MATPARSE
command.
REMOVE Number of dynamic array element removals, from REMOVE
command.
REPLACE Number of dynamic array replacements, from REPLACE command.

udtmon: lock statistics

The following table describes the fields of the Lock Statistics display, and indicates performance
considerations:

Field Display
Record Lock Number of user-level record locks set by commands such as READL
and READU.
Record Unlock Number of user-level locks that are released by commands such as
RELEASE.
Semaphore Lock Number of user-level resource locks set by commands such as LOCK
and T.ATT.
Semaphore Unlock Number of user-level resource locks released by commands such as
T.DET or 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 number
of exclusive group locks. If the number of exclusive group locks is
greater than the number of shared group locks, one or more files may
be 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 index
locks. If the number of exclusive index locks is larger than the number
of shared index locks, one or more index files may be overflowed.
Identify these locks with LIST.INDEX.
End-of-File Lock UniData-level lock that is required when UniData extends a file by
adding overflow groups or by splitting a dynamic file. If this number
is consistently greater than zero, and the Dynamic File statistics do
not show splitting and merging, one or more files overflowed. Identify
these and resize them for improved performance.
Lock Failure Number of times a process attempts to get a user-level lock and fails
because the record is already locked. If performance is suffering,
analyze your application for improper lock handling.
GLM Lock Request Number of times a udt process checks the global lock manager to
get a lock.
GLM Lock Failure Number of times a udt process attempts to get a lock from the global
lock manager and fails because the record is already locked.

320
 udtmon: sequential I/O statistics

Note: In some circumstances, this screen may indicate that more records are being unlocked than
are being locked. This is a function of how UniData gathers the statistics and does not indicate a
problem.

udtmon: sequential I/O statistics

Selecting Sequential I/O displays statistics for I/O operations on sequential files. The following screen
shows the display.

The following table describes the fields of the Sequential I/O display.

Field Description
OPENSEQ Number of UniBasic OPENSEQ executions.
CLOSESEQ Number of UniBasic CLOSESEQ executions.
READSEQ Number of UniBasic READSEQ executions.
WRITESEQ Number of UniBasic WRITESEQ executions.
OSOPEN Number of UniBasic OSOPEN executions.
OSCLOSE Number of UniBasic OSCLOSE executions.
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 the
following example.

321
Chapter 22: Performance monitoring and tuning (UNIX only)

The information displayed on the screen provides an overview of a UniBasic application in terms of
data handling. The following table describes the actions that are counted in the Data Conversion
Statistics 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.

322
 udtmon: index statistics

The following table describes the fields on the Index Statistics display.

Field Description
Node Read Number of index node reads; a node is a component of the B+ tree
structure, and a node is analogous to a block in a 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 not
properly sized. Use the ECL LIST.INDEX command to identify
these indexes, and then run DELETE.INDEX...ALL, and
CREATE and BUILD the indexes with a longer key length.
Node Reuse Number of times a node that is previously freed by a node merge
is used for a node split.
Log Read Number of reads from an index log file; these occur when an index
that was disabled is re-enabled and updated with the contents of
the index log.
Log Write Number of writes to an index log file. These occur while an index
is disabled, as UniData tracks changes by recording them in the
index log.
Overflow Read Number of times UniData reads from an index overflow node.
The system creates overflow nodes when the number of keys in
an index exceeds a set limit. Reads to and writes from overflow
nodes slow system performance. If overflow activity (reads and
writes) exceeds 5% of system activity (node reads and node
writes), use the ECL LIST.INDEX command to identify which
indexes 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.

323
Chapter 22: Performance monitoring and tuning (UNIX only)

Note: Notice in the sampleIndex Statistics display the number of Overflow Reads and Overflow
Writes 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 specified
time interval.
Latch Wait Reserved for future use.
Latch Total Number of toggles used in specified time interval.
Mglm Normal Number of normal locking operations in the specified time
interval. This type of locking is the most frequently used, and
reflects I/O performance.
Mglm Upgrade Number of upgrade locking operation in the specified time
interval. If no index related operations occur, this number may
be 0.
Mglm Downgrade Number of downgrade locking operations in the specified time
interval.
Mglm Release Number of release locking operations in the specified time
interval.
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.

324
 udtmon: Mglm performance

Field Description
Toggle Rate Toggle Failure / Total Latch. This rate should be low. If
the number is consistently greater than 5, increase the
TOGGLE_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/O
performance and should be low.

325
Chapter 23: UniData and the UNIX file system
(UNIX only)
This chapter describes relationships between UniData file types and UNIX file types, and outlines the
structures of various types of UniData files.

UniData directories and files

UniData uses UNIX files, directories, and links to organize its database. A UniData account is, in
simplest terms, a UNIX directory that contains a VOC file, its dictionary (D_VOC), and other files that
are created by the newacct command.
The VOC file serves as the central repository for information about the account. It contains direct
information (such as commands and keywords you can use) and pointers to menus, data, dictionary
files, and cataloged programs. For information about the newacct command, see Managing UniData
accounts, on page 89.

Note: The data and dictionary files that are referenced in a VOC file are not necessarily located in
the same UNIX directory as the VOC file. You can list the files that are defined for a UniData account
by 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 the
relationships between UniData file types and UNIX file types.

UniData file type UNIX file type

Static hashed file Data file.
Dynamic hashed file UNIX directory that contains data files and overflow files (or UNIX
symbolic links to these files) and indexes (if any are built). The
data, overflow, and index files are UNIX data files.
Sequentially hashed file UNIX directory that contains data files and overflow files and
indexes whose records are stored in sequential order based on
the @ID. A sequentially hashed file has a fixed modulo, just like a
static hashed file.
Dictionary (DICT) file (A static Data file that contains attribute and record definitions for a
hashed file) UniData file.
Alternate key index (for static Data file located in the same directory at the same level as the file
file) that is be indexed.
Alternate key index (for dynamic Data file located in the dynamic file directory along with the data
file) file and the overflow file.
DIR file UNIX directory. You can copy records from another file into a DIR
file with the ECL COPY command; each such record is stored as a
UNIX 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 all
hashed files in the directory. You can copy records from one file
into another file within the directory.

326
 Files, pointers, and links

UniData file type UNIX file type

MULTIDIR (multilevel DIR file) UNIX directory that contains one or more subdirectories. One
dictionary exists for the MULTIDIR, which is shared by each
subdirectory. If you copy records from another file into one of the
subdirectories, each record is stored as a UNIX text or data file.

You can define links and pointers within UniData to reference files that are located in different UNIX
file systems. When setting pointers in VOC entries, you can also define environment variables for the
paths 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 was
created. The following screen shows the ECL CREATE.FILE command (creating a static file) and the
ECL LS command (displaying the account directory).
UniData Release 8.2.1 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 5
Create file D_STATIC.TST, modulo/1,blocksize/1024
Hash type = 0
Create file STATIC.TST, modulo/5,blocksize/1024
Hash type = 0
Added "@ID", the default record for UniData to DICT STATIC.TST.
:LS
BP D_SAVEDLISTS D__REPORT _SAVEDLISTS _REPORT_
CTLG D_STATIC.TST D__SCREEN STATIC.TST _SCREEN_
D_BP D_VOC D__V__VIEW VOC __V__VIEW
D_CTLG D__HOLD_ D_savedlists_HOLD_ savedlists
D_MENUFILE D__PH_ MENUFILE _PH_

Setting a UniData pointer

You can set a pointer in a UniData VOC file to a data file in another UniData account. This feature
allows users that are working in different UniData accounts to share data files. Remember two points
to about setting a VOC pointer:
▪ A VOC pointer is internal to UniData. It is not the same thing as a UNIX link. Because of this, even
backup utilities that follow symbolic links do not automatically follow VOC pointers. See Setting a
UNIX link, on page 329 for more information about UNIX links.
▪ Setting a VOC pointer does not alter the physical location of the data file. Although you can access
the file from the directory where the pointer resides, the physical location of the file and its indexes
remains unchanged.
The following screen shows the ECL SETFILE command (setting a VOC pointer):
:SETFILE /usr/ud82/demo/INVENTORY INVENTORY
Establish the file pointer

327
Chapter 23: UniData and the UNIX file system (UNIX only)

Tree name /usr/ud82/demo/INVENTORY

Voc name INVENTORY
Dictionary name /usr/ud82/demo/D_INVENTORY
Ok to establish pointer(Y/N) = Y
SETFILE completed.
:LIST INVENTORY WITH FEATURES LIKE "Portable..." FEATURES
LIST INVENTORY WITH FEATURES LIKE "Portable..." FEATURES 18:56:11
May 21 2011 1
INVENTORY. Features......................
39300 Portable, Sports Model
12006 Portable Color Ink Jet
39400 Portable Model
39000 Portable Sports Model
38000 Portable, 5-disk
52070 Portable Color, 3 ppm
52060 Portable Ink Jet, 5 ppm
10008 Portable, B/W, 6 ppm
30000 Portable Clock Radio
10009 Portable Color, 6 ppm
39100 Portable, Basic Functions
11 records listed
:LS
BP D_SAVEDLISTS D__REPORT _SAVEDLISTS _REPORT_
CTLG D_STATIC.TST D__SCREEN sandSTATIC.TST
_SCREEN_
D_BP D_VOC D__V__VIEW VOC __V__VIEW
D_CTLG D__HOLD_ D_savedlists _HOLD_ savedlists
D_MENUFILE D__PH_ MENUFILE _PH_
Notice that you can set the pointer and then access the file. However, the physical location of the file
remains in /usr/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 Commands
Reference 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 to
change each associated VOC entry. The following screen shows how to set an environment variable for
the 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 are
using 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 the
demo database:

328
 Setting a UNIX link

:WHERE
/users/testacct
:!printenv DEMO
/usr/ud82/demo
:CT VOC INVENTORY
VOC:
INVENTORY:
F
@DEMO/INVENTORY
@DEMO/D_INVENTORY
:
When users access the INVENTORY file, UniData uses the environment variable to locate the file. If you
move the entire demo database, you can redefine the environment variable to the new path. Users
can continue to access the files.

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

Warning: You can use environment variables only in VOC entries for files. You cannot use them in
other 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 UNIX
level. When you set a symbolic link, UNIX creates an entry in your current working directory that points
to the location you linked to.
The following screen shows how to set a symbolic link to a UniData file in another account:
% pwd
/users/ump01/testacct
% ln -s /usr/ud82/demo/ORDERS ORDERS
% ln -s /usr/ud82/demo/D_ORDERS D_ORDERS
:udt

UniData Release 8.2.1 Build: (6069)

© Rocket Software, Inc. 1985-2015.
All rights reserved.

Current UniData home is /disk1/ud82/.

Current working directory is /users/ump01/testacct.
:LS
BP D_ORDERS D__REPORT_ ORDERS _REPORT_
CTLG D_SAVEDLISTS D__SCREEN_ SAVEDLISTS _SCREEN_
D_BP D_VOC D___V__VIEW VOC __V__VIEW
D_CTLG D__HOLD_ D_savedlists _HOLD_ savedlists
D_MENUFILE D__PH_ MENUFILE _PH_
Notice that ORDERS and D_ORDERS appear in the LS output. UNIX creates an entry in the current
working directory for the link, although the ORDERS file remains physically located in /usr/ud82/
demo.
To access ORDERS from the current account, you must add a VOC entry for the file. You can use
SETFILE (by entering SETFILE ORDERS ORDERS at the colon prompt), or you can use AE, as
shown in the following example:
:LIST ORDERS WITH ORD_DATE LIKE "...1996"
Not a filename :

329
Chapter 23: UniData and the UNIX file system (UNIX only)

ORDERS
:AE VOC ORDERS
Top of New "ORDERS" in "VOC".
*--: I
001= F
002= ORDERS
003= D_ORDERS
*--: FI
Filed "ORDERS" in file "VOC".
LIST ORDERS WITH ORD_DATE LIKE "...1996" ORD_DATE
LIST ORDERS WITH ORD_DATE LIKE "...1996" ORD_DATE 11:37:30 May 22 20111
Order
ORDERS.... Date......
912 01/13/1996
941 01/14/1996
830 01/24/1996
970 01/15/1996
834 01/24/1996
Notice that even though ORDERS appeared in the LS output, you need to add a VOC entry to define
the file to your current UniData account.

Note: Refer to your host operating system documentation for more information about UNIX
symbolic 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. Each
UniData hashed file consists of a file header and one or more groups of data. UniData supports two
proprietary hashing algorithms, which determine which data groups contain each record. Hashing
allows direct access to a record by translating its record key into its location in a data file.
The following screen shows characteristics of a UniData static hashed file:
:LS
AE_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__VIEW
D_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.TEST
STATIC.TEST: data
When you create a static hashed file, you specify the modulo (number of groups) and the block size of
the file. Static hashed files overflow if one or more groups cannot store all the data (level 1 overflow)
or keys (level 2 overflow) of records that are hashed to the group. UniData adds overflow blocks to the
file, but subsequent accessing and updating of records is then resource-intensive and performance

330
 Points to remember about static files

suffers. UniData provides utilities to resize static files by adding more groups (changing the modulo) or
by making the groups larger (changing the block size).

Points to remember about static files

Remember the following points about static files:
▪ A UniData static file is a binary data file.
▪ When you create the file, you define the size of a static file by specifying the number and size of
groups in the file.
▪ When you add records to the file, each record is hashed to a group by using a proprietary hashing
algorithm.
▪ Static files can overflow, causing performance problems.
▪ A static hashed file cannot be larger than 2 GB. If a file exceeds 2 GB, you must make it a dynamic
file.
See Managing UniData files, on page 117 for more information about file management commands.

Dynamic files
A dynamic file is a UNIX directory file, containing index, data, and overflow files (and/or symbolic links
to these 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 file
system. The following screen shows characteristics of a simple dynamic file:
:CREATE.FILE DYNAMIC.TEST 1 DYNAMIC
1 is too small, modulo changed to 3.
Create file D_DYNAMIC.TEST, modulo/1,blocksize/1024
Hash type = 0
Create dynamic file DYNAMIC.TEST, modulo/3,blocksize/1024
Hash type = 0
Split/Merge type = KEYONLY
Added "@ID", the default record for UniData to DICT DYNAMIC.TEST.
:LS
BP D_DYNAMIC.TEST D__PH_ MENUFILE _REPORT_
CTLG D_MENUFILE D__REPORT_ SAVEDLISTS _SCREEN_
DYNAMIC.TEST D_SAVEDLISTS D__SCREEN_ VOC __V__VIEW
D_BP D_VOC D___V__VIEW _HOLD_ savedlists
D_CTLG D__HOLD_ D_savedlists _PH_ vocupgrade
:!ls -l DYNAMIC.TEST
total 10
-rw-rw-rw- 1 terric unisrc 4096 Jun 25 17:13 dat001
-rw-rw-rw- 1 terric unisrc 1024 Jun 25 17:13 over001
Notice that the UniData dynamic file is a UNIX directory, containing UNIX files dat001 and over001. The
dat001 file is a UniData hashed file, and the blocks in over001 are linked to groups in the dat001 file.

The dat001 file

The dat001 file is also called the primary data file. As you add records to a dynamic file, UniData
hashes the keys to groups in dat001. As the file fills up, UniData adds more groups to the dat001
file. If the current file system fills up or if dat001 grows larger than a UniData limit, UniData creates a
dat002 file. If dat002 is in another file system, UniData creates a UNIX link to the dat002 file in the
original dynamic file.

331
Chapter 23: UniData and the UNIX file system (UNIX only)

The over001 file

As you add records to a dynamic file, whenever the space reserved for data in a group in the primary
file gets too full, UniData writes the excess data into blocks in over001. Registers within UniData
track how blocks in over001 are linked to groups in dat001. If over001 gets too large, UniData
adds more blocks to it. If the current file system becomes full or over001 grows larger than a UniData
limit, UniData creates an over002 file. If the over002 file is in a file system different from the
current one, UniData creates a UNIX link to over002 in the original dynamic file.
If you specify the OVERFLOW keyword with the CREATE.FILE command, UniData creates a dynamic
file with an overflow file for each dat file. For example, over001 corresponds to dat001, over002
corresponds to dat002, and so forth. When the file is cleared, UniData maintains this overflow
structure.

Points to remember about dynamic files

Remember the following points about dynamic files:
▪ A UniData dynamic file is a UNIX directory. The directory contains files or UNIX links.
▪ Dynamic files expand and shrink with respect to modulo. Expansion and shrinking take place
automatically during UniData processing.
▪ Dynamic files can expand across UNIX file systems. The original dynamic file contains UNIX links to
any “part files” that are created on other file systems.
▪ Because the parts of a dynamic file are related by symbolic links, you need a backup utility that
follows symbolic links to guarantee complete backups of dynamic files.

Note: Managing UniData files, on page 117 includes detailed information about the behavior of
UniData dynamic files.

Sequentially hashed files

A sequentially hashed file has the same structure as a dynamic file, but UniData stores all records
sequentially based on the primary key. The modulo (number of groups) for a sequentially hashed file is
fixed, it does not grow and shrink as records are added or deleted.
You create sequentially hashed files by converting from existing UniData static or dynamic files. You
specify a percentage of the file that you want to remain empty to allow for growth. Although the
structure for a sequentially hashed file is the same as a dynamic file, the modulo is fixed.
Use sequentially hashed files for files where 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 data overflows the group (level 1 overflow), UniData writes
the overflow data to the over001 file.

The over001 file

As you add records to a sequentially hashed file, whenever the space reserved for data in a group in
the primary file gets too full, UniData writes the excess data into blocks in over001.

332
 The gmekey file

Registers within UniData 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 than a UniData limit, UniData creates an over002 file. If the over002 file resides
in a different file system than the over001 file, UniData creates a link to over002 in the original
sequentially hashed file.
If the sequentially hashed file has level 2 overflow, the file should be rebuilt by using the shfbuild
command.

The gmekey file

Each sequentially hashed file contains a static, read-only file that is called the gmekey file.
This file is read into memory when you open a sequentially hashed file. The gmekey file contains
information about the type of keys in the file (alphabetic or numeric), and controls which group a
record is hashed to when it is written.
You create a sequentially hashed file by converting an existing dynamic or static file with the
shfbuild command.

Syntax
shfbuild [-a |-k] [-n | -t] [-f] [-e empty percent] [-m modulo] [-b
block size multiplier] [-i infile] outfile

Parameters
The following table describes the shfbuild options.

Parameter Description
-a Only rebuild the last group of the sequentially hashed file. UniData splits the
last group into groups according to the records in the group. If you use this
option, the outfile should be the name of the sequentially hashed file. Do not
specify infile.
-k Build the gmekey file only. If you use this option, outfile should be the name of
the sequentially hashed file. Do not specify infile. UniData rebuilds the gmekey
file according to the keys in each group of outfile.
-n/-t Force the outfile to be in numeric or alphabetic order. By default, the order
of outfile is determined by the infile primary key type. If infile is a sequentially
hashed file, UniData uses the same order in outfile. If infile is not a sequentially
hashed file, the order of outfile is determined by the justification of the @ID of
the infile dictionary record. If it is right-justified, it is numeric. Otherwise, it is
alphabetic.
If you use the -a or the -k option, these options have no effect.
-f Force outfile to truncate before 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 the new modulo
of the file from empty_percent and the number of records in the rebuilt groups.
If you do not specify -e or -m, UniData rebuilds the sequentially 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.

333
Chapter 23: UniData and the UNIX file system (UNIX only)

Parameter Description
outfile The name of the output file.

To convert an existing file, run the shfbuild command from the system level prompt, as shown in
the following example:
% shfbuild -m 59 SEQUENTIAL
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 VOC
file in order to access the sequentially hashed file, as shown in the following example:
:AE VOC SEQUENTIAL
Top of New "SEQUENTIAL" in "VOC".
*--: I
001= F
002= SEQUENTIAL
003= D_SEQUENTIAL
*--: FI
Filed "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 or
data file is a UniData record. The BP file, a UniData file that stores UniBasic source files and compiled
programs, is a DIR-type file.
The following screen shows the structure of a sample BP file:
:LIST BP
LIST BP 12:08:40 May 22 2011 1
BP........
MAINPROG
_MAINPROG
SUBR
_SUBR
4 records listed
In the example, MAINPROG and SUBR are UniBasic source files. _MAINPROG and _SUBR are compiled
programs.

Multilevel files
A UniData multilevel (LF-type) file is a UNIX directory that contains one or more UniData hashed files.
All of the UniData hashed files share a common dictionary. To access a record, you must specify both
the directory and the hashed file where the record is located. The following screen shows an example
of a multilevel file:
:CT VOC MULTI1
VOC:
MULTI1:
LF
MULTI1
D_MULTI1
:!ls -l MULTI1
total 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

334
 Points to remember about multilevel files

-rw-rw-rw- 1 claireg unisrc 4096 May 22 12:31 MULTI3

:LIST MULTI1,MULTI2 WITH F1 = PA
LIST MULTI1,MULTI2 WITH F1 = PA 12:46:08 May 22 2002 1
ECLTYPE
CP
listdict
CT
SP.OPEN
LISTDICT
6 records listed

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

Points to remember about multilevel files

Remember the following points about multilevel files:
▪ A UniData multilevel file is a UNIX directory that contains UniData hashed files.
▪ Each multilevel file can contain a mixture of static and dynamic hashed files.
▪ All of the hashed files in a multilevel file share the same dictionary.
▪ UniData supports multilevel files to simplify conversion for legacy applications. However,
accessing and maintaining multilevel files is less efficient than accessing and maintaining ordinary
static or dynamic files. The leveled structure requires more system resources to read and update
these files. For this reason, we recommend that you use ordinary static or dynamic hashed files
rather than multilevel files whenever possible. You can share a single dictionary among UniData
files by modifying the VOC entries for each file to reference the same dictionary.

Multilevel directory files

A UniData multilevel directory (LD) file is a UNIX directory. The UNIX directory contains one or more
UNIX subdirectories (UniData DIR type files). All of the DIR files share the same dictionary. To access a
record, you must specify both the multilevel directory file and the DIR file where the record resides.
The following screen shows characteristics of a multilevel directory file:
:LS
AE_COMS D_CTLG D_VOC MULTI1
_REPORT_
AE_SCRATCH D_DYNAMIC.TEST D__HOLD_ MULTID _SCREEN_
BP D_MENUFILE D__PH_ ORDERS
__V__VIEW
CTLG D_MULTI1 D__REPORT_ SAVEDLISTS savedlists
DYNAMIC.TEST D_MULTID D__SCREEN_ STATIC.TEST
D_AE_COMS D_ORDERS D___V__VIEW VOC
D_AE_SCRATCH D_SAVEDLISTS D_savedlists _HOLD_
D_BP D_STATIC.TEST MENUFILE _PH_
:!ls -l MULTID
total 4
drwxrwxr-x 2 claireg unisrc 24 May 22 12:49 TEST1
drwxrwxr-x 2 claireg unisrc 24 May 22 12:49 TEST2
:LIST MULTID,TEST1
LIST MULTID,TEST1 12:51:57 May 22 2011 1
MULTID....
MAINPROG
_MAINPROG

335
Chapter 23: UniData and the UNIX file system (UNIX only)

SUBR
_SUBR
4 records listed

Note: If a subdirectory of a multilevel directory file has the same name as the main directory, you
can use the main directory name to access the subdirectory. For instance, LIST MULTID is correct
syntax if the directory MULTID contains 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 (UNIX
subdirectories).
▪ All of the DIR files in a multilevel file share the same dictionary.
▪ Each record in a multilevel directory is a UNIX file.
▪ UniData supports multilevel directory files to simplify conversion of legacy applications. However,
accessing and maintaining multilevel directory files is less efficient than ordinary DIR files. The
leveled structure means that more system resources are needed to read and update these files.
For this reason, we recommend that you use ordinary DIR files rather than multilevel directory files
whenever possible. You can share a single dictionary among UniData DIR files by modifying the
VOC entries for each file to reference the same dictionary.

Index files and index log files

UniData creates an index file whenever a user creates the first alternate key index on a UniData hashed
file. Index information is stored in B+ tree format. UniData index files are UNIX data files.

Note: Regardless how many alternate key indexes users create for a data file, UniData creates a
single index file.

The ECL CREATE.INDEX command creates the index file. The ECL BUILD.INDEX command
populates the index. DELETE.INDEX (with the ALL option) removes the index file.
By default, each time a UniData data file is updated, its associated indexes are updated. You can turn
off automatic indexing on one or more data files (by using the ECL DISABLE.INDEX command) to
speed performance during periods of heavy activity on your system. If you turn off automatic indexing
for a file, UniData creates a log file and stores all updates to it. The ECL UPDATE.INDEX command
allows you to apply updates from index logs to indexes in batch mode, and the ECL ENABLE.INDEX
command turns automatic updating back on. Either CLEAR.FILE or DELETE.INDEX (with the ALL
option) removes the index log file.

Note: For more information about index handling commands, see the UniData Commands
Reference.

Index-related files for a static hashed file

For a static hashed file, UniData creates both the index file and the index log file in the account
directory with the data file. The following screen shows a sample account where a static file named
STATIC.TEST has been indexed:
:LS

336
 Index-related files for a dynamic hashed or sequentially hashed file

AE_COMS D_CTLG D_VOC MULTI1 _PH_

AE_SCRATCH D_DYNAMIC.TEST D__HOLD_ MULTID
_REPORT_
BP D_MENUFILE D__PH_ ORDERS _SCREEN_
CTLG D_MULTI1 D__REPORT_ SAVEDLISTS
_V__VIEW
DYNAMIC.TEST D_MULTID D__SCREEN_ STATIC.TEST savedlists
D_AE_COMS D_ORDERS D___V__VIEW VOC
x_STATIC.TEST
D_AE_SCRATCH D_SAVEDLISTS D_savedlists X_STATIC.TEST
D_BP D_STATIC.TEST MENUFILE _HOLD_
X_STATIC.TEST is the index file for the data file STATIC.TEST, and x_STATIC.TEST is the index log file.

Index-related files for a dynamic hashed or sequentially hashed file

For a dynamic hashed or sequentially hashed file, UniData creates both the index file and the index log
file in the dynamic file directory. The following screen shows a sample account where a dynamic file
named DYNAMIC.TST has been indexed:

:LS
AE_COMS D_CTLG D_VOC MULTI1 _REPORT_
AE_SCRATCH D_DYNAMIC.TEST D__HOLD_ MULTID
_SCREEN_
BP D_MENUFILE D__PH_ ORDERS __V__VIEW
CTLG D_MULTI1 D__REPORT_ SAVEDLISTS savedlists
DYNAMIC.TEST D_MULTID D__SCREEN_ STATIC.TEST
D_AE_COMS D_ORDERS D___V__VIEW VOC
D_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 the
account. The file idx001 is the index file, and xlog001 is the index log file.

UniData and tmp space

UniData 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 an
alternate temporary disk storage location by setting an environment variable that is called TMP, or by
changing the TMP parameter in the udtconfig file, located in /usr/ud82/include. If both are
set, the environment variable overrides the configuration parameter.

337
Chapter 23: UniData and the UNIX file system (UNIX only)

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

In most cases, UniData removes its temporary work files when they are no longer needed. Certain files
exist that UniData does not remove, including output files that it generates from filetools. Because the
default /tmp is routinely cleared on many systems, you should consider defining alternate temporary
storage if you know you are going to be repairing files, for example. Otherwise, you risk losing crucial
data if the workfiles are removed before you are finished.

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=1
SYS_PV=3
# 1.2 Changable parameters
NFILES=60
NUSERS=40
WRITE_TO_CONSOLE=0
TMP=/users/tmp/
.
.
.
Notice that the path name for TMP ends with the “/” character. This is required.

Setting an environment variable

You can set the environment variable TMP in individual users’ .login or .profile files to define
alternate temporary disk storage for those users. A user with access to a UNIX prompt can set the
environment variable as well.
In the C shell, use the following commands to set and display the TMP environment variable:
setenv TMP directory-name/
printenv TMP
In the Bourne or Korn shell, use the following commands to set and display the TMP environment
variable:
TMP=directory-name/;export TMP
printenv TMP

338
Chapter 24: UniData and UNIX ipc facilities
(UNIX only)
Interprocess communication (ipc) facilities consist of message queues, shared memory segments,
and semaphores.
UniData and memory, on page 55 describes shared memory handling. This section describes how
UniData uses message queues and semaphores.

Note: The UNIX ipcs and ipcrm commands, and the UniData system-level ipcstat and
udipcrm commands, are useful for tracking and managing ipc resources. Refer to your host
operating system documentation for information about ipcs and ipcrm, and see Managing ipc
facilities (UNIX only), on page 300 for information about ipcstat and udipcrm.

Message queues
A message queue is a system resource that can accept input from a number of processes. Processes
can then retrieve messages from the queue, with some degree of selectivity. UNIX kernels generally
include parameters that define the number of message queues, their size, and the number of
outstanding messages the system can support.
The following table shows UNIX kernel parameters related to message queues and messages.

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 read
from a HP-UX kernel.

UniData and message queues

The smm and sbcs daemons use message queues for interprocess communication. When you start
UniData, UniData initializes log files for each daemon, and lists the queues that are assigned to each
daemon 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.

339
Chapter 24: UniData and UNIX ipc facilities (UNIX only)

UniData daemon Queues

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

Note: If you are using RFS, you need more message queues to handle communications for the RFS
daemons. See Administering the Recoverable File System for information about RFS requirements
for 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 are
configured for a minimal number of queues. Refer to your host operating system documentation
for information about kernel configuration.

Semaphores
UNIX system semaphores are used to control access to resources (like segments of shared memory)
that can handle a limited number of simultaneous users. When a process acquires a semaphore, that
process has access to the system resource the semaphore controls. When the process is finished with
the resource, the process releases the semaphore.
A semaphore undo structure is a resource that is used to recover a semaphore if the process that
acquired it terminates abnormally.
The following table lists UNIX kernel parameters that are important for the use of system semaphores.

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 read
from a HP-UX kernel.

UniData requires that certain kernel parameters have adequate settings in order for UniData to
accommodate the full number of licensed users. The following table lists some recommended kernel
parameters.

Description HPUX Solaris Recommended value

Semaphore semmnu semmnu NUSERS * 3.25
undo
structures
system wide
Shared shmmni shmmni Must be greater than SHM_GNTBLS
memory
max-shm-ids
segments
(Solaris 10+)
Number of msgmni msgmni Non-RFS: 10 + the number of concurrent journal
message processes if you are using UniData Journaling.
max-msg-ids
queues
(Solaris 10+) RFS: ((number of authorized users / 4) * 2) + 10

340
 Semaphores

Description HPUX Solaris Recommended value

Semaphore semmni semmni For UniData 8.1+ and later:
identifiers
max-sem-ids Standard Systems:
(Solaris 10+) semmni >= ((NUSERS / NSEM_PSET) * 2) + 5
Systems with Replication:
semmni >= ((NUSERS / NSEM_PSET) * 3) + 10
For UniData 7.3.x and prior:
Standard Systems: semmni >= (NUSERS /
NSEM_PSET) + 5
Systems with Replication:
semmni >= ((NUSERS / NSEM_PSET) * 2) + 10
Number of semmns semmns semmni * (NSEM_PSET or semmsl)
semaphores
available Note: NSEM_PSET in these formulas are from the
system wide udtconfig file, and the corresponding kernel
parameter is semmsl.

Warning: If semmni or semmns is not tuned high enough, the error in the smm.errlog file will be
similar to the following:
Exit: smm: cannot allocate semaphore for udtno xx errno 28. Exit:
SMM can’t setup Control Table List
When this message displays, UniData will fail to start.

Note: On Red Hat Linux, running telnet in SSL mode will not work when SELINUX is enabled.

Note: If you are using RFS, you might need additional system semaphores. RFS semaphore
operations may be handled at the UNIX system level, or by C or assembler instructions, depending
on what method is most efficient for your UNIX version. For more information, see Administering
the Recoverable File System.

341
Chapter 25: UniData and UNIX devices (UNIX
only)
This chapter briefly outlines how the UNIX operating system communicates with devices such as
terminals, disk drives, tape drives, and printers. The chapter also outlines how UniData interacts with
UNIX devices and device handling.

UNIX devices: overview

The UNIX operating system uses device drivers to communicate with disk drives, tape drives,
terminals, printers, and other hardware. Device drivers are programs that know how to communicate
with each type of hardware. The UNIX kernel accesses these programs whenever a process requests
interaction with a device.
The UNIX communication interface is set up so that any device can be viewed as a file. Data can
be read from and written to a device file. The UNIX kernel translates actions on the device file into
requests from the appropriate device driver program.
On most UNIX systems, device files reside in the /dev directory. This directory contains special files
for serial devices, terminals of various sorts, disk devices, tape devices, and so forth. The names for
these special device files vary among UNIX versions.

Note: For more information about device files and device drivers on your system, see your host
operating system documentation.

UniData and terminal devices

For virtually all terminal input/output, UniData relies on your host UNIX operating system to perform
terminal emulation. UniData does not maintain its own terminal definition files. Different versions of
UNIX handle terminal definitions differently. Some store terminal definition information in a termcap
file while others use a terminfo database. Refer to your host operating system documentation for
information about terminal definitions for your system.
Because terminal emulation in UniData happens at the UNIX level, terminal emulation problems that
occur within UniData must be resolved at the UNIX level.

Note: 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 file
with extensions. This file is located in udtbin. To run the utilities that require it (which include
confprod, udtconf, and shmconf) you must define either the UDTBIN or the VVTERMCAP
environment variable. See Environment variables for UniData, on page 396 for further
information.

UniData and tape devices

Names for tape device files vary considerably between UNIX versions. The name of a tape device file
often identifies a tape drive and an access method (such as rewind/no rewind).
UniData includes a number of commands that allow you to read data from or write data to UNIX
tape devices. To use these commands effectively, you need to understand the tape device naming

342
 UniData and printers

conventions on your system, because you need to specify device names to define them in UniData.
Refer to your host operating system documentation for this information.
UniData uses various proprietary methods, as well as standard UNIX commands, to read/write data
to tape devices. Tape devices must be defined in a UniData file before you can access them via
UniData commands. See Accessing UNIX devices (UNIX only), on page 277 and the UniData Commands
Reference for more information.

UniData and printers

UniData uses the UNIX spooler on each system to perform all printing. In order to print from within
UniData to a UNIX printer, that printer must be connected to your system and defined within your
spooler software. UniData provides commands and options that interface with your spooler and
enable you to direct output to a printer or a class of printers.
Many printer problems that appear within UniData must be resolved outside of UniData, since the
UniData commands do not interact directly with a printer device. You need to understand the printer
configuration and spooler software on your system to troubleshoot UniData printing problems.
Since different UNIX versions use different spooler commands, UniData enables you to define
the translation between UniData printing options and UNIX spooler options by defining a spooler
configuration file. You can determine your current spooler selection with the ECL LIMIT or SETPTR
command. For more information about defining spooler commands, refer to Managing printers in
UniData, on page 183.

UniData and serial devices

UniData includes a group of commands that allow you to read data from or write data to a UNIX serial
device. Although you can use these commands to access a terminal or printer device, they are most
commonly used for communicating between UniData and a device, such as a bar code reader or
scale. If such a device has a physical connection to your system, you can define it within UniData and
communicate with it through UniBasic commands.
To make effective use of these UniData capabilities, you need to understand your configuration and
device naming conventions. Refer to your host operating system documentation for this information.
See Accessing UNIX devices (UNIX only), on page 277 and Developing UniBasic Applications for
information about communicating with serial devices.

343
Chapter 26: Dynamic Linking, CallBasic, and
CALLC (UNIX only)
This chapter describes the use of dynamic linking with UniData (new at UniData 8.2.0), writing
UniBasic programs that call external C programs (CALLC), and external C programs calling UniData
(CallBasic).
The information in this chapter applies to the UNIX operating system only.
• Dynamic linking in UniData
Starting with the UniData 8.2.0 release, the core libraries for UniData on UNIX/Linux were changed
from being statically linked to being dynamically linked.
• Accessing C from UniBasic (CALLC)
This section provides instructions on using UniBasic programs to interact via C (CALLC).
• Accessing UniData from a C program (CallBasic)
The CallBasic application programming interface (API) allows you to access a UniData database by
calling UniBasic subroutines from a C program.

Dynamic linking in UniData

Starting with the UniData 8.2.0 release, the core libraries for UniData on UNIX/Linux were changed
from being statically linked to being dynamically linked.
Before detailing information about accessing between C and UniData, it is important to understand
changes in UniData 8.2.0 related to dynamic linking of the core UniData libraries.
If you are using UniData 8.1.x or older, refer to the UniData documentation associated with the version
of UniData you have installed.

Important:
With the change to dynamic linking, the executables makeudt and makeudapi are no longer
used. If you run makeudt, a short how-to displays noting this change. The libu2callc.so/sl
file includes the custom code and the udt or udapi_slave executables are not modified.
The cfuncdef_user file is also no longer used. Only cfuncdef is referenced. If the cfuncdef
file has been changed, an upgrade will not replace it.

Changing from static linking to dynamic linking offers these benefits:

▪ Only one copy of each function is stored in memory and shared among all users
▪ UniData install image size on some platforms is substantially reduced
▪ UniData executable program sizes are substantially reduced
▪ Patching may be easier in some cases as only library changes may be needed
▪ Linking is done at runtime
There are new UniData libraries linked to the UniData executables. The following libraries have .so
extensions for AIX, Solaris, and Linux platforms, and .sl extensions for HP-UX.

File Description
libunidata.so/sl The UniData run machine and general functions.

344
 Runtime linking

File Description
libunidata_rfs.so/sl RFS related functions. Not all executables link to
this file.
libu2callc.so/sl Custom CALLC functions.
libu2callc_nfasvr.so/sl NFA functionality is needed for CALLC. Not all
executables link to this file.
libodbc.so/sl ODBC functions: these can be from third-party
sources.

• Runtime linking
Inside the UniData executables, only the filenames are referenced in the object code. Fully
qualified paths are no longer used. This means that at runtime of the executable, a search order is
used to find all libraries.
• The /.udlibs## definition
The /.udlibs## link (where ## represents the major UniData version) in the root directory
typically points to the $UDTHOME/lib/uddlls directory.
• Dynamic library search method and tools
To have the dynamic libraries found properly, it is important to understand the behavior of the
search method on each operating system and how to troubleshoot linking errors.
Parent topic: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Runtime linking
Inside the UniData executables, only the filenames are referenced in the object code. Fully qualified
paths are no longer used. This means that at runtime of the executable, a search order is used to find
all libraries.
If an executable cannot be found, a message similar to the following is displayed:

# udt
Could not load program udt:
Dependent module libunidata.so could not be loaded.
Could not load module libunidata.so.
System error: No such file or directory
#

The search order for the libraries are platform specific. Generally, the order is:
1. Dynamic linking environment variables
2. The /.udlibs## file, where ## represents the major UniData version
3. Any remaining default system paths
All UniData executables check the /.udlibs## path. If you were using the dynamic library
environment variables previously only for XML, these variables are no longer needed. But, if you use
these dynamic library environment variables for other reasons (such as third-party ODBC drivers),
then continue to use these environment variables. It is good practice to use the dynamic library
environment variables noted to force the library look-up mechanism to the path you intend to use.
These variables are also helpful when testing CALLC functionality.

345
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Note: Starting at UniData 8.1.0, only 64-bit builds are produced. When changing your make files,
you may need to add 64-bit compiler options. Refer to OS documentation for the exact syntax
needed.

Parent topic: Dynamic linking in UniData

The /.udlibs## definition

The /.udlibs## link (where ## represents the major UniData version) in the root directory typically
points to the $UDTHOME/lib/uddlls directory.
Previously, this would only include libodbc.so/.sl. Starting at 8.2.0, it will also include links to
the UniData bin libraries needed by the UniData executables.
The /.udlibs## link is reset on UniData installs and upgrades. The location of the /.udlibs##
link is commonly changed when third-party ODBC drivers are used. It is highly recommended
that when this path is changed, that the relink.udlibs /new_path command be used to
confirm that all links are set up properly. The first parameter is the parent directory of where the
libodbc.so/.sl file is found. To reset the links to the default path, use the command $UDTBIN/
relink.udlibs $UDTHOME/lib/uddlls.

Warning: Be careful when moving this directory, as the links are created, but are not removed. If
LD_LIBRARY_PATH or LIBPATH (on AIX) contains a directory with links to the UniData libraries
(even an old version), these files will be used before the paths in /.udlibs## are resolved.

Parent topic: Dynamic linking in UniData

Dynamic library search method and tools

To have the dynamic libraries found properly, it is important to understand the behavior of the search
method on each operating system and how to troubleshoot linking errors.
The following tools referenced are based on IBM AIX 7.1, HP-UX 11.31, Red Hat Linux (RHEL) 6, and
Oracle (Sun) Solaris 11 SPARC. These are the UniData 8.2.x build platforms. The exe_name would be
the executable you want to review. For example, “udt”.
A shared library may be found in more than one directory using the various search paths. The first
occurrence found in the search paths will be used. It is best to use the following tools to identify which
path is being used.

346
 Dynamic library search method and tools

Warning:
▪ The $ENV variable may be called before some executables, and may override any environment
variables set.
▪ On AIX, the ldd command does not take into account the $LD_LIBRARY_PATH variable.
▪ The use of Java clients local to the server may require the OS-specific variables to be set. For
example, LIBPATH on AIX and SHLIB_PATH on HP-UX.
▪ The libodbc.so/.sl file shipped with UniData may be found in both the /.udlibs##
path and $UDTBIN directory.
▪ Using different types of UNIX shells may generate different results than the search orders noted.
The information included is mostly based on using ksh on AIX and HP-UX, and bash on Linux
and Solaris.
▪ In some cases, ldd and executable programs will look first in the current directory before other
locations. However, this is not consistently done in all situations, and may be seen more on AIX
than other platforms.

In some tool output, you may see references to UniData paths that typically should not exist. These
are internal build system paths and can be ignored if not found.

AIX
Tools: ldd exe_name; dump -H -X64 exe_name
Search order: $LIBPATH, $LD_LIBRARY_PATH, /.udlibs##, system default paths
On AIX, $LIBPATH is searched before anything else. Support for $LD_LIBRARY_PATH was added
at AIX 5.3, but it is still secondary to $LIBPATH. After $$LIBPATH and $LD_LIBRARY_PATH, the
location defined by the /.udlibs## is used, and finally any system default paths. If you look at
‘dump -H -X64 udt’ in the ‘INDEX 0’ position, you may see the default search path.
Refer to the previous warnings, especially the $ENV and ldd items.

HP-UX
Tools: ldd exe_name; chatr exe_name
Search order: $LD_LIBRARY_PATH, $SHLIB_PATH, /.udlibs##, system paths
Unlike AIX, on HP-UX, the general $LD_LIBRARY_PATH variable is searched first, followed by
$SHLIB_PATH. After those variables /.udlibs## is searched, and finally the system paths. On HP-
UX, ldd should properly refer to $LD_LIBRARY_PATH. The system paths may be listed in chatr
udt output, but typically anything included under /usr/lib is listed.

Linux
Tools: ldd exe_name; objdump -a -x exe_name
Search order: $LD_LIBRARY_PATH, /.udlibs##, system paths (including paths set with
ldconfig)
LD_LIBRARY_PATH is searched first, then /.udlibs##, and then any system paths.
During the UniData installation or upgrade, ldconfig is executed to include UniData paths in the
system default paths. The UniData bin is included in /etc/ld.so.conf.d/UniData.conf and
the UniData Python lib directory is included in /etc/ld.so.conf.d/UniData_python.conf.

347
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Then ldconfig is executed to update the library cache. The UniData bin directory has been included
in the ldconfig cache for several releases now.

Solaris
Tools: ldd exe_name; ldd -s exe_name; crle -64
Search order: $LD_LIBRARY_PATH, /.udlibs##, system paths (including paths set with crle)
$LD_LIBRARY_PATH is searched first, then /.udlibs##, and then any system paths.

Parent topic: Dynamic linking in UniData

Accessing C from UniBasic (CALLC)

This section provides instructions on using UniBasic programs to interact via C (CALLC).
Many applications use C functions for purposes such as environment definition, security, or low-
level data transfers (similar to the UniBasic GET and SEND functions). UniData allows you to build a
customized u2callc library (libu2callc.so/sl) that includes C functions developed at your site.
After you build the u2callc library, you can access the C functions from within a UniBasic application
using CALLC commands.

Note: When you use CALLC, your C functions are executed by a udt process. They are not visible to
the end user at all.

• CALLC prerequisites
This section provides the steps required before linking your C functions into the UniData CALLC
library.
• CALLC requirements
This section provides information regarding the required components to take advantage of the
CALLC functionality.
• Linking C functions into the UniData CALLC library
This section provides the steps to link a C function with UniData so that it can be called by a
UniBasic program.
• File examples
These examples demonstrate the cfuncdef, base.mk, c_example.c files, and the CDEMO
basic program. The base.mk file and the cfuncdef file are platform-specific.
• Passing bstring-type data example
This example demonstrates passing bstring-type data.
• Reinitializing $UDTHOME/work files
This section provides the steps to reinitialize $UDTHOME/work files using the $UDTBIN/work
directory.
• Troubleshooting CALLC
The following table contains solutions for some common problems encountered when you
attempt to link C programs with UniData.
• Using the debug executables (udt.d)
This section provides information about the debug versions of the core UniData libraries included
in the $UDTBIN/lib.d directory and the steps to use the debug executables.
Parent topic: Dynamic Linking, CallBasic, and CALLC (UNIX only)

348
 CALLC prerequisites

CALLC prerequisites
This section provides the steps required before linking your C functions into the UniData CALLC library.
1. Complete the following steps before you create a new u2callc library:
a. Determine whether the files in the udthome/work directory have been modified.
b. Check if the cfuncdef matches the default, or if there is a libu2callc.so or
libu2callc.sl file.
For default information, see The cfuncdef file, on page 357.
c. If you want to restart from a fresh environment, refer to Reinitializing $UDTHOME/work files,
on page 361.
d. After you upgrade between major UniData versions, reinitialize the directory.
2. Copy the udthome/work directory to another directory to set up a test environment.
To call the library with the new code, set LIBPATH (AIX) or LD_LIBRARY_PATH to include the
directory where the new libu2callc.so/sl file is located.
3. Log in as root.
UniData supplies required files and templates needed to link the C program or function with
UniData. These files and templates reside in the udthome/work directory, to which only root
has read or write access. You can copy the files to another directory temporarily to work on them.
4. Provide the absolute path.
Any time you specify a path in a file, you must specify the absolute path, rather than using an
environment variable. For example, specify /usr/ud82/work, rather than $UDTHOME/work.
5. Determine if you want to use triggers.
You can call a C function from a UniBasic trigger subroutine. For more information about
maintaining data in files using UniData triggers, see the Developing UniBasic Applications guide.
6. Define the following environment variables:
▪ PATH: Include UDTBIN, as several executables are used during the make process including
genefs, gencdef, and genfunc.
▪ UDTHOME and UDTBIN: Optionally set these parameters.
▪ LIBPATH (AIX) or LD_LIBRARY_PATH: Set to include the location of libu2callc.so/sl
when testing.
For more information about setting up environment variables, see Administering UniData on
Windows and UNIX Platforms.
Parent topic: Accessing C from UniBasic (CALLC)

CALLC requirements
This section provides information regarding the required components to take advantage of the CALLC
functionality.

Warning:
Starting with UniData 8.2.0, the udt and udapi_slave executables are not replaced in the
process. Using an executable from a UniData 8.1.x or prior version will not work.

The following components are required:

▪ Development environment

349
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Your system should have a full software development kit. A base compiler is not sufficient. You
need network libraries if you are using NFA.

Note: Refer to your host operating system documentation and your hardware vendor if you
have questions about your C development environment.

▪ C functions
You need to code and compile the C functions you are linking into UniData.
▪ Function definitions and make files
When you install UniData, the files base.mk and cfuncdef are installed into the udthome/
work directory. If you modify the cfuncdef file to include definitions for your site-specific C
functions, you may need to customize the make file. On an upgrade, the cfuncdef file will not be
replaced. However, you should back up this file.
▪ UniData commands
You use the UniData system-level commands gencdef, genfunc, and genefs during the make
process.

Parent topic: Accessing C from UniBasic (CALLC)

Linking C functions into the UniData CALLC library

This section provides the steps to link a C function with UniData so that it can be called by a UniBasic
program.

Note: Before proceeding, see CALLC prerequisites, on page 349 to ensure that you have
completed all the required prerequisites.

• Write the C program

Writing the C program is the first task required in creating a C function that you will call from a
UniBasic program.
• Compile the C program
Compiling the C program is the second task required in creating a C function that you will call from
a UniBasic program.
• Add the C function to UniData
Adding the C function to UniData is the third task required in creating a C function that you will call
from a UniBasic program.
• Create and modify the makefile
Creating and modifying the makefile is the fourth task required in creating a C function that you
will call from a UniBasic program.
• Make the u2callc library
Making the u2callc library is the fifth task required in creating a C function that you will call from a
UniBasic program.
• Write, compile, and test the UniBasic program
Writing, compiling, and testing the UniBasic program is the sixth task required in creating a C
function that you will call from a UniBasic program.
• Deploy the updated library

350
 Write the C program

Deploying the updated library is the last task required in creating a C function that you will call
from a UniBasic program.
Parent topic: Accessing C from UniBasic (CALLC)

Write the C program

Writing the C program is the first task required in creating a C function that you will call from a
UniBasic program.

About this task

Access the standard compiler for your platform and operating system to write the C program. Other
compilers can be used, but are not tested or certified with UniData releases.

Note: Refer to File examples, on page 357 for the c_example.c program used in this
document.

Procedure
1. Use the following guidelines when writing C programs:
▪ Naming variables:
Avoid naming variables or functions with the prefix U and an underscore (U_), such as U_unit
and U_errout. UniData uses U_ as an identifier for variable names and functions.
▪ Passing arguments:
You cannot pass more than 22 arguments. Each argument is limited to 255 characters.
Include the bstring header to pass binary data.
▪ Returning arguments:
The maximum number of bytes allowed in a function return is 256. If you increase the size of a
variable of data type bstring, you must free the original memory assignment and reallocate it
and reassign the length to avoid a memory leak.
▪ Passing binary data:
Include the bstring header file to pass a binary string to or from a C program, especially when
that data could contain imbedded ASCII character 0 (which C interprets as a line terminator).
2. To display error messages, use the UniBasic C function U_errout.
U_errout has the same syntax as U_preprint, except the variable U_unit is replaced by 0.
U_erroutoutput goes to errout whereas U_preprint output goes to stdout.
Syntax: U_errout(0,"error message from the routine, value is
%d",value);
3. To maintain screen integrity and I/O redirection, use the UniBasic C function U_preprint instead
of the C function printf.
The U_preprint function refreshes the screen, enabling the C subroutine to properly manage
screen I/O. This function follows syntax similar to printf.
Syntax: U_preprint pattern,arg1,arg2...
For example:

extern int U_unit;

.
.

351
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

.
U_preprint(U_unit,"message from the routine, value is %d",value);

4. To end the C program, use U_done.

U_done performs various cleanup tasks, and then terminates the C program.

Note: Do not use exit to end the C program.

Parent topic: Linking C functions into the UniData CALLC library

Compile the C program

Compiling the C program is the second task required in creating a C function that you will call from a
UniBasic program.

About this task

After it is written, compile the C program to test it. If the source is included in the work directory, the
program can be recompiled during the make process.

Procedure
1. Use the UNIX/Linux cc command with the -c option to produce the object code.
2. Verify the following before you proceed to the next step:
▪ The C program does not contain the main() function.
▪ The C program compiles cleanly.
For example, enter the following commands at the UNIX/Linux command prompt:
# cc -c c_example.c
3. Copy the object code to the udthome/work directory:
$ cp c_example.o $UDTHOME/work

Note: To place the program in udthome/work directory, you must have write permissions
to that directory. For assistance, see your system administrator.

Parent topic: Linking C functions into the UniData CALLC library

Add the C function to UniData

Adding the C function to UniData is the third task required in creating a C function that you will call
from a UniBasic program.

Prerequisites
To proceed with adding the C function to UniData, the C program must reside in the udthome/work
directory.

The cfuncdef file is placed in the udthome/work directory at installation. It could contain
references to site-specific libraries.
Some earlier releases of UniData included some UniData functions in the cfuncdef file. If the person
installing UniData 7.3, or upgrading from an earlier version, chose not to overlay this file, you could

352
 Add the C function to UniData

have the wrong version. Also, if someone has previously linked C programs to UniData for CALLC, the
cfuncdef file could contain references to these programs.

Procedure
1. Check for the following required files in the udthome/work directory:
▪ The makefile (c_example.mk in this example)
▪ The function definition file (cfuncdef)
▪ C functions for UniData itself (funchead.o interfunc.o callcf.o and
efs_init.o)
2. Verify that the cfuncdef file is free of references to other C programs.
3. Modify or create the cfuncdef file. If you are creating the cfuncdef file, start with a default
cfuncdef file.
See File examples, on page 357, if needed.
The file should contain the following three lines:

$$FUN Put the C function definition here.

$$OBJ Put the object file here.
$$LIB Put the library path here if the C function is not
stored in udtlib.

The following example shows a version of the cfuncdef file that has been modified to set up the
function c_example. The following steps refer to this example.

/* this is a test for adding a C function to the*/

/* Runtime version of UniData. */
/* C function declaration format:
function-name:return-type:number-of-argument:arg1,arg2,...argn */
$$FUN /* beginning of C function */
c_example:string:1:string
$$OBJ /* object files or .o file comes here */
/usr/ud82/work/c_example.o
$$LIB /* library comes here */

4. Add the function to cfuncdef.

The function definition line follows $$FUN.
Syntax: fun_name:rtn_data_type:num_arg:arg_data_type
A colon separates each element, and a comma separates multiple arguments. You can enter more
than one function definition, each on a separate line.
The following table lists the function definition arguments.

Argument Description Value in example

fun_name The name of the C program as c_example
it will be called from UniBasic
programs.
rtn_data_type The data type of the return string
value.
num_arg The number of arguments. 1
arg_data_type The data type of the string
arguments.

353
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

The following table lists valid data types for arguments and return values.

Data Type Description

int An integer. A 32-bit signed long word.
short A 16-bit signed long word.
long A 32-bit signed long word (same as int).
double A 64-bit floating point value.
float A 32-bit floating point value.
char A signed byte.
string A pointer to a character string terminated by NULL (0) in a 34 KB buffer.
The buffer size cannot be changed.
Although memory reallocation is not supported, you can allocate
memory for the variable in a UniBasic program before passing it in the
parameter to the C program. For example:

...
var = SPACE(64000)
CALLC(var...)
The variable now has been allocated a size of 64 KB.

bstring A pointer to a structure (struct) in a buffer that is a minimum of 34 KB in

size. You can reallocate this buffer. Also, you can pass data contain the
NULL (0) character by using bstring. Defined as:

typedef struct (
char *str;
int len
} bstring;

To prevent a memory leak, you must free the original buffer assignment
before reallocating it. If the string is changed, the length must also be
reassigned.
pointer A 32-bit signed long word.
5. Add the object code path and file name.
Enter the object code path and file name on the line that follows $$OBJ. You can put it in any
directory as long as you specify the absolute path here.
6. Add the library path to cfuncdef.
If your function does not reside in udtlib, enter the library path on the line that follows $$LIB,
preceded by -L. Do not use the environment variable (udtlib) in the path name, but instead list the
absolute path. The function in the example does not link any alternate libraries.
Parent topic: Linking C functions into the UniData CALLC library

Create and modify the makefile

Creating and modifying the makefile is the fourth task required in creating a C function that you will
call from a UniBasic program.
1. In udthome/work copy the base.mk file to another filename. For example, c_example.mk.
The base.mk file will be replaced on upgrades and may change at future UniData releases.
# cd $UDTHOME/work
# cp -p base.mk c_example.mk

354
 Make the u2callc library

2. Include the object files (for example, c_example.o) into the UDT_OBJS and NFASVR_OBJS
definitions in the makefile.

Note: The object files referenced in the following example may not match your release, and
are provided for illustrative purposes only.

# vi c_example.mk
Change these lines:
UDT_OBJS = funchead_udt.o interfunc_udt.o callcf_udt.o efs_init_udt.o
NFASVR_OBJS = funchead_nfasvr.o interfunc_nfasvr.o callcf_nfasvr.o
efs_init_nfasvr.o
To include your object code at the end of the lines:
UDT_OBJS = funchead_udt.o interfunc_udt.o callcf_udt.o efs_init_udt.o
c_example.o
NFASVR_OBJS = funchead_nfasvr.o interfunc_nfasvr.o callcf_nfasvr.o
efs_init_nfasvr.o c_example.o
Parent topic: Linking C functions into the UniData CALLC library

Make the u2callc library

Making the u2callc library is the fifth task required in creating a C function that you will call from a
UniBasic program.
1. Use the make command to compile the libu2callc.so/sl library.
This will put the u2callc in the local directory. It will not replace the file in $UDTBIN
automatically.
2. If you are not in $UDTBIN, remove any existing library first:
# rm libu2callc.*

Note: There is no clean option included in the current base.mk files. However, if you modify
the makefile for your site, you should add a clean (or similar) option.

3. Make the libu2callc.so/sl file:

# make -f c_example.mk all
Parent topic: Linking C functions into the UniData CALLC library

Write, compile, and test the UniBasic program

Writing, compiling, and testing the UniBasic program is the sixth task required in creating a C function
that you will call from a UniBasic program.

Prerequisites
With the dynamic libraries in UniData 8.2, you will want to set the environment variable
LD_LIBRARY_PATH (on HP, Sun, or Linux) or LIBPATH (on AIX), and run a report that the
libu2callc.so/sl file is pointing to the $UDTHOME/work directory.
1. Set the environment variable LD_LIBRARY_PATH or LIBPATH, to include the $UDTHOME/work
directory (or the directory where you created the libu2callc.so/sl file):

355
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

(Non AIX): # LD_LIBRARY_PATH=$UDTHOME/work:$LD_LIBRARY_PATH; export

LD_LIBRARY_PATH
(AIX): # LIBPATH=$UDTHOME/work:$LIBPATH;export LIBPATH
2. Start an OS shell and run ldd $UDTBIN/udt.
This provides a report that the libu2callc.so/sl file is pointing to the $UDTHOME/work
directory.
3. When the path is confirmed in Step 2, cd to your UniData account and execute udt.

Procedure
1. Write the UniBasic program that uses the UniBasic CALLC function to call the C function.
In the following example, the user is prompted for the environment variable name, call the C
program c_example you created, then return the results:
PROMPT ''
PRINT 'Enter an environment variable (such as PATH or TERM): ':
INPUT VARNAME
EVAL = CALLC c_example(VARNAME)
PRINT 'Value of ':VARNAME:' is ':EVAL
STOP
END
2. Enter the BASIC command at the ECL prompt to compile the UniBasic program.
:BASIC BP CDEMO
For instructions about compiling and cataloging UniBasic programs, see creating and running a
program instructions in the Developing UniBasic Applications guide.
3. Execute the UniBasic program using the UniData ECL RUN command to test the program.
The following example demonstrates running the UniBasic program CDEMO:
:RUN BP CDEMO
4. Enter an environment variable name (such as PATH or TERM).
To continue the example, the user enters TERM.
The program calls the C function. The C function determines the value of the environmental
variable and returns it to the UniBasic program, which displays the value. For example:
Value of TERM is vt100
Parent topic: Linking C functions into the UniData CALLC library

Deploy the updated library

Deploying the updated library is the last task required in creating a C function that you will call from a
UniBasic program.
1. When testing is completed, copy the libu2callc.so/sl file to the $UDTBIN directory to
make the file available to all users.
On HP, the file will end with a .sl extension.
# cd $UDTBIN
# cp -p libu2callc.so libu2callc.so.orig
# cp -p libu2callc_nfasvr.so libu2callc_nfasvr.so.orig
# cp $UDTHOME/work/libu2callc* $UDTBIN

356
 File examples

Tip: If users are logged in, the file may be in use. If so, log users out and copy the file in place
later. Alternatively, with dynamic libraries, if the cp command worked without error, the next
time users log in, the updated library will be used. For any unirpc connections, you should
restart the Unirpc daemon to confirm the updated library is used.

2. Restore the settings for the LD_LIBRARY_PATH or LIBPATH variables to confirm the results
when in production mode (that is, when using $UDTBIN).
Parent topic: Linking C functions into the UniData CALLC library

File examples
These examples demonstrate the cfuncdef, base.mk, c_example.c files, and the CDEMO basic
program. The base.mk file and the cfuncdef file are platform-specific.

The cfuncdef file

This is the default file for $UDTHOME/work/cfuncdef. If modified, the modifications will remain
after an upgrade. As of UniData 8.2.0, the cfuncdef_user file is no longer used.

/* this is a test for adding C function to the RUN Machine */

/* comment lines come here. */
/* C function declaration format:
function-name:return-type:number-of-argument:arg1,arg2,...,argn
*/
$$FUN /* beginning of C function */
$$OBJ /* *.o come here */
$$LIB /* library comes here */

The base.mk file

Refer to the $UDTHOME/work/base.mk or $UDTBIN/work/base.mk for the contents of this file.
The contents can change at any UniData release and are platform specific.

The c_example.c file

#include <stdio.h>
char *c_example(envar)
char *envar;
{
char *getenv();
static char buf[100];
char *pathlist;
sprintf (buf,"%s",getenv(envar));
return(buf); /* return string to UniData */
}

CDEMO basic program

PROMPT ''
PRINT 'Enter an environment variable (such as PATH or TERM): ':
INPUT VARNAME
EVAL = CALLC c_example(VARNAME)
PRINT 'Value of ':VARNAME:' is ':EVAL

357
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

STOP
END

Parent topic: Accessing C from UniBasic (CALLC)

Passing bstring-type data example

This example demonstrates passing bstring-type data.
Notice that the original bstring passed by the UniBasic program is shorter than the minimum buffer
size of 34 KB. Therefore, UniData assigns a 34-KB buffer to it.
Within the C program, however, the size of the variable passed by the UniBasic program is changed.
To avoid a memory leak resulting from assigning a larger buffer, the C program checks the size of the
string to be passed back, frees up the original 34-KB allocation, and reassigns a buffer of adequate
size.
The following UniBasic program prompts the user for the length of buffer to assign (see length in the
INPUT statement), then passes this length to the C program (see length in the CALLC statement):

PROGRAM trycallc
* Input a length to indicate that the length of the 2nd IO string
* and bstring will be changed in C routine.
PROMPT ""
CRT "Input length of new IO strings: ":;INPUT length
instr = "THE FIRST INPUT STRING"
iostr1 = "THE FIRST IO STRING"
iostr2 = "THE SECOND IO STRING"
bstring = "THE BSTRING"
CRT "Calling str_arg() function"
CALLC str_arg(length, instr, iostr1, iostr2, bstring)
CRT
CRT "After str_arg() function was called"
CRT
CRT "The 1st input string >> ":instr
CRT "The 1st IO string >> ":iostr1
CRT "The length of the 2nd IO string >> ":LEN(iostr2)
CRT "The length of the bstring is >> ":LEN(bstring)
CRT "The 1st 20 char of the 2nd string >> ":iostr2[1,20]
CRT "The 1st 20 char of the bstring is >> ":bstring[1,20]

The following C program is called by the CALLC statement in the preceding UniBasic program. The
buffer size assigned to the arguments IOstr2 and bstring are tested. If either is greater than 34KB, the
memory allocation for that variable must be freed and reallocated. Because IOstr2 is 1KB in size, the
memory allocation is freed and reallocated before passing it to the UniBasic program.

Note: The program name is str_arg.c.

#include <stdio.h>
#include <string.h>
#include "/usr/ud82/include/callc_bstr.h"
#define ONEK 1024
extern int U_unit;
int
str_arg(len, InStr, IOstr1, IOstr2, Bstr)
int len; /*length of the 2nd IO string and Bstring after updating */
char *InStr; /* an input string, read only */

358
 Passing bstring-type data example

char *IOstr1; /* an IO string, length < 34 KB */

char *IOstr2; /* an IO string, length > 34 KB */
bstring *Bstr; /* an IO bstring struct pointer */
{
char buf1[30], buf2[30];
int memsize;
/* Input Strings */
U_preprint(U_unit, "The 1st input string (%s)\n", InStr);
U_preprint(U_unit, "The 1st IO string (%s)\n", IOstr1);
U_preprint(U_unit, "The 2nd IO string (%s)\n", IOstr2);
U_preprint(U_unit, "The binary string (%s)\n", Bstr->str);
U_preprint(U_unit, "Length of the bstring (%d)\n", Bstr->len);

/* For an IO string, the memory size is either 34 KB

* or the length of the original string in the basic
* program. Memory reallocation is not supported
* for string-type parameters.
* Allocate memory in the UniBasic program. (Assign
* a long string to the variable as
* a work around if the size is known.)
*/

strcpy(IOstr1, "The 1st IO string is changed");

len *= ONEK;
memsize = strlen(IOstr2);
memsize = (memsize > 34*ONEK ? memsize : 34*ONEK);
if ( len < memsize ) {
memset(IOstr2, 'a', len);
memcpy(IOstr2, "len < 34K ", 10);
IOstr2[len] = '\0';
}
else {
/* no memory reallocation is allowed here */
memset(IOstr2, 'b', 100);
IOstr2[30*ONEK] = '\0';
memcpy(IOstr2, "len > 34K ", 10);
}
/* For bstring data, the initial memory size is the
* same as for string data, and memory reallocation
* is supported. To avoid a memory leak, the buffer
* size for the bstring needs to be freed
* before allocating a larger buffer.
*/

memsize = Bstr->len;
memsize = (memsize > 34*ONEK ? memsize : 34*ONEK);
if ( len < memsize ) {
Bstr->len = len;
memset(Bstr->str, 'c', len);
memcpy(Bstr->str, "len < 34K ", 10);
}
else {
/* memory re-allocation is allowed here */
free(Bstr->str);
Bstr->str = malloc(len);
Bstr->len = len;
memset(Bstr->str, 'd', len);
memcpy(Bstr->str, "len > 34K ", 10);
}

/* print out changed strings */

memcpy(buf1, IOstr2, 20);

359
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

memcpy(buf2, Bstr->str, 20);

buf1[20] = buf2[20] = '\0';
U_preprint(U_unit, "\nAfter modification:\n");
U_preprint(U_unit, "The 1st IO string (%s)\n", IOstr1);
U_preprint(U_unit, "Length of the 2nd IO string (%d)\n",strlen(IOstr2));
U_preprint(U_unit, "Length of the bstring (%d)\n", Bstr->len);
U_preprint(U_unit, "The 1st 20 char of IO str2 (%s)\n", buf1);
U_preprint(U_unit, "The 1st 20 char of Bstring (%s)\n", buf2);
return 0;
}

The following cfuncdef file contains the function and argument definitions needed to link the
preceding C program with UniData:

/* comment lines come here. */

/* C function declaration format:
* function-name:return-type:number-of-argument:arg1,arg2,...,argn
*/
$$FUN /* beginning of C function */
str_arg:int:5:int,string,string,string,bstring
$$OBJ /* *.o come here */
str_arg.o
$$LIB /* library comes here

The following shows the output produced by executing the UniBasic program trycallc after linking
the C program str_arg with UniData. Notice that the user responded to the prompt of length for the
output string with a number less than 34. This will require that the memory allocation for IOstr2 be
freed and reallocated to pass back a variable of 1 KB in size.

:RUN BP trycallc
Input length of new IO strings: 30
Calling str_arg() function
The 1st input string (THE FIRST INPUT STRING)
The 1st IO string (THE FIRST IO STRING)
The 2nd IO string (THE SECOND IO STRING)
The binary string (THE BSTRING)
Length of the bstring (11)

After modification:
The 1st IO string (The 1st IO string is changed)
Length of the 2nd IO string (30720)
Length of the bstring (30720)
The 1st 20 char of IO str2 (len < 34K aaaaaaaaaa)
The 1st 20 char of Bstring (len < 34K cccccccccc)

After str_arg() function was called

The 1st input string >> THE FIRST INPUT STRING

The 1st IO string >> The 1st IO string is changed
The length of the 2nd IO string >> 30720
The length of the bstring is >> 30720
The 1st 20 char of the 2nd string >> len < 34K aaaaaaaaaa
The 1st 20 char of the bstring is >> len < 34K cccccccccc
:

Parent topic: Accessing C from UniBasic (CALLC)

360
 Reinitializing $UDTHOME/work files

Reinitializing $UDTHOME/work files

This section provides the steps to reinitialize $UDTHOME/work files using the $UDTBIN/work
directory.

Prerequisites
If the $UDTBIN/work directory is not available, at a minimum, restore the cfuncdef file to the
contents noted. The base.mk file in the directory should work for your system. Copy the base.mk
file to another file before modifying it.

Procedure
1. Back up the current directory as follows:
cd $UDTHOME
mv work work.orig
2. Copy the backup directory from the $UDTBIN directory as follows:
cp -R $UDTBIN/work $UDTHOME/work
cd $UDTHOME/work
3. Modify the $UDTHOME/work/base.mk.
4. Change the libpath variable to reference the fully qualified value of $UDTHOME/lib. It will not
work with a value of $UDTHOME/lib.
The line will look similar to: libpath = -L/usr/ud82/lib/

Note: When doing an install or upgrade, this step is normally handled.

5. Remove the interfunc_udt.c file.

rm -f $UDTHOME/work/interfunc_udt.c
Parent topic: Accessing C from UniBasic (CALLC)

Troubleshooting CALLC
The following table contains solutions for some common problems encountered when you attempt to
link C programs with UniData.

Problem Solution
When executing udt, the following This happens if the library noted cannot be
message displays: Dependent module found in the dynamic library variables, or via the
libunidata.so could not be loaded. /.udlibs## symbolic links.
Re-run the relink.udlibs syntax (previously
noted in the section The /.udlibs## definition) to
resolve this issue.
When executing the UniBasic program, the The first libu2callc.so/sl file referenced via
following message displays: In BP/_CDEMO the dynamic library variables, or /.udlibs##,
at line 4 C function 'c_example' does not contain the function you are attempting
not found. to use.
See the search order for your platform (previously
noted in this chapter) and update the correct file.

361
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Problem Solution
When running the UniBasic program, the This happens if the UDT_OBJS or NFASVR_OBJS
following message displays: udt: symbol reference in the make file does not include the
lookup error: /disk1/ud82/work/ object file for your function.
libu2callc.so: undefined symbol:
Update the make file and remake the library.
c_example

/usr/ccs/bin/ld:
Add the full path to the C program in the
Can't find library for -lapidummy cfuncdef file that follows $$OBJ.
*** Error exit code 1 Check the libpath line in your makefile (the one
you created by copying base.mk). It should list
the absolute path to the UniData libraries.
After running the make command, it returns: Remove the libu2callc.so/sl file, then re-
‘libu2callc.so’ is up to date. run the make command. Do not remove this file
from $UDTBIN, as it will prevent new udt sessions
from starting.
The make command aborts with an error such References to libraries are incorrect.
as: unsatisfied symbol: str_arg,
Check the cfuncdef file. Enter the full path to
where str_arg is the object file for your C
the object file for the C program after the line that
program.
contains $$OBJ. Check the ‘libpath’ variable in
your makefile.
When you try to copy your C object file into You do not have permission to write to the given
$UDTHOME/work, you get: directory.
cp: cannot create /disk1/ud82/ Either log in as root or open up permissions on the
work/str_arg.o: Permission denied directory.
When you execute the UniBasic program that To prevent a memory leak, you must free the
calls the C program you linked to UniData, a original buffer assignment in the C program before
memory leak results. reallocating it. If the string is changed, the length
must also be reassigned. For more information,
see Passing bstring-type data example.
You receive the error: cp: /disk1/ud82/ The file is in use.
bin/libu2callc.so: cannot write:
Log users out, and then copy and move the file
Text file busy
into place.
When you log in as root, UniData cannot find The setting for the UNIX environment variable
udthome, or other files or directories. PATH is lost.
Reset your path as it is in your .login or
.profile file (if you have one), or see your
system administrator or the UNIX man pages for
instructions on setting PATH.
Reset the environment variables udthome and
udtbin. For instructions, see Administering
UniData on Windows and UNIX Platforms or the
UNIX man pages.

Parent topic: Accessing C from UniBasic (CALLC)

362
 Using the debug executables (udt.d)

Using the debug executables (udt.d)

This section provides information about the debug versions of the core UniData libraries included in
the $UDTBIN/lib.d directory and the steps to use the debug executables.

About this task

With the change to dynamic libraries at UniData 8.2.0, the UniData libraries are dynamically linked.
Instead of the library information being stored in udt, it is included with libunidata.so (or .sl
on HP) and other files. With dynamic linking, only the library names are stored in the executables. For
this reason, the debug versions of the core UniData libraries are included in the $UDTBIN/lib.d
directory.
By default the libraries in UniData bin are referenced in one of the following ways: /.udlibs82,
$LD_LIBRARY_PATH, $LIBPATH (AIX), $SHLIB_PATH (HP), ldconfig (Linux).

1. Use the platform-specific dynamic library env variable before calling a debug executable.

Note:
For AIX, use LIBPATH. For HP, Sun, and Linux, use LD_LIBRARY_PATH.

2. Set LD_LIBRARY_PATH to include the $UDTBIN/lib.d directory:

LD_LIBRARY_PATH=$UDTBIN/lib.d:$LD_LIBRARY_PATH;export
LD_LIBRARY_PATH
3. If you make the libu2callc libraries and they are not in $UDTBIN, then add them to the front of
the variable:
LD_LIBRARY_PATH=$UDTHOME/work:$LD_LIBRARY_PATH;export
LD_LIBRARY_PATH
4. Execute udt.d or another debug executable.

Note:
▪ On AIX, you also may want to set LIBPATH.
▪ On AIX, enable full core files and unique core file naming.
▪ On HP, you also may want to set SHLIB_PATH.
▪ Remember to have ulimit -c set high enough to generate a core file.

5. Clear or reset any variables set to resume normal optimized calls.

6. Use the ldd command to confirm that the proper libraries are referenced.
Example:
# ldd $UDTBIN/udt
linux-vdso.so.1 => (0x00007fffd0a7e000)
libunidata.so => /.udlibs82/libunidata.so (0x00007fb7c9b65000)
libu2callc.so => /.udlibs82/libu2callc.so (0x00007fb7c9962000)
libodbc.so => /.udlibs82/libodbc.so (0x00007fb7c9760000)
libncurses.so.5 => /lib64/libncurses.so.5 (0x00007fb7c953d000)
Parent topic: Accessing C from UniBasic (CALLC)

363
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Accessing UniData from a C program (CallBasic)

The CallBasic application programming interface (API) allows you to access a UniData database by
calling UniBasic subroutines from a C program.
The CallBasic API is particularly useful for applications such as automated processes that gather data,
and then write the data into a UniData database. The main body of the application may be written
in C, and the application uses a UniBasic subroutine, called through CallBasic, to write the data into
UniData hashed files in the 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:
• How CallBasic works
The CallBasic API includes three functions:
• C program example
The following C program, called sample.c, illustrates the components required for CallBasic:
• UniBasic subroutine example
The following UniBasic subroutine, called EXAMPLE, is a simplified routine showing the
requirements for CallBasic.
• Steps for CallBasic
Complete all of the following tasks, in the order presented, to access UniData from a C program
with CallBasic.
Parent topic: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Requirements
The components required to use the CallBasic API are:
▪ Development environment—Your system should have a full software development kit. (A base
compiler is not sufficient). You need network libraries if you are using NFA.
Consult your host operating system documentation and your hardware vendor if you have
questions about your C development environment.
▪ C programs—You need to code and compile the C application that will call UniBasic.
▪ Function definitions and make files—When you install UniData, the file callbas.mk is installed
into the directory udthome/work. Use this makefile as a template to build your application, with
UniData linked into it.
The examples in this section are developed using udthome/work as a workspace. You can create a
separate workspace by creating a new directory and copying all the files from udthome/work into it.
Then complete the steps in your own workspace.

Parent topic: Accessing UniData from a C program (CallBasic)

364
 How CallBasic works

How CallBasic works

The CallBasic API includes three functions:
▪ udtcallbasic_init( )
This function initializes UniData and CallBasic. It serves the purpose of opening a “UniData
session” for your C application. Your C program must execute this function once and only once.
▪ U_callbas( )
This function calls a UniBasic subroutine, passing arguments, and places the results in a pointer to
the return value. You may execute this function numerous times in your C application, each time
you want to call a UniBasic subroutine.
▪ udtcallbasic_done( )
This function clears all UniData-related temporary files and other resources, and ends the interface
between the C application and UniData. You must execute this function once in your C application.
You must also include this function in any error exits in your application that may be taken after
udtcallbasic_init().
See Code, compile, and catalog the UniBasic subroutine, on page 369 for a detailed description of
the CallBasic functions and their requirements.

Parent topic: Accessing UniData from a C program (CallBasic)

C program example
The following C program, called sample.c, illustrates the components required for CallBasic:

#include <stdio.h>
#include <setjmp.h>
#include "/usr/ud82/include/share.h"

main()
{
/* end of modified code */

/* Declare variables */
char *rtn;
char arg0[BUFSIZ];
char arg1[BUFSIZ];
char *args[2];
int sts;

/* Initialize the UniData environment */

/* Set up an error handler to shut down gracefully */

int jmpret, sat;

U_SET_JMP(jmpret, sat);
if (!jmpret) {
udtcallbasic_done(1);
exit(-1);
}
udtcallbasic_init(0, 0);

/* Assign arguments for the UniBasic routine */

strcpy(arg0, "Plants");
strcpy(arg1, "Animals");

365
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

args[0] = arg0;
args[1] = arg1;

/* Call the subroutine */

sts = U_callbas(&rtn, "EXAMPLE", 2, args);
if (sts == 0){
free(rtn);
}
printf("status: %d\n", sts);
/* Close everything properly */
udtcallbasic_done(sts);
}

Notice the following points about sample.c:

• Header files
You must include setjmp.h for the error handler, and you must include the UniData header file /
usr/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 taken
before the C program exits, whether normally or abnormally.
• Initialize CallBasic
This statement initializes CallBasic, effectively starting a udt session for your C program:
• Call a UniBasic subroutine
In this program, you call the subroutine and assign the return to a variable.
• Freeing resources
Each U_callbas( ) execution allocates memory. Remember to free this after conclusion of the
subroutine:
• Ending CallBasic
This statement ends CallBasic and is the last step in the C program.
Parent topic: Accessing UniData from a C program (CallBasic)

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.
Parent topic: C program example

Error handler
Remember that the CallBasic exit routine, udtcallbas_done( ), must be the last action taken
before the C program exits, whether normally or abnormally.
Parent topic: C program example

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

366
 Call a UniBasic subroutine

If you initialize CallBasic more than one time, you will encounter errors and your program may dump
core.

Parent topic: C program example

Call a UniBasic subroutine

In this program, you call the subroutine and assign the return to a variable.
/* Call the subroutine */
sts = U_callbas(&rtn, "EXAMPLE", 2, args);
Remember, you can call more than one UniBasic subroutine, as long as you do so between initializing
and closing CallBasic. Use the U_callbas( ) function.

Parent topic: C program example

Freeing resources
Each U_callbas( ) execution allocates memory. Remember to free this after conclusion of the
subroutine:
if (sts == 0){
free(rtn);
Notice that you free the memory if the function completes successfully. UniData frees the memory if
the function fails.

Parent topic: C program example

Ending CallBasic
This statement ends CallBasic and is the last step in the C program.
/* Close everything properly */
udtcallbasic_done(sts);
Remember that this function closes the UniData session for the C program, closing all UniData
temporary files, and releasing all resources held by UniData for this C program.
If you do not exit UniData cleanly, you may lose consistency of data and you may damage files.

Parent topic: C program example

UniBasic subroutine example

The following UniBasic subroutine, called EXAMPLE, is a simplified routine showing the requirements
for CallBasic.

SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)
PRINT "THE FIRST ARG IS ":ARG1
PRINT "THE SECOND ARG IS ":ARG2
RETNVAL="RETURN"
RETURN
END

367
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Notice the following points about the UniBasic subroutine.

Arguments
The arguments for the UniBasic subroutine match what is sent from the C program. The following is
the call to the subroutine:
sts = U_callbas(&rtn, "EXAMPLE", 2, args);
This is the first line of the subroutine:
SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)

Additional information
You must create, compile, and catalog the UniBasic subroutine in a UniData account. The routine may
be globally, directly, or locally cataloged. However, if you catalog the routine directly or locally, you
must execute the C program from the UniData account where the subroutine is cataloged. Regardless
of how you catalog the UniBasic subroutine, you must execute the C program from a valid UniData
account.

Parent topic: Accessing UniData from a C program (CallBasic)

Steps for CallBasic

Complete all of the following tasks, in the order presented, to access UniData from a C program with
CallBasic.
• Code and compile the C program
Coding and compiling the C program is the first task required to access UniData from a C program
with CallBasic.
• Code, compile, and catalog the UniBasic subroutine
Coding, compiling, and cataloging the UniBasic subroutine is the second task required to access
UniData from a C program with CallBasic.
• Make a copy of the makefile template
Making a copy of the makefile template is the third task required to access UniData from a C
program with CallBasic.
• Edit the makefile
Editing the makefile is the fourth task required to access UniData from a C program with
CallBasic.
• Build the new executable
Building the new executable is the fifth task required to access UniData from a C program with
CallBasic.
• Produce a stripped executable
Producing a stripped executable is the final task (and is optional) when accessing UniData from a C
program with CallBasic.
Parent topic: Accessing UniData from a C program (CallBasic)

Code and compile the C program

Coding and compiling the C program is the first task required to access UniData from a C program with
CallBasic.

368
 Code, compile, and catalog the UniBasic subroutine

About this task

C compilers differ between UNIX versions. For instance, some C compilers require ANSI-compliant
syntax, and others do not. Consult the documentation supplied with your C compiler for specific
coding requirements for your system.

Procedure
1. Locate the C program in the same directory as the makefile.
By default, this is udthome/work.
2. Use the cc -c command to compile the C program in your workspace.
The cc -c command produces a .o file in the same directory.
The following example shows how to compile the sample program sample.c.

# ls -l sample*
-rw-rw-rw- 1 root sys 745 Jun 11 11:43 sample.c
# cc -c sample.c
# ls -l sample*
-rw-rw-rw- 1 root sys 745 Jun 11 11:43 sample.c
-rw-rw-rw- 1 root sys 1624 Jun 11 11:45 sample.o
#
See C program example, on page 365 for a listing of sample.c.
Parent topic: Steps for CallBasic

Code, compile, and catalog the UniBasic subroutine

Coding, compiling, and cataloging the UniBasic subroutine is the second task required to access
UniData from a C program with CallBasic.
1. Code and compile the UniBasic subroutine.

Note: A transaction started in a UniBasic subroutine invoked by a C program can continue

into another subroutine called by the same C program:

udtcallbasic_init( )
U_callbas(subroutineA) * this subroutine starts a transaction
U_callbas(subroutineB) * this subroutine commits the transaction
udtcallbasic_done( )

However, a transaction started in a UniBasic program executed from ECL must complete
before the process returns to ECL.

a. Start UniData – udtcallbasic_init.

Your C program must execute this function once and only once. The C function
udtcallbasic_init initializes the UniData environment, starting a udt process to
execute the CallBasic subroutine call.
The syntax of this function is:

udtcallbasic_init(value1, value2)
int — value1;
int — value2;

You must initialize the UniData environment with udtcallbasic_init before calling a
UniBasic subroutine.

369
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

Warning: You can call udtcallbasic_init only once in your program. If you attempt
to call it more than once, your program could cause a core dump.

The following table describes each parameter of the syntax.

Parameter Description
value1 Names the type of UniData process that will
be started. The default is 0.
Values for each parameter are in the
share.h file in the /usr/ud82/include
directory.
Valid parameters include the following:
01 – U_PHANTOM – This parameter behaves
like the ECL PHANTOM command.
0100 – U_REDIRECT – This parameter
overrides the terminal attributes that
UniData set by default. It sends UniData
output to a file instead of the terminal
screen.
0400 – U_UDT_SERVER – This parameter sets
a flag that, when a fatal error occurs, returns
control to the calling UniBasic program
rather than aborting (same as UDT.OPTIONS
41).
When UDT.OPTION 41 is used, errors are
returned in EXECUTE instead of longjmp.
value2 Enter one of the following values to clear
(or not clear) the screen when CALLBASIC is
initialized:
0 – Do not clear the screen.
1 – Clear the screen.
b. Call the UniBasic subroutine – U_callbas.
This function calls a UniBasic subroutine, passes arguments, and sets a pointer to the return
value. You can execute this function numerous times in your C application, each time you
want to call a UniBasic subroutine.
The syntax of this function is:

int U_callbas (rtn, progname, argc, argv)

The following table describes each parameter of the syntax.

370
 Code, compile, and catalog the UniBasic subroutine

Parameter Data type Description

rtn char The address of the pointer to the value returned
from the UniBasic subroutine. You cannot use this
argument to pass anything to the subroutine. The
return values include the following:
0 – The function executed successfully.
-1 – A UniBasic program error occurred in the RUN
process, you are out of memory, or the system is
performing a CHAIN.
-2 – A fatal error occurred or a STOP was encountered
in a UniBasic program.
progname char The pointer to the name of the subroutine.
argc int The number of arguments passed to the subroutine.
argv char The address of an array of pointers to arguments. You
cannot use these arguments to pass anything to the
subroutine.

Note: UniData allocates memory every time you execute U_callbas. In the C program,
you must free the storage space pointed to by the first argument or the memory will
be unavailable to the system. However, you must free memory only if the function
completes successfully.

c. Close files and UniData – udtcallbasic_done.

This function clears all UniData-related temporary files and other resources, and ends the
interface between the C application and UniData. You must execute this function once in
your C application. You must also include this function in any error exits in your application
that could be taken after udtcallbasic_init.
The syntax of this function is:

udtcallbasic_done(status)
int status;

status is returned, but it is currently not interpreted.

2. Catalog the UniBasic subroutine globally, locally, or directly.
The following example shows compiling and directly cataloging the sample subroutine EXAMPLE
in the UniData demo account:
:AE BP EXAMPLE
Top of "EXAMPLE" in "BP", 6 lines, 128 characters.
*--: P
001: SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)
002: PRINT "THE FIRST ARG IS ":ARG1
003: PRINT "THE SECOND ARG IS ":ARG2
004: RETNVAL="RETURN"
005: RETURN
006: END
Bottom.
*--: FIBC
Filed "EXAMPLE" in file "BP" unchanged.
Compiling Unibasic: BP/EXAMPLE in mode 'u'.
compilation finished
:

371
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

3. Before proceeding, thoroughly test both your C program and your UniBasic subroutine.
Parent topic: Steps for CallBasic

Make a copy of the makefile template

Making a copy of the makefile template is the third task required to access UniData from a C
program with CallBasic.

About this task

The template is called callbas.mk and is released by default into udthome/work.
The template for your makefile is platform and release dependent. Always use callbas.mk on
your system as a starting point.

Caution: Do not use the examples in this document. They are for reference only.

Procedure
1. Copy the template.
2. Name the copy in a way that relates it to your C program.
Example:
# ls callbas*
callbas.mk
# cp callbas.mk sample.mk
#
Parent topic: Steps for CallBasic

Edit the makefile

Editing the makefile is the fourth task required to access UniData from a C program with CallBasic.

Prerequisites
Access vi or any UNIX text editor to edit the copy you created in Make a copy of the makefile template,
on page 372. The purpose is to produce a makefile that will build your C program, with udt linked
into it, forming an executable whose name you choose. The following additional steps are required so
that the make is successful.

Procedure
1. Correct the following references for UniData libraries:
▪ Locate and change a line in your make file that resembles the following:
libpath = -L/disk3/srcman/alpha/ud_82_020715_4088/bin/lib
Notice that the path does not match your production system. It contains a UniData internal
naming convention.
Change this to reflect the actual location of your UniData libraries. The following example uses
the default location:
libpath = -L/usr/ud82/lib
▪ Locate and delete from your make file a line that resembles the following:
libpath = -L$$UDTLIB

372
 Build the new executable

2. Locate the following line and modify the name of your compiled C routine.
NEWOBJS = callbas_sample.o
This is a default object name released with the template. Change this to match your C routine, as
shown for the following sample program:
NEWOBJS = sample.o
This change allows your C routine to be included in the make.
3. Locate the following line and modify the makefile to name the resulting executable.
callbas:
$(OBJS)
The default name callbas is released with the makefile. Substitute the name you want as
shown in the following example:
sample: $(NEWOBJS) $(OBJS)
The UNIX make utility will build a new executable linking the UniData libraries with your compiled
C routine.

Note: As shown in the examples, it is simplest to maintain naming consistency between your
C program, its .o file, and your new executable.

4. Locate the following line and modify the all option to reference your executable:
all : libu2callc.so callbas
To include your executable:
all : libu2callc.so sample
5. Check your work.
Make certain that you have replaced all occurrences of callbas with the name of your program.
Parent topic: Steps for CallBasic

Build the new executable

Building the new executable is the fifth task required to access UniData from a C program with
CallBasic.

About this task

The executable resulting from this task will be significantly larger than your compiled C program
because this task links in the UniData kernel.

Procedure
1. Do the following to estimate the total size:
▪ Record the size (in bytes) of udtbin/udt.
▪ Add the size (in bytes) of your compiled C program (sample.o in the examples).
▪ Add about 20% overhead, since the executable will not be stripped.
2. Make sure you have enough space available in your work area.
3. Run the rm -f interfunc_udt.c command to rebuild the file during the make process.
4. Use the UNIX make utility, as shown in the following screen:
# make -f sample.mk

373
Chapter 26: Dynamic Linking, CallBasic, and CALLC (UNIX only)

cc -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 sample executable in your working directory.

Note: You do not need to log on as root to execute the make utility. You do need to have write
permissions at the directory level in your work area.
Refer to your host operating system documentation for information about the make utility.

Parent topic: Steps for CallBasic

Produce a stripped executable

Producing a stripped executable is the final task (and is optional) when accessing UniData from a C
program with CallBasic.

About this task

The make utility produces an executable that contains symbol table information that is helpful if you
are using a debugging tool to research a problem. However, including this information increases the
size of the executable, and may result in a noticeably slower response for users.

Procedure
1. Test and debug your executable.
Consult your host operating system documentation for information about debugging and symbol
tables.
2. Use the UNIX strip command to remove the symbol table information.
Using the strip command decreases size and improves performance.
The following screen shows the results of stripping the sample executable:
# ls -l sample
-rwxrwxrwx 1 root sys 12657828 Jun 12 12:18 sample
# strip sample
# ls -l sample
-rwxrwxrwx 1 root sys 4423680 Jun 12 12:57 sample
#
Parent topic: Steps for CallBasic

374
Chapter 27: General troubleshooting (UNIX only)
This chapter outlines several problems that you may encounter running UniData, and offers
suggestions to research and resolve them. The chapter also describes a number of UniData system
messages, along with explanations of their causes.

Crashes and restart problems

This section presents suggestions for handling situations where UniData stops running entirely, or
where you cannot start UniData.

UniData crashes
Symptoms: System appears to be “hung”; one or more terminals may display the message Killed or
udt dead.
Suggestions:
1. Check to make sure your hardware and operating system is running. Hardware or power
problems may cause UniData to crash. If your system is up and running, proceed to step 2.
Otherwise, identify and resolve system problems.
2. If you are running UniData on AIX, check swap space. When it runs out of swap space, the AIX
operating system kills processes.
3. Check to see if UniData is still running. Run the showud command to check the status of the
UniData daemons. If the UniData daemons are still running, proceed to UniData is hung, on page
376. Otherwise, proceed to step 4.
4. Check the UniData logs and error logs. These logs are located in udtbin. Consider printing them
in 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 117
▪ Managing memory (UNIX only), on page 285
▪ Managing ipc facilities (UNIX only), on page 300
6. 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 375. Otherwise, resume normal
operations.

Note: UNIX system crashes may result in data inconsistencies or file corruption, depending
on the activity at the time of the crash. Examine your data files with guide after you start
UniData. 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 the
window where you run startud.

375
Chapter 27: General troubleshooting (UNIX only)

Suggestions:
1. Make sure your UNIX environment is running correctly. Check UNIX system logs for error and
warning conditions. Identify and resolve external problems.
2. Check the UniData log files in udtbin. Consider printing them in case they are needed to solve a
problem.
3. Check for indications of shared memory problems. (For example, if smm is unable to create the
CTL segment, UniData will not start). If messages exist in the smm.errlog, review Managing
memory (UNIX only), on page 285 for suggestions to solve the problem.
4. Check the status of UniData ipc facilities by logging on as root and running ipcstat. If ipc
structures were not properly cleaned up after a crash, follow the procedures that are described in
Managing ipc facilities (UNIX only), on page 300 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 Administering
the 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 (UNIX only), on page 307.

UniData is hung
Symptoms: The system has been performing acceptably, but the response slows. One to all terminals
may appear hung.
Suggestions:
1. Run the UNIX ps command. Look for processes with large and rapidly growing cpu time. Explore
these 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 164 for procedures to identify
and clear unneeded locks.
5. Identify and resolve message queue problems by using the procedures that are described in
Managing ipc facilities (UNIX only), on page 300.
6. If the response is still slow, or if steps 1 - 3 did not reveal the problem, check your system to
identify and resolve unusual load conditions. The UniData listuser, sbcsprogs, and
udtmon programs, and the UNIX uptime, vmstat, and ps commands may provide helpful
information.

Error messages
Error messages that are seen in UniData applications may originate from the following:

376
 Common error messages

▪ 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/ UniBasic runtime error. The error identifies the program
TEST at line 20... (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 UniData
can be found in the file that is identified by the VOC pointer
ENGLISH.MSG, which is a UniData hashed file. Use ECL
ESEARCH or UniQuery to search for messages in this file. If
you have localized UniData to run in your local language, see
UniData 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 troubleshooting
information.

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 the
command.
▫ BASICTYPE is set to P when it should be U or vice versa; try changing BASICTYPE and reenter the
command.

377
Chapter 27: General troubleshooting (UNIX only)

Not a verb command

▪ Occurrence—This error appears when you are attempting to run an ECL command.
▪ Cause—command must be either a VOC entry or a globally cataloged program.
▫ You spelled the command incorrectly; try again.
▫ You are in the wrong UniData account; command is not an entry in the local VOC file; check the
VOC file.
▫ command is a UniBasic program that is not globally cataloged; determine how it should be
cataloged; make necessary corrections; instruct users appropriately. See Managing cataloged
programs, on page 211 for further information.

cannot open abcdef

▪ Occurrence—This error is a UNIX-level error that occurs when a process is attempting to open a file
that 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 that
does not exist, while others return “cannot open.”

▫ The user that receives the error does not have sufficient permissions to run the file. See
UniData and UNIX security, on page 110 and Managing UniData security, on page 95 for more
information.

Note: Some UNIX commands return the message cannot open filename:
Permission denied and others simply return Permission denied.

[100004]
▪ Occurrence—A number of users are logged on to UniData. When an additional user tries logging
on, [100004] displays on the terminal.
▪ Cause—You are out of semaphore undo structures in the UNIX kernel. Use the UniData kp
command to display kernel settings; the parameter semmnu should be set to three times the
number of users 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 parameter
cannot exceed the kernel parameter semmnu. Set NUSERS to the number of authorized UniData
users + number of authorized UniData users / 4.

378
 Virtual field too big

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 a
stack of C routines that is bigger than the default. The limit that is exceeded is not the number of
characters in the formula itself, but an internal limit. Set the environment variable VFIELDSIZE to a
number greater than 300 (the default) to resolve this problem. Try setting VFIELDSIZE to 400. The
larger VFIELDSIZE is, the more memory your process requires.

Record is too long. Ask UniData to extend the U_MAXEXTRA.

▪ Occurrence—This message occurs while you are loading records from tape into a UniData hashed
file with T.LOAD. When the message occurs, T.LOAD quits, leaving a partial restore.
▪ Cause—T.LOAD encountered a record that is too large to process. You can remake the T.DUMP
tape with a larger block size, or you can load the tape into a DIR-type file rather than a UniData
hashed file. Once you load it into the DIR file, you can use the ECL COPY command to copy the
records into a hashed file. If you run T.LOAD to load a file into a directory, make sure your UNIX file
system has enough inodes; you need one inode for every record in the file you are loading.

Numra is maxed out in installshmid

▪ Occurrence—This message displays while someone is trying to run a globally cataloged UniBasic
program.
▪ Cause—The sbcs daemon is out of memory to store globally cataloged programs. sbcs can
manage up to 20 shared memory segments, and the size of each is determined by the UniData
configuration parameter SBCS_SHM_SIZE (1 MB by default). However, some UNIX versions (AIX, for
example) limit the number of shared memory segments to 10, which limits the memory available
for sbcs. You can resolve this situation by resetting SBCS_SHM_SIZE. Values from 4 - 8 MB are
appropriate for AIX systems.

379
Appendix A: Configuring SSL for Telnet (UNIX
only)

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 described
below.
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 port
number 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 the
path to the UniData bin directory. Udtelnetd is the UniData secured telnet server and it takes the
following options.

Option Description
-d N Debug level. Where N is the debugging level to be specified from 0 to 3. A setting
of 3 is the highest level of debugging and a 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 the
process id of udtelnetd invoked by inetd.
-o dir Specify the path to the temporary directory. The default setting is /tmp.

There are two new files introduced into the unishared directory on the server that you need to be
familiar with, udtelnetd and .udscrfile. They are located on the database server, under /
unishared/unitelnet. You can determine the location of the unishared directory by typing
cat /.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 used
to get security context in a pregenerated security file (defined in .udscrfile). This security context
record 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 more
information on the Security Context File, refer to the Developing UniBasic Reference manual.

380
Appendix B: UniData configuration parameters
This section lists the names and descriptions for all UniData configuration parameters in alphabetical
order.
Refer to Configuring your UniData system, on page 64 for additional information about modifying your
udtconfig file.
The following table describe the configuration parameters that are placed in the udtconfig file
located in \udthome\include at the time of installation. They are system-dependent and should
not be changed.

Parameter Description
AIMG_BUFSZ The size of the after image buffer, in bytes.
AIMG_FLUSH_BLKS Number of blocks that are flushed to the after image logs from the
after image buffer at one time.
AIMG_MIN_BLKS Minimum number of blocks required in the after image buffer before
the system flushes the blocks to the after image logs. Block size is set
in the log configuration table.
ARCH_FLAG Toggles archiving function on and off for RFS. Must be greater than 0
for archiving.
ARCH_WRITE_SZ Size, in bytes, of blocks for the archive process to write from the log
files to the archive files. Default is zero, meaning each write is one
block. If set to a nonzero value, must be a multiple of the log/archive
block size.
ARCHIVE_TO_TAPE Switch for turning on automatic save of archive files to backup.
Changing the value to 1 turns on this feature.
AVG_TUPLE_LEN Number of local pages that matches the average length of records
in your applications. Specifies the length of a buffer kept by udt for
holding a record. Should not exceed the number of local pages in a
global page.
AUDIT_LOG_COMPRESS Compresses a full log output block (default size is 4K), and writes
the compressed data into the audit log files. The compression log
file is a binary file that cannot be viewed by a text editor, and is not
directly loadable to a hash file or third-party tool. A value of 1 enables
compression. 0 disables it. The default value is 0. This parameter
applies to sequential log file only. For hashed log files and syslog files,
it is ignored.
AUDIT_LOG_ENC Specifies whether encryption is required for audit log records. The
default is 0 or FALSE. To turn on encryption, specify 1 or TRUE.
UniData encrypts the files regardless of whether Automatic Data
Encryption has been set up or not.

Note: If you change this value, you must backup and remove all
existing audit log files before you restart UniData.
AUDIT_LOG_LOC Specifies the directory where hashed or sequential audit log files, as
well as the staging and large record directories, are created. If this
value is not a full path, UniData treats it as relative to UDTHOME. If not
specified, the default is $UDTHOME/audit.

381
Appendix B: UniData configuration parameters

Parameter Description
AUDIT_LOG_START_DISABLEDAllows you to specify whether U2 Audit Logging starts automatically
or manually when UniData starts. A value of 1 disables U2 Audit
Logging when UniData starts. A value of 0 means U2 Audit Logging is
always started enabled. The default is 0.
AUDIT_LOG_MAX Specifies the maximum number of hashed or sequential audit log
files to be concurrently written by UniData. The value should be
between 1 and 8. The default is 1. For sequential log file types, if the
value is greater than 1, then multiple concurrent threads are created
within udaudd to handle the log writes. Each writer thread writes to a
separate log file.
AUDIT_LOG_MSG_LEVELS Controls which classes of log message are to be logged. By default, all
the values are enabled. The values are:
▪ INFO
▪ WARNING
▪ ERROR
▪ CRITICAL
INFO type messages are stored in the udaudd.log file. WARNING,
ERROR, and CRITICAL messages are stored in the udaudd.errlog
file.
AUDIT_LOG_TYPE Specifies the audit log file type. The default is 2 (sequential file). Valid
options are:
▪ 1 - UniData Dynamic file
▪ 2 - Operating system sequential file (default)
▪ 3 - Operating system syslog file (valid only for UNIX/Linux)
AUDIT_SEQ_BUF_SZ Specifies the size of each memory buffer used for sequential log files
in 1K blocks. UniData will have all buffers initialized, but only the first
AUDIT_LOG_MAX ones activated. UniData processes (such as udt)
randomly choose an active buffer each time a log record is produced
to provide balanced load for all buffers and to accommodate buffer
suspension/resumption. A larger size can improve audit performance.
This parameter only applies to the sequential audit log file. The unit is
1024-byte block. The default is 1024 (1 MB).
AUDIT_SEQ_FILE_SWITCH Specifies the amount of time in seconds before UniData must switch
to a new audit log file. On a busy system, the log file can grow rapidly.
Decide the value carefully based on your application and system load.
The format of this parameter is udaud.ddmmyyyy.seq, where
seq is a sequential number determined by UniData to guarantee the
uniqueness of the log files. The timestamp is determined by UTC time.
This parameter only applies to the sequential audit log file. The unit is
1 second. The default is 0 (no time switch limit).
AUDIT_SEQ_FILE_SZ Specifies the maximum size of a sequential log file in 1K blocks.
UniData will automatically switch to a new audit log file when its size
has reached the maximum. UniData can switch to a new file even if
the maximum is not reached. See AUDIT_SEQ_FILE_SWITCH for more
information. This parameter only applies to the sequential audit log
file. The unit is 1024-byte block. The default is 500000 (500 MB), and
the minimum size should not be less than 1MB. The total size cannot
be larger than 4GB.

382
 UniData configuration parameters

Parameter Description
AUDIT_SEQ_OUTBLK_SZ Specifies the output block size in 1K blocks used by the udaudd
daemon for sequential log files. udaudd writes to a log file only
after at least this size of data was available from the buffer. It is not
necessarily equal to the system physical block size. Depending on
platforms, a larger block size can improve performance but can cause
more log data loss in the case of a system crash. This parameter only
applies to the sequential audit log file. The unit is 1024-byte block.
The default is 4 (4 KB). Any value less than 1 or greater than 32 will
default to 4.
AUDIT_SEQ_SYNC_CNT Specifies the number of cached log records when UniData must put
the cached data into the system buffer. On a busy system, the log
data can grow very rapidly. Decide the value carefully based on your
application and system load. If the value is 0, data is not cached
and the audit log record is immediately put into the system buffer.
A larger count value may cause more log data loss in the case of a
system crash. See AUDIT_SEQ_SYNC_TIME for more information. This
parameter may or may not improve performance. This parameter only
applies to the sequential audit log file. The default is 0 (no caching),
and you can choose up to 1000.
AUDIT_SEQ_SYNC_TIME Specifies the amount of time in milliseconds (up to 5,000) before
UniData must put the cached audit log records into the system buffer.
On a busy system, the log data can grow very rapidly. Decide the value
carefully based on your application and system load. If the value is 0,
data is not cached and the audit log record is immediately put into
the system buffer. A longer sync time may cause more log data loss
in the case of system crash. See AUDIT_SEQ_SYNC_CNT for more
information. This parameter may or may not improve performance.
This parameter only applies to the sequential audit log file. The unit is
1 millisecond. The default is 0 (no caching).
BGINPUTTIMEOUT The number of seconds a background or phantom process waits
before timing out. Before the timeout expires, a process may use
the UNIX tandem or the UniData for Windows Platforms TANDEM
command to attach to the process.
BIMG_BUFSZ The size of the before image buffer, in bytes.
BIMG_FLUSH_BLKS Number of blocks that are flushed to the before image logs from the
before image buffer at one time.
BIMG_MIN_BLKS Minimum number of blocks required in the before image buffer before
the system flushes the blocks to the before image logs. Block size is
set in the log configuration table.
BPF_NFILES Per-process logical limit for total number of recoverable files that
can be opened with UniBasic OPEN statements at one time. If more
recoverable files are opened, UniData closes files and then reopens
them, causing heavy overhead. This parameter cannot exceed N_AFT.
CENTURY_PIVOT Determines the century pivot date. Default is 1930.
CHECK_HOLD_EXIST Determines if UniData checks for the existence of a _HOLD_ file prior
to unconditionally removing it when you specify the BANNER UNIQUE
option with the SETPTR command.
CHKPNT_TIME Checkpoint interval: number of seconds between flushes of the
system buffer to disk.

383
Appendix B: UniData configuration parameters

Parameter Description
COMPACTOR_POLICY Used to guide BASIC memory compactor to do compaction for BASIC
strings.
0: compact when program is finished
1: compact when EXECUTE (another BASIC pgm) is completed
2: compact when EXECUTE (another BASIC program) or CALL is
completed
CONVERT_EURO Turns Euro conversion on or off. If this flag is set to 0, UniData does
not perform conversion. If this flag is set to 1, UniData performs
conversion.
DEFAULT_HASH_TYPE The udtconfig parameter DEFAULT_HASH_TYPE was introduced at
8.1.0. The value can be 0, 1, or 3. The default value for creating a new
file is TYPE is 3. If the hash type is not specified, then the value of the
udtconfig parameter DEFAULT_HASH_TYPE will be used.
Old files will not be automatically resized to the value specified in
DEFAULT_HASH_TYPE. Instead, they will remain in their current hash
type. Any change in type must be specified using the RESIZE or
MEMRESIZE commands.
DEFAULT_HASH_ TYPE This is the default hash type for the hashed file to be created. The
valid 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.
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 this
parameter is 3, meaning that the new whole file split style will be the
default.
EFS_LCKTIME Used by the NFA Server to specify the maximum time to wait for a
lock.
EXPBLKSIZE Number of local pages used for expression buffers. udt keeps a buffer
of this size for intermediate results. We recommend you set this
parameter so the buffer is one-quarter to one-half the size of a global
page.
FCNTL_ON Used with UniData Physical Lock Manager. If a UNIX platform supports
test-n-set instruction, SYS_PV is set to 3 and FCNTL_ON is set to 0. If a
UNIX platform does not support test-n-set instruction, SYS_PV is set
to 2 and FCNTL_ON is set to 1. Do not change this parameter unless
instructed to do so by Technical Support.
FIPS_MODE Specifies the default system-wide FIPS mode. UniVerse uses an
embedded FIPS 140-2 validated cryptographic module provided by
OpenSSL. When UniData is running with FIPS mode enabled (value 1),
all its crypto operations are performed by the embedded FIPS module
where only FIPS 140-2 compliant crypto algorithms are allowed. When
FIPS mode is disabled (value 0), no such restrictions apply. Default
value: 0.

Note: Beginning at UniData 8.2.1 or higher, when FIPS mode is

enabled in the udtconfig file, the SSLv3 protocol is unavailable and
is blocked from all incoming and outgoing secure connections to and
from the database.

384
 UniData configuration parameters

Parameter Description
FIELD_UPDATE_THRESHOLD Defines the record size threshold to which field-level updates apply;
an integer in Kbytes.
The default is 0. With the default setting, field-level updates are not
used for WRITE commands.
If you specify a FIELD_UPDATE_THRESHOLD, when you change a
record with a WRITE statement, the entire record is updated if the
record size is smaller than the FIELD_UPDATE_THRESHOLD. If the
record size is larger than the specified threshold, UniData compares
the original record with the update and only writes changed field
values, rather than updating the entire record.
This parameter affects RFS and replication files, including hash files
and directory files. If the file is not a published replication or RFS file,
this has no effect.
For more information, please the "Configuring field-level replication"
section in the U2 Data Replication User Guide and the WRITE
documentation in the UniBasic Commands Reference guide.
GLM_MEM_ALLOC Windows only. Defines the number of lock nodes allocated for
each memory request, and is highly application dependent. If your
application requires a large number of locks in one transaction, this
setting should be increased to the maximum number of locks per
transaction *2.
GRP_FREE_BLK Pertains to dynamic files only; the number of free blocks kept in the
free block list at the group level. If more blocks are freed, they are
kept at the file level.
GRPCMT_TIME Interval, in seconds, between flushes to the after image log set.
HTTP_DEFAULT_VERSION Specifies default HTTP version. The version defaults to 1.1. Valid
values are 1.0 and 1.1.
JRNL_MAX_FILES Maximum number of journal files allowed per journal process.
JRNL_MAX_PROCS Maximum number of journal processes per journal path.
KEYDATA_MERGE_LOAD Default loading factor (percent) at which a group pair in a dynamic
file using the KEYDATA option merges. A group pair is eligible for
merging when the sum of the percentages of space occupied by keys
and pointers in both groups is less than KEYDATA_MERGE_LOAD. The
CONFIGURE.FILE command overrides this for individual files.
KEYDATA_SPLIT_ LOAD Default loading factor (percent) at which a group in a dynamic file
using the KEYDATA option splits. Splitting occurs when the percentage
of space in a group occupied by keys and pointers reaches the split
load. The ECL CONFIGURE.FILE command overrides this for
individual files.
LB_FLAG For nonrecoverable files, turn Transaction Processing on or off
by changing the value of this parameter. If you set the value
to 0, Transaction Processing is off for nonrecoverable files and
TP semantics are ignored. If you set the value to 1, Transaction
Processing is on.
Note: If RFS is on, the LB_FLAG has no effect on recoverable files. You
cannot turn off transaction processing for recoverable files if RFS is
enabled.
LOCKFIFO The locking sequence of processes in the system. This parameter
should not be changed.

385
Appendix B: UniData configuration parameters

Parameter Description
LOG_OVRFLO Path to the directory where UniData creates log overflow files.
MAX_CAPT_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH
CAPTURING or MDPERFORM WITH CAPTURING clauses. Individual
users can set an environment variable that overrides the
configuration parameter.
MAX_DSFILES Maximum number of nonrecoverable dynamic part files (dat00x,
over00x) a UniData process can open with UniBasic OPEN statements
or ECL commands. Each dynamic file has at least two part files.
MAX_FLENGTH Upper size limit, in bytes, of each partition file (dat00x) of a dynamic
file. When a part file reaches this size, UniData does not add further
blocks to it, but creates another part file using the part table. The
default value is 1073741824 bytes (1 GB). Must be greater than 32768
bytes (32 KB) and less than 2147467264 bytes (2 GB-16KB).
MAX_LRF_FILESIZE TThe maximum log reserve file size, in bytes. The default value is
134,217,728 (128 MB) This file is used primarily when replication
is suspended. This value applies to the size of each body<nn> or
info<nn> file in each <group_name>.lrf directory. The .lrf
directories reside in the udtconfig REP_LOG_PATH directory.
MAX_LRF_FILESIZE TThe maximum log reserve file size, in bytes. The default value is
134,217,728 (128 MB) This file is used primarily when replication
is suspended. This value applies to the size of each body<nn> or
info<nn> file in each <group_name>.lrf directory. The .lrf
directories reside in the udtconfig REP_LOG_PATH directory.
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.
MAX_OBJ_SIZE Maximum size, in bytes, of object programs that can be loaded into
shared memory. Object programs larger than this size are loaded into
the user’s address space instead of shared memory.
MAX_OPEN_FILE Maximum number of hashed files that can be opened by UniBasic
OPEN statements, per udt process. Includes recoverable and
nonrecoverable, static, dynamic, and sequentially hashed files; each
dynamic file counts as one file.
MAX_OPEN_OSF Maximum number of UNIX sequential files that can be opened at one
time by UniBasic OSOPEN statements, per udt process.
MAX_OPEN_SEQF Maximum number of sequential files that can be opened at one time
by UniBasic OPENSEQ statements, per udt process.
MAX_REP_DISTRIB Reserved for internal use.
MAX_REP_SHMSZ The maximum shared memory buffer segment size for a replication
group. This value includes consideration for REP_BUFSZ,
N_LOGINFO, distributions, and group control information. The
default value is 1,073,741,824 (1 GB) and it must be less than 2
GB. If MAX_REP_SHMSZ_GB is configured, then the maximum
shared memory buffer size for a replication group is the sum of
MAX_REP_SHMSZ_GB * 1GB + MAX_REP_SHMSZ.
MAX_REP_SHMSZ The maximum shared memory buffer segment size for a replication
group. This value includes consideration for REP_BUFSZ,
N_LOGINFO, distributions, and group control information. The
default value is 1,073,741,824 (1 GB) and it must be less than 2
GB. If MAX_REP_SHMSZ_GB is configured, then the maximum
shared memory buffer size for a replication group is the sum of
MAX_REP_SHMSZ_GB * 1GB + MAX_REP_SHMSZ.

386
 UniData configuration parameters

Parameter Description
MAX_RETN_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH
RETURNING or MDPERFORM WITH RETURNING clauses. Individual
users can set an environment variable that overrides the
configuration parameter.
MERGE_LOAD Default loading factor (percent) at which a group pair in a dynamic
file using the KEYONLY option merges. A group pair is eligible for
merging when the sum of the percentages of space occupied by
keys and pointers in both groups is less than MERGE_LOAD. The
CONFIGURE.FILE command lets users override this for individual
files.
MGLM_BUCKET_SIZE Number of nodes per bucket. If this parameter is inadequate for an
application, UniData displays an out of memory message is.
MIN_MEMORY_TEMP The minimum number of local pages that should be kept for
temporary buffers in a process group. Determined at installation.
MSGMAX Windows only. The maximum size of a message.
MSGMNI Windows only. The maximum number of message queues available
for UniData system-wide.
MSGTQL Windows only. The maximum number of messages allowed system-
wide.
MSGTX Windows only. The default text size of a message per node.
N_AFT System-wide limit on the number of recoverable files and indexes
that can be open at one time. The value of N_AFT in the udtconfig
cannot exceed 32,767. This is the number of slots in the system
buffer AFT. Parameter is like MAX_OPEN_FILES but pertains only to
recoverable files. A dynamic file counts as one file. Even if more than
one user opens the same file, it is only counted once.
N_AFT_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_AFT_SECTION Number of sections in the AFT. Used for RFS only.
N_AIMG Number of after image log files in each log set.
N_ARCH The number of archive files.
N_BIG Number of block index groups. This parameter determines the size
of an index table for accessing the RFS system buffer. If you enlarge
N_PUT, you should enlarge N_BIG as well. Must be a prime number.
N_BIMG Number of before image log files in each log set.
N_FILESYS Maximum number of UNIX file systems allowed. If you have more than
200 UNIX file systems, increase to your number of file systems.

387
Appendix B: UniData configuration parameters

Parameter Description
N_PARTFILE System-wide total number of recoverable dynamic part files that can
be open at one time.
This limit includes files opened by ECL and UniBasic. Each dynamic
file has at least two part files; therefore, opening a dynamic file means
opening at least two part files. Even if more than one user opens the
same dynamic file, each part file is counted once toward the total.
By default, N_PARTFILE has a minimum value calculated as follows:
▪ When N_AFT is less than or equal to 200, N_PARTFILE can be no
less than the value of N_AFT * 256
▪ When N_AFT is greater than 200 and less than or equal to 1,000,
N_PARTFILE can be no less than (200*256 + (N_AFT-200)*20)
▪ When N_AFT is greater than 1,000, N_PARTFILE can be no smaller
than ( 200*256 + 800*20 + (N_AFT-1000)*10)
If you specify a value for N_PARTFILE lower than the results of these
calculations, UniData overrides the setting.
N_PGQ Number of message queues for tm processes to send messages to
udt processes. Calculated by installation; one queue for every four
licenses.
N_PUT Number of 1,024-byte pages in the system buffer. The size of the
buffer cannot exceed SHMMAX. Sometimes the default value of N_PUT
must be decreased in order to complete a UniData installation.
N_REP_OPEN_FILE The maximum number of open replication log files for a udt or tm
process. The default value is 8.
N_SYNC Determines how many sync daemons UniData should start.
N_TMAFT_BUCKET Number of hash buckets in each tm process’s active file table (TMAFT).
Used for RFS only.
N_TMQ Number of message queues for udt processes to send messages to
tm processes. Calculated by installation; one queue for every four
licenses.
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 is
0, the default, you cannot access an NFA file on UniData 7.2 or greater
from a version of UniData prior to 7.2. If this value is set to 1, you can
access an NFA file on UniData 7.2 or greater from an earlier version of
UniData, but the file cannot be encrypted.
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 is
0, the default, you cannot access an NFA file on UniData 7.2 or greater
from a version of UniData prior to 7.2. If this value is set to 1, you can
access an NFA file on UniData 7.2 or greater from an earlier version of
UniData, but the file cannot be encrypted.
NFA_CONVERT_CHAR If this value is set to 1, UniData converts marks in a stream of data to
host-specific marks.
NFILES Number of physical files that can be opened at the operating system
level at one time in a UniData session. This limit is for both udt and
tm processes; the name of the corresponding kernel parameter varies
among UNIX/Windows versions.
NSEM_PSET Number of semaphores per semaphore set.

388
 UniData configuration parameters

Parameter Description
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.
NUSERS Limit for number of UniData user processes (such as udt and
PHANTOM) that can run at the same time.
NVLMARK Specifies a character to print to represent the null value. The ASCII
character that represents the null value is non-printing.
PART_TBL Path of a UNIX text file that directs UniData where to create dynamic
file part files.
QUOTED_IDENTIFIER When the value of QUOTED_IDENTIFIER is 1, identifiers can be
delimited by double quotation marks, and literals must then
be delimited by single quotation marks. When the value of
QUOTED_IDENTIFIER is 0, identifiers cannot be quoted, and literals
can be delimited by either single or double quotation marks.
REP_CP_TIMEOUT Specifies the checkpoint manger (cm) daemon timeout interval for
replication at checkpoint. The default value is 200 seconds. If this
value is set to 0, the cm daemon will not time out.
REP_FLAG The REP_FLAG parameter enables or disables U2 Data Replication.
If this value is 0, U2 Data Replication is off. If this value is a positive
integer, it is on.
REP_LOG_PATH The full path to the replication log files. The default value is
$UDTHOME/log/replog.
RFS_DUMP_DIR Defines where UniData stores the rfs.dump file when you execute
the s_stat -s command. On Windows, the default value is
UDTHOME\bin, with UniData storing the rfs.dump file in the
UDTBIN directory. On UNIX, The default value is an empty string, with
UniData storing the rfs.dump file in the $UDTBIN directory. If the
path you specify is invalid when UniData starts, UniData writes the
rfs.dump file to the $UDTBIN directory, and prints a message to the
sm.log.
RFS_DUMP_HISTORY Specifies how many rfs.dump files to preserve when you execute
the s_stat -s command.
The default value is 1. With this value, UniData creates the rfs.dump
file in the directory you specify with the RFS_DUMP_DIR parameter.
If this value is set to a positive integer, for example 4, the rfs.dump
files will be named rfs.dump1, rfs.dump2, rfs.dump3, and
rfs.dump4. The s_stat -s command uses the first available
rfs.dump file. If all rfs.dump files are full, s_stat -s reuses the
oldest rfs.dump.file.
If this value is set to 0, all rfs.dump files are preserved and named
rfs.dump1, rfs.dump2, and so forth.
SB_FLAG Toggles system buffer on and off. If zero, system buffer is off. Must be
greater than zero for RFS.
SB_PAGE_SZ Specifies the size of the system buffer page. Valid values are 1 through
16, where 1 specifies 1K, 2 specifies 2K, and so forth. The default value
is 1.
SBCS_SHM_SIZE Size, in bytes, of shared memory segments created by sbcs to store
globally cataloged programs. sbcs can attach a maximum of 20
segments system-wide. Runtime errors result if a user attempts to
load a new global program that exceeds this limit.

389
Appendix B: UniData configuration parameters

Parameter Description
SETINDEX_BUFFER_ KEYS Controls whether READFWD and READBCK statements use a buffering
mechanism. Default value is 0 (buffering off). Individual environment
variable overrides udtconfig setting; BUFFER.KEYS keyword in the
SETINDEX statement overrides either.
SETINDEX_VALIDATE_KEY Controls whether READFWD and READBCK statements validate
a key value just read. Default value is 0 (no validation). Individual
environment variable overrides udtconfig setting. VALIDATE.KEY
keyword in the SETINDEX statement overrides either.
GLM_MEM_SEGSZ The segment size for each shared memory segment required for
the lock manager. The maximum number of segments is 16. Large
application environments require a larger size. Each udt will register
the lock names it is locking in its per-process locking table. This table
is also organized as a hashed table.
GLM_MEM_SEGSZ must be greater than 4096 and less than
GLM_MEM_SEGSZ. The formula for determining GLM_MEM_SEGSZ
is NUSERS * maximum number of locks per transaction * 512.
GLM_MEM_SEGSZ should be a multiple of 4096.
N_GLM_GLOBAL_BUCKET The number of hash buckets system-wide used to hold the lock
names in shared memory. This setting directly affects performance.
Normally, the default value of this parameter should not be changed.
However, if you notice significant degradation in performance, or your
application intensively accesses specific files, you can increase this
parameter. The default value is the closest prime number to NUSERS
* 3.
N_GLM_SELF_BUCKET The number of hash buckets for the per-process locking table. This
parameter is highly application-dependent. If the application requires
a large number of locks in one transaction (more than 20), you should
increase this setting to the closest prime number to the maximum
number of locks per transaction.
SHM_ATT_ADD Starting address for shared memory attachment. Set at installation;
do not change this unless instructed by Technical Support.
SHM_FIL_CNT Maximum number of dynamic files that can be open concurrently,
system-wide.
SHM_FREEPCT Percentage of freed global pages in an active global shared memory
segment that UniData keeps in the global shared memory pool.
smm checks the current percentage; if the percentage is less than
SHM_FREEPCT, smm creates a new shared segment.
SHM_GNPAGES Number of global pages in a shared memory segment.
SHM_GNTBLS Number of GCTs (global control tables) in CTL. Each shared memory
segment is associated with a GCT. The GCT registers the use of global
pages in its associated shared memory segment. Cannot exceed the
kernel parameter shmmni.
SHM_GPAGESZ Size of each global page, in 512-byte units.
SHM_LBA Alignment size, in bytes, for shared memory attachment. Set at
installation; do not change.
SHM_LCINENTS The number of entries in the CI table of each LCT, which is the number
of local pages that can be attached by a process. SHM_LCINENTS
must be greater than or equal to SHM_SHM_LMINENTS. Cannot
exceed 255.

390
 UniData configuration parameters

Parameter Description
SHM_LMINENTS Number of entries in the MI table of a LCT, which means the number of
global pages or self-created dynamic segments that can be attached
by a process. Cannot exceed 255.
SHM_LPAGESZ Size, in 512-byte blocks, of each local page in a global page. A global
page is divided into local pages, so SHM_GPAGESZ must be a multiple
of SHM_LPAGESZ.
SHM_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_MAX_SIZE Current kernel setting for maximum size (in bytes) of a shared
memory segment. This parameter is set at installation; if you increase
the kernel parameter shmmax, you need to increase SHM_MAX_SIZE
to the same value as well.
SHM_MIN_NATT The minimum number of shared memory segments that should be
kept attached to a process.
SHM_NFREES The number of inactive shared memory segments that UniData keeps
in the system. smm checks the current number of inactive segments;
if the number is larger than SHM_NFREES, smm returns some inactive
global shared segments to UNIX.
SINGLE_SAVEDLIST By default at UniData 8.1.0 and later, the saved list is stored as
one item in the SAVEDLISTS directory. You may see a performance
improvement during a DELETE.LIST operation, due to fewer files
being involved. This behavior can be returned to the original behavior
in UniData 7.3.x and earlier by setting the udtconfig parameter
SINGLE_SAVEDLIST from 1 (default) to 0.
With SINGLE_SAVEDLIST set to 0, or using UniData 7.3.x or earlier, a
saved list that exceeds approximately 34,810 characters on UniData
for UNIX or 29,408 on UniData for Windows platforms is saved in
multiple parts. Each part has an extension to the specified saved list
name, beginning at 000 and incrementing sequentially (001, 002, and
so forth).
SPLIT_LOAD Default loading factor option (percent) at which a group in a dynamic
file using the KEYONLY option splits. Splitting occurs when the
percentage of space in a group occupied by keys and pointers reaches
the split load. The ECL CONFIGURE.FILE command overrides this
for individual files.
SSL_OPTIONS Specifies additional options that will be set for SSL
connections. The valid options are: TLS_FALLBACK_SCSV, and
NO_TLS_FALLBACK_SCSV. The valid delimiters are: comma(,), and the
plus sign (+). Invalid options will be ignored. If the parameter is not
specified, or the resultant string is empty, then TLS_FALLBACK_SCSV
will be the default. When TLS_FALLBACK_SCSV is specified, protocol
downgrade will not be allowed during the SSL session handshake,
preventing the POODLE attack.
SSL_PROTOCOLS Specifies the protocols allowed using SSL connections. The allowed
protocols are: SSLv3, TLSv1, TLSv1,1 TLSv1,2. The valid delimiters are:
comma(,), and the plus sign (+). Invalid protocols will be ignored. If
the parameter is not specified, or the resultant string is empty, then
TLSv1+TLSv1.1+TLSv1.2 will be the default.

391
Appendix B: UniData configuration parameters

Parameter Description
STATIC_GROWTH_ The time interval, expressed in seconds, to warn when a static file is
WARN_INTERVAL larger than the threshold. If the file is nonrecoverable, UniData writes
the information to the udt.errlog file. If the file is recoverable,
UniData writes the information to the sm.log file
STATIC_GROWTH_ The threshold value for the static file size, expressed in bytes. If
WARN_SIZE the file is nonrecoverable, UniData writes the information to the
udt.errlog file. If the file is recoverable, UniData writes the
information to the sm.log file
STATIC_GROWTH_ The number of table elements in the Static Growth Warn table.
WARN_TABLE_SIZE UniData uses this table to track the last time a warning was issued
indicating a file was larger than the threshold. When no unused
elements are present in the table, UniData uses the oldest element
for a new static file. If the file is nonrecoverable, UniData writes
the information to the udt.errlog file. If the file is recoverable,
UniData writes the information to the sm.log file
SYNC_TIME Defines the number of seconds the sync daemon should wait before
scanning the Block Index Group to flush dirty pages.
SYS_PV Type of P/V operations used for the Recoverable File System (RFS)
only. Determined at installation; platform dependent. Do not change
unless instructed by Technical Support.
SYSTEM_EURO The configurable system Euro encoding. On UNIX systems, the default
is CHAR(164). On Windows Platforms, the default is CHAR(128).
TANDEM_FLAG Specifies whether a UniData session is allowed to be TANDEMized by
default. The default value is 1, meaning TANDEM is allowed. The other
valid value is 0.
TCA_SIZE The maximum number of entries in the transaction control area (TCA).
The TCA is used when more than one replication group is configured,
and there are cross-group transactions.
If you are using transaction processing, set the value to at least the
number of users on the system. If you are not using transaction
processing, this parameter is irrelevant.
TCA_SIZE The maximum number of entries in the transaction control area (TCA).
The TCA is used when more than one replication group is configured,
and there are cross-group transactions.
If you are using transaction processing, set the value to at least the
number of users on the system. If you are not using transaction
processing, this parameter is irrelevant.
TERM_EURO Sets the terminal system Euro Code. On UNIX systems, the default is
CHAR(164). On Windows Platforms, the default is CHAR(128).
TMP Path of a directory for storing intermediate work files. Default is
\U2\ud82\temp on UniData for Windows Platforms or /tmp/ on
UniData for UNIX. When changing this parameter on UniData for UNIX,
do not forget the trailing “/.”
TOGGLE_NAP_TIME If FCNTL_ON is set to 0, the length of time (in milliseconds) that a
process waits to access a shared memory address held by another
process. This parameter has no effect if FCNTL_ON is set to 1. Do not
change unless instructed to do so by Technical Support.

392
 UniData configuration parameters

Parameter Description
TOGGLE_NAP_TIME_NS If FCNTL_ON is set to 0, the length of time (in nanoseconds) that a
process waits to access a shared memory address held by another
process. On UniData for UNIX, this parameter is used together with
TOGGLE_NAP_TIME. On UniData for Windows, this parameter is not
used. Do not change this parameter unless instructed by Rocket
Software.
TRIGGER_ADMIN Allows triggers to be administered by users who are members of a
designated operating systems group. If one or more groups have
administration rights, the group name(s) must be specified as a
comma-delimited list. For example:
TRIGGER_ADMIN=global1, globaladm
Users who are members of global1 and globaladm are able to amend
triggers as long as they have read and write access.
By default, the user who created the trigger has administrator rights.
TSTIMEOUT Used by the udtts executable to specify the maximum number of
seconds to wait for input from client about device information. If
the information is not provided, UniData starts without the device
information.
UDR_CONVERT_CHAR When this value is set to 1, if the publishing server and the subscribing
server have a different I18N group, UniData converts marks and
SQLNULL marks to those on the local machine on the data passed
between the two systems. The default value is 0.
UDR_CONVERT_CHAR When this value is set to 1, if the publishing server and the subscribing
server have a different I18N group, UniData converts marks and
SQLNULL marks to those on the local machine on the data passed
between the two systems. The default value is 0.
UDT_LANGGRP The language group ID used to distinguish language groups that use
similar special characters. UDT_LANGGRP is composed of the record
mark, escape sequence mark, and the null value mark. The default is
255/192/129.
UDT_SPLIT_POLICY Determines if a dynamic file splits when an existing record is rewritten
to the file without any changes. If the value of this parameter is set to
1, rewriting an existing record to an 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 existing record in a dynamic file group that was
already over the defined split load triggers a split for the file.
UDT_SPLIT_POLICY Determines if a dynamic file splits when an existing record is rewritten
to the file without any changes.
If the value of this parameter is set to 1, rewriting an existing record to
an 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 existing
record in a dynamic file group that was already over the defined split
load triggers a split for the file.

393
Appendix B: UniData configuration parameters

Parameter Description
UDT_TM_IPC Windows only. On UniData for UNIX, the udt and tm processes
communicate using message queues. Since message queues are not
available on Windows platforms, UniData provides three options for
the communication between the udt and tm processes:
▪ UDT_TM_IPC=1 – UniData uses its own message queues to
communicate between the udt and tm processes. If you change
the value of the N_PGQ or N_TMQ udtconfig parameters,
you must also change the value of the MSGMNI configuration
parameter. The value of MSGMNI should be 12+N_PGQ+N_TMQ.
▪ UDT_TM_IPC=2 – UniData uses named pipes as the
communication mechanism between the udt and tm processes.
Each udt process creates two named pipes, one for the udt
process to write and the tm process to read, and one for the tm
process to write and the udt process to read.
▪ UDT_TM_IPC=3 – UniData uses memory-mapped files and events
to communicate between the udt and tm processes. Each udt
process creates 2K memory-mapped files when it starts.
The default value for the UDT_TM_IPC udtconfig parameter is 3
UPL_LOGGING Determines if UPL performs logging. If this parameter is set to 0, UPL
does not perform any logging. If this value is set to 1, UPL performs
logging.
USE_DF Windows only. The USE_DF parameter enables you to choose how
UniData loads the shared memory table. Beginning in UniData 7.2, the
smm daemon no longer forked a df process to create the entries in the
shared memory table, as it had in prior releases. Now, UniData loads
the shared memory table by reading the mount table.
If you set the value of USE_DF to 0, UniData loads the shared memory
table by reading the mount table. This is the default setting.
If you set the value of USE_DF to 1, the smm process forks a df process
to load the shared memory table.
USE_DF UNIX only. Determines whether UniData reads the mount table or
forks a df process when you execute the sms -F command.
0 – UniData loads the shared memory table by reading the mount
table.
1 – UniData forks a df process to load the shared memory table.
VARMEM_PCT The percentage of free memory that should be kept in the first global
page for UniBasic variables after compacting. If the actual percentage
is less than this value, UniData keeps one free global page. Otherwise,
UniData returns all free global pages to UNIX.
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; in
such a case, no merge will occur). The default value is 40.
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 split
will occur, which would tell the system not to split). The default value
is 75.
WRITE_TO_CONSOLE Switch for turning on and off messaging to your console. Must be
greater than zero for messages to display at console.

394
 UniData configuration parameters

Parameter Description
ZERO_CHAR The character you want to use to represent CHAR(0). See OSREAD,
OSBREAD, READT in the UniBasic Commands Reference for more
information.

395
Appendix C: Environment variables for UniData
This section lists environment variables that can be set to customize a UniData environment.
Users can set them before entering UniData to affect a particular UniData session. UNIX system
administrators can also set them in a .login or .profile for one or more users to establish
defaults for some or all users.
The following table lists environment variables in alphabetical order.

Environment variable Description

ALLOW_DBPAUSE_ OSBWRITE When this environment variable is set to 1, an OSBWRITE process
is successful even if dbpause if active. If the environment variable
is set to 0, an OSBWRITE process pauses.
BACKUP_CNTL_FILE UNIX only. Used by the Recoverable File System (RFS); specifies
a path where the udt.control.file can be automatically
backed up at checkpoint time. If this variable is not defined,
udt.control.file is not backed up.
CSTACKSZ Establishes the maximum number of commands in the ECL
command stack. Each stack entry can hold a 2720 character
command. The default is 49.

Note: On UNIX, f 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. If
INIT_BREAKOFF is not set, the break key is enabled by default.
LPREQ UNIX only. Identifies an alternate spooler directory. Must be a full
path ending in “/”.
MAX_CAPT_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH
CAPTURING or MDPERFORM WITH CAPTURING clauses. This
environment variable overrides the configuration parameter in
the udtconfig file.
MAX_RETN_LEVEL Number of levels allowed for nested UniBasic EXECUTE WITH
RETURNING or MDPERFORM WITH RETURNING clauses. This
environment variable overrides the configuration parameter in
the udtconfig file.
MAX_TRANS_FIELD Number of TRANS fields that can be kept concurrently; default
value is 12; must not be greater than 64.
MAX_TRANS_REL Number of TRANS files that can be open concurrently; default
value is 32; must not be greater than 32.
NFA_LOG_DIR Used by NFA; name of a directory where UniData creates NFA
client-side. If this variable is not defined, the logs are created in /
tmp on UNIX or \temp on Windows.
NFA_LOG_LEVEL Used by NFA; debug level for NFA client processes. Can be an
integer 0-10; level 0 logs only fatal errors, and level 10 logs all
traffic and many internal functions. The default is level 0.
NOCHKLPREQ UNIX only. Bypasses UNIX printer verification; useful for large
systems with hundreds of printers defined.
PHANTOM_WAIT The PHANTOM_WAIT environment variable specifies the number
of seconds to wait before populating the CAPTURING variable and
returning to the main program. If you set this value to 0, there is
no delay before populating the CAPTURING variable.

396
 Environment variables for UniData

Environment variable Description

SETINDEX_ BUFFER_ KEYS Controls whether READFWD and READBCK statements use
a buffering mechanism. Default value is 0 (buffering off).
Individual environment variable overrides udtconfig setting;
BUFFER.KEYS keyword in the SETINDEX statement overrides both.
SETINDEX_ VALIDATE_KEY Controls whether READFWD and READBCK statements validate
a key value just read against the record. Default value is 0
(no validation). Individual environment variable overrides
udtconfig setting; VALIDATE.KEY keyword in the SETINDEX
statement overrides both.
SGLISTNUM Size of token stack for XREF, in UENTRY. Default is 500.
SQL_TMP_MODULO Number of temporary files used by UniData SQL for an equal
join operation. Default is 7; if this is set to a number less than 7,
UniData SQL uses the default. No upper limit. Must be set before
entering udt/SQL, or before starting UniServer.
SUPPRESS_ORPHAN_ Determines if the guide utility reports orphan blocks. Orphan
BLOCK_ERROR blocks could exist in both the primary file and the overflow
files. guide reports these errors in the GUIDE_ERRORS.LIS
file. If you want to suppress these messages, set the value of
SUPPRESS_ORPHAN_BLOCK_ERROR to a positive integer.
TABSTOPS Specifies a number of characters to tab in UniBasic PRINT
statements. Must be 1-76. The default is 8.
TMP Identifies an alternate directory for /tmp (UNIX) or \temp
(Windows) when additional work space is needed by UniData.
Must be a directory path ending with / (UNIX) or \ (Windows).
UDT_EDIT Identifies the path of the text editor UniData invokes when users
execute the ECL ED command. The default is vi. This variable
cannot be set to AE.
UDT_INTERNAL1 Determines the number of sleep milliseconds for SYSTEM(14). The
default value is 15. Valid values are 0 to 500. If this environment
variable is not set, SYSTEM(14) sleeps for 15 milliseconds if there
is no data in the input pipe. If it is set to 0, SYSTEM(14) returns the
number 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
list name when executing the SAVE.LIST command.
UDT_SELECTSIZE Size of a buffer used to keep select list in memory. If a select list
is larger then the size of this buffer, UniData writes it to a file. If
UDT_SELECTSIZE is not defined, the system uses a buffer size of
10 KB.
UDTBIN Location of UniData executables.
UDTERRLOG_LEVEL Determines the logs to which file open errors are written. If the
value of this environment variable is equal to or greater than
2, UniData writes file open errors to the udt.errlog, and
on Windows platforms, to the Windows event log. Otherwise,
UniData does not log file open errors.
UDTHOME Location of the UniData home directory, which contains
directories including sys, demo, lib, work, sybase, and include.
VFIELDSIZE Increases the size for the stack of C routines used to process
formulas created in virtual fields. Default is 300. Define a larger
number if users see “virtual field too big” errors in UniQuery.

397
Appendix C: Environment variables for UniData

Environment variable Description

VOC_READONLY If set to a nonzero number, allows UniData to run with read-only
access to the VOC file.
VVTERMCAP The UNIX path of the vvtermcap file needed to run the UniData
commands UENTRY, shmconf, and confprod. This variable is
not necessary if UDTBIN is defined.

398
Appendix D: Daemon processes
Daemon processes are available for use for U2 Data Replication and cleaning up dead user processes.

Shared memory manager

The shared memory manager daemon, smm, records all operating system resources, such as shm
segments and semaphores.

System clock
A system clock is in the system shared memory segment to generate a timestamp. uvsmm and smm are
enhanced to have a separate thread repeatedly update the clock every second. Other processes can
quickly get the current time from the system clock instead of repeatedly calling system calls.
The data update log contains the timestamp generated from the system clock. For transactions,
all transaction logs contain the same timestamp as the data update log, including cross-group
transactions. The timestamp and the replication log are passed to the subscribing server. In delayed
replication, the subscribing server uses the timestamp to calculate when to perform database
updates.
The timestamp is carried with the replication log its whole cycle, regardless of failover. After failover,
logs generated in the original publisher can be sent back during the sync. It follows the same delay
time period rule at runtime. During the failover, a FAILOVER_END log is generated at the subscriber.
This log is sent back during sync after the failover. This log is the only log that does not follow the
delay time period rule, and is handled by replication writer processes immediately, no matter whether
a delay time period is defined.

Replication manager daemon (repmanager)

The replication manager, which runs on each publishing server and subscribing server, performs the
following tasks:
▪ Reads and loads replication configuration information when the database starts
▪ Creates replication processes for each replication group
▪ Monitors and controls replication processes
▪ Responds to commands from ud_repadmin and XAdmin
▪ Reconfigures the replication environment
▪ Manages failover replication, recovery, and data synchronization of replication data

Note: The repmanager process is often referred to as RM in messages recorded in the rm.log and
rm.errrlog files.

The cleanupd daemon

The clean up daemon, cleanupd, detects terminated user processes at check time intervals. If
cleanupd detects a terminated process, internal flags are set. The smm daemon periodically checks
to see if cleanupd has set internal flags. If it detects flags, smm performs the necessary cleanup and
resets its own flag to zero. The cleanupd daemon performs clean up that is not handled by smm.

399
Appendix D: Daemon processes

When the smm daemon has reset its flag to zero, the cleanupd daemon resets its flag to zero, makes
the user process ID available, and frees the local control table.
The cleanupd daemon is started when UniData starts.

The cleanupd.config file

You can specify the parameters that determine how frequently the cleanupd daemon runs in the
cleanupd.config file, located in the $UDTHOME directory.
The following table describes the parameters stored in the cleanupd.config file.

Parameter Description
start Used to determine when to start the cleanupd daemon.
▪ 0 - does not start the cleanupd daemon when the server starts.
▪ 1 - start the cleanupd daemon when the server starts.
timer The number of seconds the cleanupd daemon waits before check for
terminated processes.
res The resolution strategy parameter is historical to the UniData dead lock daemon
(dlockd) and not applicable to the cleanupd daemon.
log The full path to the cleanupd log file. If no file is specified, the log file name
used is cleanupd.log.

Stop and restart the database so that the changes take effect.

cleanupd command
The cleanup command forces a clean up of resources owned by a terminated process. To run the
cleanup command, you must be a UniData administrator or the user that has the same user number
as the terminated process.

Syntax
cleanupd {[-t time] [-l location]} | {-c} | {-stop}

Parameters
The following table describes each parameter of the syntax.

Parameter Description
-t time The interval time (in seconds) to have the cleanupd daemon check for dead
processes. The default is 15 seconds.
-l location The location of the cleanupd log file. The default location is uvhome/
uvcleanupd.log.
-c Instructs the cleanupd daemon to use the parameters that are defined
in the cleanupd.config file on startup. When -c is specified, no other
options can be used.
-stop Stops the cleanupd daemon while UniData is running.

400
 Starting UniData daemons

Note: If the cleanupd daemon is cleaning up a terminated rw process, the information logged
in the cleanupd.log file will contain additional information regarding the replication log being
processed. This can be helpful in diagnosing unexpected rw terminations.

Starting UniData daemons

Use one of the following commands to start the UniData daemons:
▪ -admin -start [-init]
▪ rc start [init]
Specify the -init option to clear the pending replication logs saved to synchronize the subscriber
database. Use this option for initial startup or after refreshing a subscriber database.

Note: Care should be taken when using the -init option, as improper use might cause the
subscriber to be out of sync with the publisher.

Stopping UniData daemons

Use one of the following commands to stop the UniData daemons:
▪ -admin -stop [-force]
▪ rc stop [force]
These commands check whether any users are still logged on to the system. If users are logged on, the
system is not stopped. If you specify the -force option, the system is stopped even if users are still
logged on.

Displaying UniData daemons

On UNIX systems, use the show command to display a list of daemon processes currently running on
the system. The following example illustrates output from the show command:
% /shire3/uv113/bin/showuv
USER PID TIME COMMAND
root 307326 0:00 /shire3/uv113/../unishared/unirpc/unirpcd
root 532674 0:01 /shire3/uv113/bin/uvcleanupd -t 15
root 618668 0:00 /shire3/uv113/bin/uvdlockd -config
root 549070 0:02 /shire3/uv113/bin/uvsmm -t 15Displaying smm
Use the sms command to display the contents of the shared memory segments.

Syntax
sms [options]

Options
The following table describes the options available for the sms command:

Option Description
-h Displays the shared memory segment header.
-G shm_id Displays the shared memory segment you specify with shm_id.

401
Appendix D: Daemon processes

Option Description
-g shm_no Displays the shared memory segment you specify with shm_no.
-L pid Displays the LCT entry you specify with pid.
-l lct_no Displays the LCT entry you specify with lct_no.
-S shm_id Displays the LCT entry of the session where the shared memory segment is
created.

Global control table

The global control table (GCT) manages shared memory segments system-wide. This table is located
in the shared memory management segment. Each GCT records the use of global pages in a shared
memory segment. UniData determines the number of GCTs in the CTL by the configuration parameter
SHM_GNTBLS. The SHM_GNTBLS parameter must not exceed the kernel parameter shmmni.

Local control tables

Each local control table (LCT) records the shared memory activity of a UniData process group.
UniData determines the number of LCTs in the CTL by the NUSERS configuration parameter. Each LCT
comprises four subtables:

Subtable name Description

PI Process information table. Each PI table registers all processes within a
process group.
CT Counter table. Each CT records information about the behavior of the process
group.
MI Memory information table. Each MI table records all global pages or self-
created shared memory segments used by the process group.
CI Control information table. Each CI table records all blocks allocated from
shared memory for temporary buffers.

A process group relates to a process group leader or a user executing a UniData system-level
command from a UNIX prompt.

Terminology
The following table describes the UniData executable names for U2 Data Replication for UniData.

Replication component Executable name

Shared memory manager smm
Stop shared memory stopsmm
management
Replication manager repmanager
Show sms information sms
Cleanup manager cleanupd
Publisher process pub
Subscriber process sub

402
 Terminology

Replication component Executable name

Replication writer rw
Publisher listener process publistener
Publisher synching tool pubsyncer
Replication manager RPC tool rmconn
Replication diagnosis tool reptool
Stop replication manager tool stoprm
Replication administration _repadmin
tool
Show UNIX daemon processes show
Show format processing psfmt
Test process ID test_pid
Show host information hostinfo

The next table describes the U2 Data Replication for UniData services names.

Replication service UniData service name

U2 replication service rep
Replication manager rmconn
connection service

The next table describes the U2 Data Replication for UniData daemon log files. These log files are
located in the $UDTHOME directory.

Log file File name

Shared memory manager log smm.log
file
Shared memory manager smm.errlog
error log file
Cleanup log file cleanupd.log
Cleanup error log file cleanupd.errlog
Replication manager log file rm.log
Replication manager error log rm.errlog
file
Publisher error log file pub<n>.errlog
Subscriber error log file sub<n>.errlog
Replication writer error log rw.errlog
file
Deadlock log file dlockd.log

403