Admn PDF

UniData
Administering UniData on
Windows NT or Windows
2000
Version 5.2
June 2000
Part No. 000-6795
Published by Informix Press
Informix Corporation
4100 Bohannon Drive
Menlo Park, CA 94025-1032
2000 Informix Corporation. All rights reserved. The following are trademarks of Informix Corporation
or its affiliates, one or more of which may be registered in the United States or other jurisdictions:
Answers OnLineTM; ArdentTM; AxielleTM; C-ISAM; Client SDKTM; CloudconnectorTM; CloudscapeTM; CloudsyncTM;
CloudviewTM; DataBlade; Data DirectorTM; Data MineTM; Data Mine BuilderTM; DataStage;
Decision FastStartTM; Decision for Telecommunications Campaign ManagementTM; Decision FrontierTM;
Decision Solution SuiteTM; DecisionscapeTM; DialogueTM; Dynamic Scalable ArchitectureTM; Dynamic ServerTM;
Dynamic Server.2000TM; Dynamic ServerTM, Developer EditionTM; Dynamic ServerTM with Advanced Decision
Support OptionTM; Dynamic ServerTM with Extended Parallel OptionTM; Dynamic ServerTM with MetaCube
ROLAP Option; Dynamic ServerTM with Universal Data OptionTM; Dynamic ServerTM with Web Integration
OptionTM; Dynamic ServerTM, Workgroup EditionTM; Dynamic Virtual MachineTM; Encrypt.CSMTM;
Enterprise Decision ServerTM; E-stageTM; FormationTM; Formation ArchitectTM; Formation Flow EngineTM;
Foundation.2000TM; Frameworks for Business IntelligenceTM; Frameworks TechnologyTM;
Gold Mine Data Access; i.DecideTM; i.Financial ServicesTM; i.FoundationTM; i.IntelligenceTM; i.ReachTM;
i.SellTM; Illustra; Informix; Informix 4GL; Informix COM AdapterTM;
Informix Enterprise Command CenterTM; Informix Extended Parallel ServerTM;
Informix Informed DecisionsTM; Informix InquireSM; Informix Internet Foundation.2000TM; InformixLink;
InformiXMLTM; Informix Red Brick Decision ServerTM; Informix Session ProxyTM; Informix VistaTM;
InfoShelfTM; Installation AssistantTM; InterforumTM; I-SpyTM; IterationsTM; J/FoundationTM; LUCIDTM;
MaxConnectTM; Media360TM; MediazationTM; MetaArchitectTM; MetaBrokerTM; MetaCube; MetaHubTM;
MetaStageTM; NewEraTM; O2 & DesignTM; O2 Technology & DesignTM; Object TranslatorTM; Office ConnectTM;
ON-BarTM; OnLine Dynamic ServerTM; OnLine/Secure Dynamic ServerTM; OpenCase; OrcaTM; PaVERTM;
Prism; Prism & DesignTM; RedBack; RedBeanTM; RedBeans & DesignTM; Red Brick and Design;
Red Brick Data MineTM; Red Brick Decision ServerTM; Red Brick Mine BuilderTM;
Red Brick DecisionscapeTM; Red Brick ReadyTM; Red Brick Systems; Regency Support;
Rely on Red BrickSM; RISQL; Server AdministratorTM; Solution DesignSM; STARindexTM; STARjoinTM;
SuperTerm; SuperView; SureStartTM; SystemBuilderTM; TARGETindexTM; TARGETjoinTM;
The Data Warehouse Company; UniData; UniData & Design; UniVerse;
Universal Data Warehouse BlueprintTM; Universal Database ComponentsTM; Universal Web ConnectTM;
ViewPoint; Virtual Table InterfaceTM; VisionaryTM; Web Integration SuiteTM; XML DataPortTM;
Zero Defect Data. The Informix logo is registered with the United States Patent and Trademark Office. The
DataBlade logo is registered with the United States Patent and Trademark Office.
Documentation Team: Claire Gustafson
GOVERNMENT LICENSE RIGHTS
Software and documentation acquired by or for the US Government are provided with rights as follows:
(1) if for civilian agency use, with rights as restricted by vendors standard license, as prescribed in FAR
12.212; (2) if for Dept. of Defense use, with rights as restricted by vendors standard license, unless
superseded by a negotiated vendor license, as prescribed in DFARS 227.7202. Any whole or partial
reproduction of software or documentation marked with this legend must reproduce this legend.
ii Administering UniData on Windows NT or Windows 2000
Contents
Chapter 1 - Introduction to UniData for Windows NT or

Windows 2000 ..................................................................................9
Audience ...................................................................................................10
Product Basis ............................................................................................11
Notes About Terminal Devices and Tape Drives .....................................19
Printing in UniData for Windows NT or Windows 2000 .........................21
Chapter 2 - Migrating Applications to UniData for Windows NT

or Windows 2000............................................................................23
Process Overview .....................................................................................24
UniData Migration Tools ..........................................................................26
Special Considerations for UniData SQL .................................................30
NT_SCOUT ..............................................................................................34
NT_CATALOG_MAP .............................................................................40
TAR2FTP ..................................................................................................42
convcode, convdata, convidx ....................................................................47
NT_UPDATE_PATHS .............................................................................50
NT_RECATALOGGER ...........................................................................52
Administering UniData on Windows NT or Windows 2000
SQL_UNIX_2_NT ....................................................................................53
Chapter 3 - Managing and Using the UDTelnet Service .............57

Introduction ...............................................................................................58
Overview of Features ................................................................................60
Configuring the UDTelnet Service ...........................................................62
Starting, Stopping and Pausing UDTelnet ................................................78
Chapter 4 - Managing and Using the UDSerial Service ..............81

Introduction ...............................................................................................82
Overview of Features ................................................................................84
Configuring the UniData Terminal Server ...............................................86
Starting and Stopping the UniData Terminal Server ..............................100
Chapter 5 - UniData and Services...............................................103

What Is a Service? ..................................................................................104
Principal UniData Services .....................................................................105
Monitoring UniData Services .................................................................109
Chapter 6 - UniData and Memory................................................ 113

Windows NT or Windows 2000 and Shared Memory ...........................114
UniData and Shared Memory .................................................................115
Chapter 7 - Configuring Your UniData System.........................129

Configuration Procedure .........................................................................130
Chapter 8 - Starting, Stopping, and Pausing UniData ..............139

Normal Operation ...................................................................................140
Pausing UniData .....................................................................................144
Additional Commands ............................................................................148
Chapter 9 - Managing UniData Accounts...................................155

What Is a UniData Account? ..................................................................156
Creating a UniData Account ...................................................................157
Deleting an Account ...............................................................................162
Clearing Space in UniData Accounts .....................................................163
Chapter 10 - Managing UniData Security...................................165

Customizing Permissions ........................................................................165
Customizing a VOC File .........................................................................170
Remote Items ..........................................................................................174
The SETFILE Command ........................................................................177
LOGIN and LOGOUT Paragraphs .........................................................178
UniData SQL Privileges .........................................................................181
Field-Level Security for UniQuery .........................................................182
Chapter 11 - Managing UniData Files .........................................189

UniData Hashed Files .............................................................................190
Static Hashed Files ..................................................................................191
Dynamic Hashed Files ............................................................................192
Sequentially Hashed Files .......................................................................204
DIR-Type Files .......................................................................................206
Multilevel Directory Files .......................................................................209
Index Files and Index Log Files .............................................................211
File-Handling Commands .......................................................................214
File Corruption ........................................................................................217
UniData Detection Tools ........................................................................220
UniData Recovery Tools ........................................................................232
Detection and Repair Examples ..............................................................240

How to Use guide ...................................................................................243
Error Messages .......................................................................................246
Chapter 12 - Managing UniData Locks.......................................253

The Global Lock Manager ......................................................................254
Locking in UniBasic ...............................................................................256
Resource Locks .......................................................................................259
Listing Locks ..........................................................................................260
Commands for Clearing Locks ...............................................................270
Procedure for Clearing Locks .................................................................273
Chapter 13 - Managing UniData Users .......................................275

Adding Users ..........................................................................................276
Monitoring User Processes .....................................................................281
Stopping User Processes .........................................................................283
Chapter 14 - Managing Printers in UniData ...............................285

Configuring and Troubleshooting a Printer ............................................286
Spooling From UniData ..........................................................................290
Creating a Form ......................................................................................301
Defining a Printer Unit in UniData .........................................................304
UniData Printing Commands ..................................................................318
Chapter 15 - Managing Cataloged Programs ............................321

UniBasic Source and Compiled Programs ..............................................322
Cataloging UniBasic Programs ...............................................................324
Managing Global Catalogs .....................................................................327
Listing Programs in Use .........................................................................336

Creating an Alternate Global Catalog Space ..........................................337
Chapter 16 - Managing and Using Tape Devices ......................343

UniData Tape Handling Commands .......................................................344
SETTAPE ...............................................................................................346
Steps for Tape Device Use ......................................................................348
Chapter 17 - CALLC and CallBasic ............................................353

Dynamic Link Libraries (DLLs) and UniData .......................................354
Calling External Routines From UniData ...............................................355
CALLC Example Programs ....................................................................361
Accessing UniData From an External Program ......................................373
Sample Programs ....................................................................................376
Steps for CallBasic ..................................................................................383
Chapter 18 - Monitoring and Tuning UniData ............................387

Monitoring Your Windows NT or Windows 2000 System ....................388
UniData Performance Factors .................................................................389
UniBasic Profiling ..................................................................................392
UniData Performance Monitoring ..........................................................396
ECL Process Monitoring Commands .....................................................407
Examples .................................................................................................410
Appendix A - UniData Configuration Parameters .....................413

Appendix B Environment Variables for UniData ............................................429
Index
Chapter 1 - Introduction
to UniData for Windows
NT or Windows 2000
The purpose of this manual is to collect, in a single book, as much information as possible about
activities needed to administer a UniData installation on Windows NT. This manual repeats some
information presented elsewhere in the UniData documentation set. Certain command descriptions
and examples have been amplified or modified in this manual to increase their usefulness to system administrators as opposed to end users.
Chapter 1 - Introduction to UniData for Windows NT or Windows 2000
Audience
Administering UniData is intended for people whose responsibilities include the following:
10
Tasks performed at the operating system level
Modifying file permissions
Adding users
Creating directories
Starting and stopping UniData
Backing up UniData files
Tasks performed within UniData
Creating and managing UniData accounts
Optimizing UniData configuration
Customizing security
Managing files
Monitoring and accessing files, peripherals, and system resources
Product Basis
Product Basis
UniData for Windows NT includes most of the features present in UniData for UNIX. However,
the following features are not supported on UniData for Windows NT or Windows 2000:
USAM
Recoverable File System (RFS)
Transaction Processing (TP)
Excluded Commands
The following commands are not supported on UniData for Windows NT or Windows 2000:
acctrestore
ACCT.SAVE
kp
nusers
shmconf
showud
smmtest
systest
udfile
udstat
udtinstall
Reserved Characters
UniData for Windows NT or Windows 2000 does not allow the use of the following characters in a
file or directory name:
(double quotation mark)
11
| (pipe sign)
* (asterisk)
/ (slash)
: (colon)
< (less than sign)
> (greater than sign)
? (question mark)
\ (backslash)
UDT.OPTIONS
You may use the reserved characters in a file specification. For instance,
C:\Informix\ud52\DEMO\INVENTORY is an acceptable file specification. The reserved
characters : and \ are used as delimiters in the file specification. However, they may not be used
within the name of a file or directory. DEM:O or INVEN\TORY are unacceptable.
If your application uses any of these characters in file or directory names, you need to substitute
other characters. See Chapter 2 - Migrating Applications to UniData for Windows NT or Windows 2000 for information about tools that locate these special characters within your accounts.
Case Sensitivity
Windows NT or Windows 2000 does not distinguish between uppercase and lowercase, except in a
users password, which is case sensitive. UniData is case sensitive. This difference creates a
number of impacts. See Chapter 2 - Migrating Applications to UniData for Windows NT or Windows 2000, for information about tools to report all instances in your file and record names where
case insensitivity could cause problems.
File Names
On Windows NT or Windows 2000, 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 NT or Windows 2000 will not allow both to exist.
12
Product Basis
Record Names
You cannot have two records in the same DIR or MULTIDIR file whose names are identical
except for case. The following screen illustrates one effect of this limitation:
Screen Example
: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 NT or Windows 2000
treats 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 name
X_filename and x_filename, respectively. On UniData for Windows NT or Windows 2000, the
index file and index log file a static hashed file are named X_FILENAME and L_FILENAME,
respectively.
13
Warning
The Windows NT or Windows 2000 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 NT or Windows
2000 machine, Windows NT or Windows 2000 may overwrite the first one you copied with the
second, and you could lose information. When you are migrating your application, consider
removing the index log files for your static files, or renaming them to the Windows NT or
Windows 2000 convention, before physically moving them to the Windows NT or Windows 2000
machine.
savedlists File
By default, a UniData account on UNIX contains a SAVEDLISTS file for saving SELECT lists,
and a savedlists file for storing temporary information for BY.EXP sorts.
At the operating system level, the file named savedlists on UniData for UNIX is called the
SAVEDLISTSL file on UniData for Windows NT or Windows 2000. However, the VOC file
contains an entry for savedlists pointing the correct file, so you should not have to modify your
application. You must change the name of the savedlists file in any UniData account you are
moving from UNIX to Windows NT or Windows 2000.
Symbolic Links
Windows NT or Windows 2000, unlike UNIX, does not support symbolic links. If your application
has identified files by using symbolic links at the operating system level, you must restructure your
UniData accounts to eliminate them. You can use environment variables in VOC pointers, or set
new pointers with SETFILE, just as you can in UniData for UNIX.
Phantom Command
On UniData for Windows NT or Windows 2000, the PHANTOM command behaves differently,
depending on where you execute it.
14
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.
Product Basis
Dynamic Files
The dynamic file implementation on UniData for Windows NT or Windows 2000 differs slightly
from the implementation on UniData for UNIX. On UniData for Windows NT or Windows 2000,
the parts of a large dynamic file must remain in the same partition where the file was created.
Because of this, the part table is not relevant to UniData for Windows NT or Windows 2000.
The size of each part file is limited by the configuration parameter MAX_FLENGTH in
udthome\include\udtconfig.
Deleting Files
Windows NT or Windows 2000 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.
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 NT or Windows 2000, only MS-DOS
commands can be executed with PCPERFORM. In some cases (for instance, the echo command)
there are MS-DOS commands named like the UNIX versions (although their behavior may differ
somewhat). In other cases (for instance, who, ls, ps) you must identify replacements. Refer to your
Windows NT, Windows 2000, and UNIX documentation for information about system-level
commands.
15
Note
UniData supplies a suite of tools to automate some application analysis tasks. You can use the
NT_SCOUT tool to report all instances of the PCPERFORM command in your UniBasic
programs, PROCS, and paragraphs. See Chapter 2 - Migrating Applications to UniData for Windows NT or Windows 2000 for information about NT_SCOUT.
Tip
If you are migrating your application to a Windows NT or Windows 2000 machine that has certain
third-party applications (for instance, the MKS Toolkit) installed, consider whether your
production system will have that software installed. MKS Toolkit and similar software products
provide a UNIX-like environment to help you with migration tasks. They include UNIX-like
commands that may not exist in MS-DOS or may function differently from the MS-DOS versions.
PCPERFORM executes the MS-DOS version of the command, provided a DOS version exists. If
no DOS version exists, PCPERFORM executes the third-party version. Make sure you test your
application in an environment that matches your production environment.
Shell Command Differences

echo
The MS-DOS echo command behaves differently from UNIX in the following ways:
16
Quotes are echoed. In UNIX, the command echo text displays the string text. In
MS-DOS, echo text displays text.
Product Basis
In MS-DOS, echo displays the input starting from one space after the command on the
command line, as shown in the following example:
Warning
In UNIX, the three commands in the example are equivalent. If your application depends
on comparing the output from echo to another string, make sure your echo command is
formatted correctly.
If you direct the output to a file, echo displays everything between its starting point and
the redirection character (>). The two commands echo abc>file and echo abc >file, equivalent on UNIX, are not equivalent on Windows NT or Windows 2000. The second command produces a 4-character string, with a space as the fourth character.
17
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, as shown in the following example:
On UNIX, the command line entry would echo the string abc to the file named file, then attempt to
execute the dir command.
18
Notes About Terminal Devices and Tape Drives
Notes About Terminal Devices and Tape Drives

This sections discusses terminal and tape devices.
Terminal Devices
UniData for Windows NT or Windows 2000 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 NT or Windows 2000:
Screen Example
: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
NUMBER
0
STATUS
UDTNO
ASSIGNED
65
USER
NAME
terric
CHANNEL
NAME
ASSIGNED
BLOCKSIZE
\\.\tape0
4096
The device identifier \\.\TAPE0 indicates the current server (.), device TAPE0.
19
You can identify a disk file as a tape device by entering a path and filename (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.
Permissions
You must log in as a member of the Administrators group to define a tape device with the
SETTAPE command.
20
Printing in UniData for Windows NT or Windows 2000
Printing in UniData for Windows NT or Windows

2000
Windows NT and Windows 2000 allow users to print to printers (which are simply drivers that
control print devices). A printer may control a network print device or a local print device.
Microsoft applications, through their own print menus, allow users to 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 NT or Windows 2000 spooler allows users to
write data, including device-specific escape sequences to a print device (RAW mode), or to
incorporate pre-defined printing options (WINDOW) mode. Within a UniData session, the
SETPTR command identifies a print unit with a default spooler mode of RAW. If the output from
your application contains escape sequences for formatting, you do not need to specify printing
options when you define a print unit with SETPTR. If you are not using escape sequences, you can
specify printer options in a quoted string on the SETPTR command line. UniData then passes that
information to the Windows NT or Windows 2000 spooler.
21
22
Chapter 2 - Migrating
Applications to UniData for
Windows NT or Windows 2000
This chapter describes the process for moving a UniData application from a UNIX platform,
where the application is installed and running, to a Windows NT or Windows 2000 platform. The
chapter describes how to use the migration tools provided with UniData for Windows NT or
Windows 2000.
Tip
Informix strongly recommends you read this entire chapter before you begin migrating your
application.
23
Chapter 2 - Migrating Applications to UniData for Windows NT or Windows 2000
Process Overview
This overview presents a high-level view of the migration process. The remainder of the chapter
describes the tools in detail. The process sequence follows:
1. After you install UniData for Windows NT or Windows 2000, copy the tools from Windows
NT or Windows 2000 to UNIX. The directory udthome\NTMIGRATE contains the UniBasic
tool programs NT_scout, NT_CATALOG_MAP, Tar2ftp, SQL_UNIX_2_NT, and
NT_UPDATE_PATHS, and also contains input files needed for the programs. For more
information about these programs, see UniData Migration Tools in this chapter.
2. Complete these UNIX steps in the following order for each UniData account:
Run NT_scout in the account to identify migration items. Resolve migration items that
would cause data loss. This is a required step. For more information, see
NT_SCOUT in this chapter.
Run NT_CATALOG_MAP in the account to create a VOC paragraph that compiles

and catalogs UniBasic programs on Windows NT or Windows 2000. This is an
optional step. You may recompile and catalog programs manually if you prefer. For
more information, see NT_CATALOG_MAP in this chapter.
Run Tar2ftp in the account to create a script for moving the programs and data files to
Windows NT or Windows 2000 via FTP. This is an optional step. You can move the
account via tape or FTP the account manually, if you prefer. For more information, see
TAR2FTP in this chapter.
Move the FTP script (output from Tar2ftp) to the Windows NT or Windows 2000
machine This is a required step only if you executed Tar2ftp.
3. Complete these Windows NT or Windows 2000 steps in the following order for each UniData
account:
24
Move the programs and data files from your UNIX machine. This is a required step.
Edit and use the output from Tar2ftp if you are using FTP. For more information, see
TAR2FTP in this chapter.
Convert machine format in programs, data and indexes. This is a required step if you
are migrating from a high-byte UNIX system AND you did not use Tar2ftp. For
more information, see convcode, convdata, convidx in this chapter.
Process Overview
Run NT_UPDATE_PATHS in the account to update paths in VOC entries. This ia a

required step. For more information, see NT_UPDATE_PATHS in this chapter.
Compile and catalog the application. This is a required step. If you executed
NT_CATALOG_MAP on UNIX, execute NT_RECATALOGGER. For more
information, see NT_RECATALOGGER in this chapter.
Convert the UniData SQL privilege table into Windows NT or Windows 2000 format.
This is a required step if the account is a UniData SQL account. For more
information, see SQL_UNIX_2_NT in this chapter.
4. After you have completed the sequence for each UniData account, begin testing your
application.
25
UniData Migration Tools

This section describes the tools UniData provides to migrate your application.
NTMIGRATE File
When you install UniData on your Windows NT or Windows 2000 system, the installation creates
a directory in your Informix UniData folder called NTMIGRATE, which contains a group of tools
to assist you with application migration tasks. The following table describes these tools.
Tool
Description
NT_SCOUT
UniBasic preprocessor. Run this program in each UniData account on

UNIX to identify migration issues.
ALT.ECL.CMDS
List of ECL commands that are known to be excluded on UniData for

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

UniData for Windows NT or Windows 2000. NT_SCOUT uses this
file to analyze your application.
RESERVED.CHARS
List of Windows NT or Windows 2000 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 NT or Windows 2000 machine
to FTP the contents of the UniData account.
NT_CATALOG_MAP
UniBasic program that builds a paragraph to catalog programs on

your Windows NT or Windows 2000 machine. Run this program in
each UniData account on UNIX. Execute the paragraph to catalog
your programs after moving to Windows NT or Windows 2000.
26
Tool
Description
NT_UPDATE_PATHS
UniBasic program that allows you to make global substitutions for

paths or sub-paths in VOC entries. Execute this program in each
UniData account after moving to Windows NT or Windows 2000.
BUILD.FULL.PATH
UniBasic subroutine used by NT_UPDATE_PATHS to generate

Windows NT or Windows 2000 style path specifications.
SQL_UNIX_2_NT
UniBasic program that converts a privilege table from UNIX style to

Windows NT or Windows 2000 style.
UniData Migration Tools (continued)
Copy the NTMIGRATE File

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

NTMIGRATE is a DIR-type file. You need to create its VOC entry and create a dictionary, as
shown in the following example:
Screen Example
:SETFILE NTMIGRATE NTMIGRATE
Establish the file pointer
Tree name
NTMIGRATE
Voc name
NTMIGRATE
Ok to establish pointer(Y/N) = Y
SETFILE completed.
:CT VOC NTMIGRATE
VOC:
NTMIGRATE:
DIR
27
NTMIGRATE
:CREATE.FILE DICT NTMIGRATE
Create file D_NTMIGRATE, modulo/1,blocksize/1024
Hash type = 0
Added "@ID", the default record for UniData to DICT NTMIGRATE.
Set Pointers to NTMIGRATE

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
screen:
Screen Example
:SETFILE /usr/ud52/demo/NTMIGRATE NTMIGRATE
Tree name
/usr/ud52/demo/NTMIGRATE
Voc name
NTMIGRATE
Dictionary name
/usr/ud52/demo/D_NTMIGRATE
SETFILE completed.
:CT VOC NTMIGRATE
VOC:
NTMIGRATE:
DIR
/usr/ud52/demo/NTMIGRATE
/usr/ud52/demo/D_NTMIGRATE
:
Compile the UniBasic Tools Programs

You must compile the following UniBasic programs in the NTMIGRATE file:
28
NT_SCOUT
BUILD.FULL.PATH
TAR2FTP
NT_CATALOG_MAP
Note
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 NT or Windows 2000 platform.
29
Special Considerations for UniData SQL

The UniData migration tools can move all components of a UniData SQL account from UNIX to
Windows NT or Windows 2000. 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 Windows NT or Windows 2000 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 may encounter difficulties if you rename one or more
data or dictionary files to resolve naming conflicts. Naming conflicts arise because Windows NT
and Windows 2000 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 Windows NT or Windows 2000.
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 Windows
NT or Windows 2000.
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. Informix recommends you perform these steps before
you move the account to Windows NT or Windows 2000. The following example shows the error
message generated when a catastrophic problem affects UniData SQL:
30
Screen Example
...
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 Windows NT or Windows 2000. 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
NT or Windows 2000.
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 NT and Windows 2000. The following example shows a
UNIX style privilege table:
Screen Example
:SORT privilege ALL
SORT privilege ALL 11:05:29 Feb 12 2000 1
privilege................. access.. field..... grant_op grantor... grantee...
0*&MAP&
0*&report&
0*CATEGORIES
.
.
.
1026*RENTALS
1026*TRIAL_VIEW1
1026*TRIAL_VIEW2
.
.
.
PUBLIC*MENUFILE
ALL
ALL
ALL
1
1
1
root
root
root
OWNER
OWNER
OWNER
ALL
PUBLIC
PUBLIC
PUBLIC
PUBLIC
PUBLIC
PUBLIC
root
31
PUBLIC*RENTALS
PUBLIC*STAFF
ALL
ALL
0
0
user01
root
Notice the UNIX style identifiers: 1026, user01, root.
Tip
Refer to the UniData SQL Commands Reference and Using UniData SQL for information about
the privilege table.
The migration tool SQL_UNIX_2_NT creates a Windows NT or Windows 2000 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 NT 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 NT machine)
All privileges granted to PUBLIC on the UNIX side are retained for PUBLIC on the
Windows NT or Windows 2000 side.
Privileges granted to individual users on the UNIX side are not migrated to Windows NT or
Windows 2000. 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 Windows
NT or Windows 2000. You will still need to convert the privilege table to Windows NT or
Windows 2000 style, but there should be no impact at all to users.
32
The following example shows some entries in a Windows NT or Windows 2000 style privilege
table that was generated from a UNIX style table:
Screen Example
:SORT privilege ALL
SORT privilege ALL 12:28:14 Feb 20 2000 1
&MAP&
&report&
CATEGORIES
COURSES
.
.
.
PUBLIC*__V__VIEW
PUBLIC*privilege
PUBLIC*voc
OWNER
OWNER
OWNER
OWNER
ALL
ALL
ALL
PUBLIC
PUBLIC
PUBLIC
PUBLIC
0
0
0
ADMINISTRATORS
ADMINISTRATORS
ADMINISTRATORS
52 records listed
:
33
NT_SCOUT
The NT_SCOUT program evaluates a UniData UNIX account and identifies areas that need
attention before you move the account to Windows NT or Windows 2000. NT_SCOUT detects
and reports:
Case-sensitive file names.
Case-sensitive record names in DIR type files.
Reserved characters in file names (including record names in DIR type files). NT_SCOUT
uses the list of reserved characters in the RESERVED.CHARS record.
UniBasic commands that may behave differently on Windows NT or Windows 2000.

NT_SCOUT uses the list of UniBasic commands in the ALT.BP.CMDS record.
ECL commands that are excluded or may behave differently on NT. NT_SCOUT uses the
list of ECL commands in the ALT.ECL.CMDS record.
VOC entries without corresponding files.
NT_SCOUT runs with a GLOBAL or a LOCAL option. The following table describes the options.
Option
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 accound, regardless of
physical location.
NT_SCOUT Options
34
NT_SCOUT
Output
NT_SCOUT creates three entries in the _HOLD_ file of the current account. The following table
describes NT_SCOUT output.
Output
Description
UNIX_NT_CATASTROPHIC
List of findings that you should address before moving this

account to Windows NT or Windows 2000. 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 Windows NT or Windows 2000. These findings may cause run-time errors or unexpected results from
your application programs.
UNIX_NT_SUMMARY
List of all findings from NT_SCOUT.

NT_SCOUT Output
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 wish).
Stores a UNIX text file called exclude.files, which lists program files in the current
account that you do not want to preprocess. If you want to exclude program files, you must
create both NTMIGRATE.LOC and exclude.files before you execute NT_SCOUT.
35
Using NT_SCOUT
The following sections describe how to use the NT_SCOUT program.
Create exclude.files (Optional)

Before you execute NT_SCOUT in each account, decide if there are program files in the account
that you do not want to preprocess. If there are, create the NTMIGRATE.LOC file and then create
exclude.files, as shown in the example:
Screen Example
:CREATE.FILE DIR NTMIGRATE.LOC
Create DIR type file NTMIGRATE.LOC.
Create file D_NTMIGRATE.LOC, modulo/1,blocksize/1024
Hash type = 0
Added "@ID", the default record for UniData to DICT NTMIGRATE.LOC.
:AE NTMIGRATE.LOC exclude.files
Top of New "exclude.files" in "NTMIGRATE.LOC".
*--: I
001= TESTPROGS
*--: FI
Filed "exclude.files" in file "NTMIGRATE.LOC".
:
Execute NT_SCOUT
Execute NT_SCOUT from the ECL prompt, as shown in the following example:
Screen Example
:RUN NTMIGRATE NT_SCOUT GLOBAL
Info
-- The following LOCAL program files won't be checked
/PRODUCT_INFO/TERRIC/ACCOUNT/TESTPROGS
36
CATASTROPHIC
-- Directory/file name conflict in 'D_Student'

Name conflicts with 'D_STUDENT'
CATASTROPHIC
NT_SCOUT

Warning -- In the file 'BP' record 'TIMETEST1'
OS commands may act different on NT
Contains the command 'PCPERFORM' and may function differently on NT
Line # 5 PCPERFORM "$UDTBIN/convhash CONVHASH.TEST"
Warning -- In the file 'VOC' record 'denat'
Contains the command 'DENAT' and may function differently on NT
Line # 2 HDENAT.MENU
Total Warning messages 5
Total CATASTROPHIC messages 2
Do you want to build the FTP script?N
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.
37
Correct All CATASTROPHIC Items

Print the output files from NT_SCOUT. UNIX_NT_CATASTROPHIC lists the findings you need
to address before moving data files and programs to NT. The following example shows a sample
UNIX_NT_CATASTROPHIC:
Screen Example
% more UNIX_NT_CATASTROPHIC
Info
-- The following LOCAL program files won't be checked
/PRODUCT_INFO/TERRIC/ACCOUNT/TESTPROGS
CATASTROPHIC
-- Directory/file name conflict in 'D_Student'

Name conflicts with 'D_STUDENT'
CATASTROPHIC

Total CATASTROPHIC messages 2
Before you move your programs and data files to Windows NT or Windows 2000, 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
38
NT_SCOUT
to the success of your migration to Windows NT or Windows 2000. Refer to your UniData
manuals and your UNIX, Windows NT, or Windows 2000 documentation to help you determine
the best ways to resolve these items.
Analyze WARNING Items

You can resolve WARNINGS (listed in UNIX_NT_WARNING) on either the UNIX or the NT
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 Windows NT or Windows 2000. 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 NT or
Windows 2000 machine.
Tip
The Warnings report can be very large. Some items are not problems; for instance, you will see a
message for every instance of the SETPTR command, but you do not need to change them unless
you used unsupported options. The more you have depended on the underlying operating system
(using PCPERFORM for instance), the larger your conversion effort will be.
Back Up the Account

Consider creating and verifying a full backup of your UniData account at this time. A backup is
particularly advisable if you have expended a lot of effort resolving migration items.
39
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 Windows NT or Windows 2000.
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
Windows NT or Windows 2000, 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:
Screen Example
:CT VOC NT_RECATALOGGER
VOC:
NT_RECATALOGGER:
PA
DISPLAY Compiling programs
DISPLAY Now compiling file BP
BASIC BP NUM_TST
BASIC BP BASIC_STATIC
BASIC BP TIMETEST1
BASIC BP TIMETEST2
DISPLAY
CATALOG
CATALOG
CATALOG
:
40
Now cataloging file BP

BP TIMETEST1 LOCAL FORCE
BP _NUM_TST DIRECT FORCE
BP _BASIC_STATIC DIRECT FORCE
NT_CATALOG_MAP
Using NT_CATALOG_MAP
Execute NT_CATALOG_MAP from the ECL prompt, as shown in the following example:
Screen Example
:RUN NTMIGRATE NT_CATALOG_MAP
No data retrieved from current (S)SELECT statement.

BP
:
Reminder
You need to recompile and recatalog your application on Windows NT or Windows 2000, 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.
41
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 Windows NT or Windows 2000, edit the file, and use FTP to copy the
programs and data files from UNIX to Windows NT or Windows 2000.
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:
Screen Example
:!more NTMIGRATE.LOC/tar2ftp.out
#unix acct name
#password
bin
!mkdir ACCOUNT
!mkdir ACCOUNT\SAVEDLISTS
!mkdir ACCOUNT\TESTPROGS
!mkdir ACCOUNT\SAVEDLISTSL
!mkdir ACCOUNT\_PH_
!mkdir ACCOUNT\_HOLD_
!mkdir ACCOUNT\BP
!mkdir ACCOUNT\CTLG
!mkdir ACCOUNT\NTMIGRATE
!mkdir ACCOUNT\AE_SCRATCH
!mkdir ACCOUNT\__MASTER_TABLE
!mkdir ACCOUNT\NTMIGRATE.LOC
get /product_info/terric/ACCOUNT/VOC ACCOUNT\VOC
get /product_info/terric/ACCOUNT/D_VOC ACCOUNT\D_VOC
get /product_info/terric/ACCOUNT/D_SAVEDLISTS ACCOUNT\D_SAVEDLISTS
get /product_info/terric/ACCOUNT/_PH_/O_TIME ACCOUNT\_PH_\O_TIME
get /product_info/terric/ACCOUNT/D__PH_ ACCOUNT\D__PH_
.
.
.
get /product_info/terric/ACCOUNT/STUDENT2 ACCOUNT\STUDENT2
42
TAR2FTP
get /product_info/terric/ACCOUNT/D_NTMIGRATE.LOC ACCOUNT\D_NTMIGRATE.LOC

get /product_info/terric/ACCOUNT/D_TESTPROGS ACCOUNT\D_TESTPROGS
get /product_info/terric/ACCOUNT/D_STUDENT2 ACCOUNT\D_STUDENT2
!convcode ACCOUNT
!convdata -r ACCOUNT
:
The output file contains:
Placeholders (lines beginning with #) where you will add your UNIX login ID and
password
Commands in FTP format to create necessary subdirectories in Windows NT or Windows

2000 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 Windows NT or Windows 2000
Using TAR2FTP
The following sections describe how to use the TAR2FTP program.
Execute TAR2FTP
Execute TAR2FTP from the ECL prompt, as shown in the following example:
Screen Example
:RUN NTMIGRATE TAR2FTP
.
.
.
../ACCOUNT/NTMIGRATE.LOC/tardir
../ACCOUNT/NTMIGRATE.LOC/tarhash
../ACCOUNT/D_TAPES
../ACCOUNT/TAPES
../ACCOUNT/D_TESTFILE
../ACCOUNT/TESTFILE
../ACCOUNT/D_DV_STUDENT_1
../ACCOUNT/D_DV_TEST1
../ACCOUNT/STUDENT2
43
../ACCOUNT/D_NTMIGRATE.LOC
../ACCOUNT/D_TESTPROGS
../ACCOUNT/D_STUDENT2
Now reprocessing tar to ftp format
:
Reminder
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.
Move TAR2FTP Output to Windows NT or Windows 2000

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

At minimum, you need to edit two lines in this file. At the top of the file, replace the lines
beginning with # by a UNIX user id and a UNIX password for the machine where the account
currently exists. Use the DOS editor or Notepad to edit the lines in the file.
If you want to transfer files that were not included in tar2ftp.out (for instance, data files physically
outside the account directory), you can add lines to include them at this time. If you want to move
only a portion of the contents of the account directory, you can remove lines from tar2ftp.out.
Tip
Review tar2ftp.out carefully. If you are adding additional files, notice that you need to add
commands to create necessary directories and subdirectories.
44
TAR2FTP
The following example shows a typical tar2ftp.out, with a UNIX login and password as the first
two lines:
Screen Example
% more tar2ftp.out
user01
x17abcq
bin
!mkdir ACCOUNT
!mkdir ACCOUNT\SAVEDLISTS
!mkdir ACCOUNT\TESTPROGS
!mkdir ACCOUNT\SAVEDLISTSL
!mkdir ACCOUNT\_PH_
!mkdir ACCOUNT\_HOLD_
!mkdir ACCOUNT\BP
!mkdir ACCOUNT\CTLG
!mkdir ACCOUNT\NTMIGRATE
!mkdir ACCOUNT\AE_SCRATCH
!mkdir ACCOUNT\__MASTER_TABLE
!mkdir ACCOUNT\NTMIGRATE.LOC
get /product_info/terric/ACCOUNT/VOC ACCOUNT\VOC
get /product_info/terric/ACCOUNT/D_VOC ACCOUNT\D_VOC
get /product_info/terric/ACCOUNT/D_SAVEDLISTS ACCOUNT\D_SAVEDLISTS
.
.
.
get /product_info/terric/ACCOUNT/D_TAPES ACCOUNT\D_TAPES
get /product_info/terric/ACCOUNT/TAPES ACCOUNT\TAPES
get /product_info/terric/ACCOUNT/D_TESTFILE ACCOUNT\D_TESTFILE
get /product_info/terric/ACCOUNT/TESTFILE ACCOUNT\TESTFILE
get /product_info/terric/ACCOUNT/D_DV_STUDENT_1 ACCOUNT\D_DV_STUDENT_1
get /product_info/terric/ACCOUNT/D_DV_TEST1 ACCOUNT\D_DV_TEST1
get /product_info/terric/ACCOUNT/STUDENT2 ACCOUNT\STUDENT2
get /product_info/terric/ACCOUNT/D_NTMIGRATE.LOC ACCOUNT\D_NTMIGRATE.LOC
get /product_info/terric/ACCOUNT/D_TESTPROGS ACCOUNT\D_TESTPROGS
get /product_info/terric/ACCOUNT/D_STUDENT2 ACCOUNT\D_STUDENT2
!convcode ACCOUNT
!convdata -r ACCOUNT
45
Execute the FTP Command

Use the -s argument to supply the input file, as shown in the following example:
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 in this chapter for more information about these commands.
Note
The script always runs convcode and convdata, even if the machine format conversion is not
needed. There is no harm in executing the commands in any case, but if you know you are
migrating from a low byte machine, you can delete the commands from tar2ftp.out.
46
convcode, convdata, convidx

Purpose
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 Windows NT or Windows
2000, and
You did not use TAR2FTP.
See the UniData Commands Reference for information about these three commands.
Using convcode, convdata, and convidx

Reminder
If you copied your files and data with an FTP script created by the TAR2FTP program, you do not
need to execute convcode or convdata. The FTP script executes the commands for you.
47
Execute these commands in each UniData account after you move the programs and files to
Windows NT or Windows 2000. The following screens show output from the commands. For
these examples, a modified demo database was migrated from an HPUX platform to Windows NT
or Windows 2000. The first example shows output from convdata, run with the -r (recursive)
option:
48
The next example shows the output from convcode:
The next example shows the output from convidx:
49
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 Windows NT or Windows 2000. The program displays
UNIX directory paths from VOC entries and allows you to enter the appropriate Windows NT or
Windows 2000 path. NT_UPDATE_PATHS then updates the VOC entries for the correct paths,
converting UNIX-style slashes to Windows NT or Windows 2000-style during the update. The
NT_UPDATE_PATHS program calls the UniBasic subroutine BUILD.FULL.PATH to create
Windows NT or Windows 2000-style path identifiers.
Using NT_UPDATE_PATHS
Execute NT_UPDATE_PATHS in your UniData accounts after you move the accounts and, if
needed, converted machine formats.
Reset the VOC Pointer for NTMIGRATE

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

In your UniData account, change the VOC pointer to the CTLGTB file so that it points to the
correct location on your Windows NT or Windows 2000 machine (udthome\sys, by default).
Warning
If you do not update the pointer to CTLGTB, NT_UPDATE_PATHS cannot execute.
Compile NT_UPDATE_PATHS
You need to compile this UniBasic program on your Windows NT or Windows 2000 machine, as
shown in the following example:
50
NT_UPDATE_PATHS
Screen Example
:BASIC NTMIGRATE NT_UPDATE_PATHS
Compiling Unibasic: \UNIDATA\NTMIGRATE\NT_UPDATE_PATHS in mode 'u'.
compilation finished
:
Execute NT_UPDATE_PATHS
Execute this UniBasic program from the ECL prompt, as shown in the following example:
Screen Example
:RUN NTMIGRATE NT_UPDATE_PATHS
NT_UPDATE_PATHS
15:47:55 Feb 11 1999
The current file ID is savedlists

The current path is 'SAVEDLISTSL'
The path should be
Press enter to accept existing path or 'D'elete pointer

current working path is D:\users\test\demo
Note
NT_UPDATE_PATHS compiles and catalogs a called subroutine named BUILD.FULL.PATH,
which UniData uses to update the VOC pointers in your account.
51
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 Windows NT to recompile and recatalog your application.
Using NT_RECATALOGGER
You cannot run NT_RECATALOGGER on Windows NT or Windows 2000 unless you executed
NT_CATALOG_MAP on UNIX. Run NT_RECATALOGGER after you move your account,
convert machine type (if needed), and run NT_UPDATE_PATHS.
Execute NT_RECATALOGGER from the ECL prompt, as shown in the following example:
Screen Example
:NT_RECATALOGGER
Compiling programs
Now compiling file BP
Compiling Unibasic: BP\NUM_TST in mode 'u'.
Basictype is changed, BP\NUM_TST is compiling in mode 'p'
Compiling Unibasic: BP\BASIC_STATIC in mode 'u'.
Compiling Unibasic: BP\TIMETEST1 in mode 'u'.
Compiling Unibasic: BP\TIMETEST2 in mode 'u'.
Now cataloging file BP
:
52
SQL_UNIX_2_NT
SQL_UNIX_2_NT
SQL_UNIX_2_NT is a UniBasic program that creates a Windows NT or Windows 2000-style
privilege table from a UNIX style privilege table. In the Windows NT or Windows 2000-style
table, the OWNER for all items is ADMINISTRATORS (the local Administrators group on the
Windows NT or Windows 2000 machine). 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 NT or Windows 2000, 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 NT
or Windows 2000, UniData SQL uses the UniBasic SYSTEM(515) function to detect the localized
name that corresponds to Administrators, and uses that group when creating records in the
privilege table.
Using SQL_UNIX_2_NT
Execute SQL_UNIX_2_NT after you complete the remainder of the migration steps.
53
Compile SQL_UNIX_2_NT
Compile the UniBasic program, as shown in the following example:
Screen 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
Run SQL_UNIX_2_NT
Execute the command at the ECL prompt, as shown in the following example:
Screen 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.
54
SQL_UNIX_2_NT
Review the Results

You can display the contents of privilege and of unix_privilege, as shown in the following
example:
Screen Example
:SORT privilege ALL
SORT privilege ALL 12:51:47 Jun 15 1999 1
SQLColumns
SQLSpecialC
olumns
SQLStatisti
cs
SQLTables
STATES
STUDENT
STUDENT_1
TAPES
.
.
.
PUBLIC*sysobjects
PUBLIC*sysprotects
PUBLIC*sysusers
OWNER
OWNER
PUBLIC
PUBLIC
OWNER
PUBLIC
OWNER
OWNER
OWNER
OWNER
OWNER
PUBLIC
ALL
ALL
ALL
0
0
0
ADMINISTRATORS
ADMINISTRATORS
ADMINISTRATORS
27 records listed
:SORT unix_privilege ALL USING DICT privilege
SORT unix_privilege ALL USING DICT privilege 12:52:08 Jun 15 1999 1
1026*SQLColumns
1026*SQLSpecialColumns
1026*SQLStatistics
1026*SQLTables
1026*STATES
1026*STUDENT
1026*STUDENT_1
1026*TAPES
.
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
PUBLIC
PUBLIC
PUBLIC
PUBLIC
55
.
.
PUBLIC*sysobjects
PUBLIC*sysprotects
PUBLIC*sysusers
27 records listed
:
ALL
ALL
ALL
0
0
0
terric
terric
terric
Note
The examples were generated using an English-language version of Windows NT or Windows
2000.
Remember the following points:
56
Privileges granted to PUBLIC on the UNIX system are unchanged on the Windows NT or
Windows 2000 system.
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 NT or Windows 2000 system 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.
Chapter 3 - Managing
and Using the UDTelnet
Service
The UniData Telnet Service (UDTelnet) enables multiple users to log in to a single Window NT
system to run UniData. With the UniData Telnet Service installed and started, your Windows NT
or Windows 2000 system exports a login prompt to its network so that network users can log in
and run UniData.
57
Chapter 3 - Managing and Using the UDTelnet Service
Introduction
The UniData Telnet Service is a service that exports a login prompt to a network. Users can log in
via the login 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 via UDTelnet, UniData writes screen output directly to a
socket. Using the socket is more efficient than writing screen output to the alternate console
window.
When a user shells out from UniData to execute a non-UniData process (for instance, !DIR),
UniData directs output to the alternate console window. This allows programs that write to
standard output to function without modification under UDTelnet.
Requirements for the UDTelnet Service

This sections describes the requirements for the using the UDTelnet service.
Operating System
Your system must be running Windows NT 4.0 or greater, and have UniData Admin installed.
UDTelnet runs with Windows NT or Windows 2000 Server and Windows NT or Windows 2000
Workstation.
Disk Space
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 \Informix\ud52\bin folder.
Memory
The UniData Telnet service and configuration screens take less than one megabyte of system
memory to run. You need somewhat less than 1 MB of memory for every Telnet user logged into
your system, over and above the memory required for the application.
58
Introduction
Note
For users logging in via 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 via Telnet to run DOS
commands, the performance impact for a 100MHz Pentium processor is noticeable with 20 - 30
users logged in. In contrast however, this overhead is minimal for udt processes executing through
Telnet, because UniData writes are handled through a socket.
Telnet Client
You must have a Telnet client running on your Windows NT or Windows 2000 system. The
UDTelnet Service interacts with the existing Telnet client.
59
Overview of Features
This section describes the features of the UDTelnet Service.
Configurability
Permissions
You need to log in to the Administrator account or log in as a member of the local Administrators
group to configure the UDTelnet Service.
Through UniData Admin, you can perform the following tasks to configure the UDTelnet
Service:
Establish a default configuration for all users who access your system via 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 NT or
Windows 2000 command prompt. Users can log directly into UniData, or into a custom
application.
Security
Users cannot log in via the Telnet Service unless:
60
They have a valid login on the Windows NT or Windows 2000 workstation or domain.
They belong to a local group that has the user privileges Access this computer from
network and Log on locally assigned.
These constraints mean that users logged in via Telnet have only the permissions already
associated with their Windows NT system account, just as if they had logged in from the console.
Terminal Emulation
The UniData Telnet Service provides any terminal emulation supported by UniData. UniData uses
the udtermcap file to validate terminal settings. The udtermcap file, located in the
udthome\include directory, contains definitions for terminals supported within UniData. By
default, the UDTERMCAP file contains definitions for the following terminals:
VT100, VT200, VT300, VT400, 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 in via the Serial Terminal service (UDSerial) unless UDTelnet is installed and
running.
61
Configuring the UDTelnet Service

Permissions
You need to log in to the Administrator account or log in as a member of the local Administrators
group to configure the UDTelnet Service.
You configure the UniData Telnet Server through UniData Admin. Select one of the following
methods to access the Telnet Server dialog box from UniData Admin:
From the UniData Admin menu, click Configure, and then click UDTelnet Server.
From the UniData Admin window, double-click Configuration, and then double-click
UDTelnet Server.
From the UniData Admin toolbar, click the UDTelnet Server icon, as shown in the
following example:
UDTelnet Server
Icon
62
Regardless of the method you choose, the UDTelnet Server dialog box appears, as shown in the
following example:
The following table describes the three dialog tabs for Telnet Server.
Dialog Tab
Use
Service
Settings for maximum login attempts, telnet socket, prompt

domain, event logging level, and logon banner.
Console
Configuration settings for default console time slice, maximum

console wait time, and time slice increment.
Users
Allows you to specify a list of users that are allowed to connect to

your Windows NT or Windows 2000 system via UDTelnet.
Telnet Server Dialog Tabs
63
Service Options
Select the Service tab from the Telnet Server dialog box to view and edit parameters that govern
the operation of the UDTelnet Service. A dialog box similar to the following example appears:
Set Maximum Logon Attempts

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

Set the TCP/IP socket that the UDTelnet service should monitor for client connections.
The default value for Telnet Socket is 23. Informix recommends that you not change this unless
you have another service that requires socket 23.
64
Tip
In the TCP/IP protocol stack, certain sockets are reserved for specific services. The file
%systemroot%\system32\drivers\etc\services on your Windows NT or Windows 2000 system
contains a partial listing of reserved sockets, excerpted from Internet RFC1060. Use the listing as
an aid to identify available sockets.
Select Prompt Domain

Select the Prompt Domain checkbox if you want users to enter a domain name when they log in.
If you do not select this checkbox, users are not prompted for a domain name.
Determine Event Logging Level

Determine the level of event capturing you desire. You can capture errors, warnings, and
information. Choose the level by selecting the corresponding checkbox.
Note
To review the information you capture, from the Start menu, select Programs, then
Administrative Tools, and then click Event Viewer.
Specify Logon Banner

In the Logon Banner box, enter a message to display when a user successfully connects to
UDTelnet.
Starting, Stopping, and Pausing the Telnet Server

Click Start to start the Telnet Server. The Start button appears dimmed unless the service is
paused or stopped.
Click Stop to stop the Telnet Server. The Stop button appears dimmed unless the service is
running.
Click Pause to pause the Telnet Server. The Pause button appears dimmed unless the service is
running.
65
Click OK to save the new settings and exit the Telnet Server dialog box. Click Apply to save the
new settings and keep the Telnet Server dialog box open. Changed settings do not affect Telnet
sessions that are already started. New sessions started after the service parameters were changed
use the new parameters. Click Cancel to exit the Telnet Server dialog box without saving
changes.
Console Options
Note
The Console dialog box enables you to make some tuning changes that may affect performance
for users logging in via UDTelnet to execute MS-DOS commands. However, tuning the virtual
console does not impact UniData performance for UDTelnet users, because UniData processes
bypass the virtual console in favor of a named pipe.
When a UDTelnet user is running a task on a virtual console on the Windows NT or Windows
2000 system, the UDTelnet service monitors the virtual console screen buffer for changes to send
over Telnet to update the users screen. UDTelnet must monitor changes frequently enough that the
user experiences good response, but not so frequently that the monitoring itself causes the system
to slow down. To optimize these conflicting constraints, the UDTelnet service begins polling
frequently, and polls progressively less frequently when it does not detect screen activity. You can
tune the process by modifying the parameters in the Console portion of the Telnet Server dialog
box.
Note
Modifying the Console parameters can affect the performance, latency, and throughput of the
UDTelnet Service and of your Windows NT or Windows 2000 system as a whole. Evaluate
possible consequences before you modify any of the parameters.
66
The following example shows the Console dialog box:
Set Default Console Time Slice

The value you enter in the Default Console Time Slice box determines the initial monitoring
interval in milliseconds. The UDTelnet Service begins monitoring screen buffers at this interval.
The value you enter must be a number from 100 to 2000; the default is 500. Enter the value, or use
the Default Console Time Slice arrows to select the value.
Set Maximum Console Wait Time

The value you enter in the Maximum Console Wait Time box determines the monitoring interval
in milliseconds. The value you enter must be a number from 100 to 60,000; the default is 2000.
Enter the value, or use the Set Maximum Console Wait Time arrows to select the value.
67
Set Time Slice Increment

The value you enter in the Time Slice Increment dialog box determines the polling period
increase in milliseconds. The value you enter must be a number from 100 to 1000; the default is
1000. Enter the value, or use the Set Time Slice Increment arrows to select the value.
UDTelnet begins by polling at the Default Console Time Slice. If it does not detect screen
activity, it increases the polling interval by Time Slice Increment until it reaches Max Console
Wait Time. Whenever it observes screen activity, UDTelnet returns the polling period to the
Default Console Time Slice. In the previous example, UDTelnet begins by polling every 500
milliseconds. If no it does not observe activity, it increases the polling interval by 1000
milliseconds each time until it reaches a maximum of 2 seconds. As soon as it observes activity,
UDTelnet returns the polling interval to 500 milliseconds.
Note
Although you can tune the UDTelnet Console Parameters, the performance users experience is
largely determined by the capability of your Telnet client. If you are unable to resolve performance
problems by tuning the Console parameters, you need to switch to a different Telnet client.
Tuning Considerations
You can make UDTelnet more responsive by decreasing:
the Default Console Time Slice
the Time Slice Increment
the Max Console Wait Time
Warning
Informix does not recommend decreasing the Max Console Wait Time. This parameter controls
how many resources UDTelnet consumes when the user is doing nothing. Decreasing this
parameter offers little performance benefit, but carries a large resource cost.
You can make UDTelnet consume fewer system resources and minimize its impact on the
remainder of your system by increasing:
68
the Default Console Time Slice
the Time Slice Increment
the Max Console Wait Time
Note
If you make the Max Console Wait Time too large, users may believe that their process is hung.
Click OK to save the new settings and exit the Telnet Server dialog box. Click Apply to save the
new settings and keep the Telnet Server dialog box open. Changed settings do not affect Telnet
sessions that are already started. New sessions started after the service parameters were changed
use the new parameters. Click Cancel to exit the Telnet Server dialog box without saving
changes.
User Profiles
Select the Users tab to specify which users are allowed to connect to your system through
UDTelnet, and to create custom user profiles.
69
A dialog box similar to the following example displays when you click Users:
This dialog box enables you to specify a list of users that are allowed to connect to your Windows
NT or Windows 2000 system via UDTelnet. At installation, UDTelnet is started with a default configuration that allows any user who can access your Windows NT or Windows 2000 system from
the network to access the system via UDTelnet as well. This default behavior is acceptable in
many instances. However, administrators may wish to grant only certain users Telnet access, or to
create individual user profiles. The Users dialog box allows this flexibility.
Warning
If you remove the Default profile, no user can log in via UDTelnet unless you have created a
specific profile for the user.
70
Default User Profile

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

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

Enter the full path of the working directory to which you want to connect at login in the Startup
Directory box. In the default profile, this is set to the UniData demo account.
71
Specify Arguments
In the Command Line box, enter any arguments you want to pass to the default shell. In the
default configuration, this is blank.
Determine ANSI Version

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

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

Select the Prompt Directory check box if you want the user to select a working directory at login
time. By default, this check box is not selected.
Note
If you want one or more users to see the MS-DOS prompt on login, edit the user profile or profiles
so that the default shell is %systemroot%\system32\cmd.exe.
Click OK to return to the Telnet Server dialog box, or click Cancel to exit without saving
changes.
Customizing User Profiles

Complete the following steps to create a customized profile for a user.
72
1. Add a Profile
Click New to add a user profile. The following dialog box appears:
Enter the login name of the user, then click OK. Enter the login name only (for instance, user01).
Do not enter the domain name (for instance, do not enter ACCOUNTING\user01). When you
click OK, a dialog box similar to the following appears:
UniData populates the dialog elements with the values from the Default Configuration. Click
OK to accept those values, or edit one or more fields to customize the profile.
73
Reminder
If you deleted the Default profile, UniData displays a message when you attempt to add new user
profiles. You must enter all the configuration settings manually, since UniData cannot copy them
from the default profile.
2. Customize a Profile
To edit a profile, highlight the user name in the User box, then click Edit. Consider the following
points when customizing a user profile:
74
Specify a full path in the Default Shell box. You can use either drive letters or the
Universal Naming Convention (UNC) to specify the path.
By specifying the Startup Directory, you can direct different users to different startup
directories, even if they are using the same default shell.
You can allow users to choose their directory when they log in by selecting the Prompt
Directory check box.
If you do not know whether a particular terminal supports Version 3 Color, select the
ANSI Version 3.x check box. Test the terminal; if screen colors are not displayed
correctly, modify the user profile to clear the ANSI Version 3.x check box.
The following example shows a sample configuration that allows a user to log in via UDTelnet,
select a starting directory, and access the MS-DOS command prompt. The default startup directory
is C:\Informix\ud52\demo:
Changes to a users configuration are visible the next time the user logs in via UDTelnet.
Generated Profiles
If you selected Prompt Directory in your Default Profile, UniData creates a profile for each user
who would normally receive the default user profile. UniData creates the individual profiles the
first time a user chooses a startup directory different from the default. The generated profile uses
the same configuration settings as the default profile, with the exception of Startup Directory,
75
which is set to the directory chosen by the user when they log in. The following examples show the
effect of the Prompt Directory option. In the first example, the default user profile has Prompt
Directory selected:
The following example shows the appearance of the screen when a user logs in:
Screen Example
Path (C:\Informix\ud52\demo) : \Informix\ud52\claireg
76
Notice that the default path is C:\Informix\ud52\demo, and the user is selecting an alternate startup
directory, \Informix\ud52\claireg. Pressing ENTER starts a UniData session in
\Informix\ud52\claireg. This login session also creates a profile for the user, which you can view
or edit from the Telnet Server dialog box. The generated profile is shown in the following example:
The next time the user logs in via Telnet, the default path is changed, as shown in the following
example:
Screen Example
Path (\Informix\ud52\claireg) :
77
Starting, Stopping and Pausing UDTelnet

You can control the UDTelnet service from the UDTelnet Configuration dialog box or from the
Control Panel.
Note
Pause and Stop have the same functionality. Once a user logs in through Telnet, their process is not
affected by Pause or Stop. Pause and Stop both prevent additional users to log in via Telnet.
Controlling UDTelnet from UniData Admin

You can start, stop, or pause the UDTelnet Server Service from the Service tab in the Telnet
Server dialog box.
78
Click Stop to stop the UDTelnet Service. Users already logged in can continue to work,
but no additional users can log in via UDTelnet until you Start the service.
Click Start to start the UDTelnet service (if it is stopped) or continue the service (if it is
paused).
Click Pause to pause the UDTelnet service. Users already logged in can continue to work,
but no additional users can log in via UDTelnet until you Start the service.
Starting, Stopping and Pausing UDTelnet
Controlling UDTelnet from the Control Panel

You can start, stop, or pause the UDTelnet Service from the Control Panel. Select the Services
icon from the Control Panel, and scroll through the list of services to display UniData Telnet
Service. The Status column indicates whether the service is presently running, and the Startup
column indicates whether the service is started automatically when you start your system. The
following example shows the appearance of the Services window:
Notice the following points:
The UniData Telnet Service 5.2 is started.
The UniData Telnet Service starts automatically when you start your system. This is the
default configuration when you install UDTelnet.
You can click Stop or Pause to stop or pause the service. Click Startup to switch between
manual and automatic startup for the service.
79
Note
If you Pause the UniData Telnet Service from Control Panel, click Continue to resume the service.
This is a difference in the interface from the Telnet Server dialog box.
80
and Using the UDSerial
Service
The UniData Terminal Server (UDSerial) enables users to access UniData on a Windows NT or
Windows 2000 platform via a modem or an asynchronous terminal connected through one of the
Windows NT or Windows 2000 platforms 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 NT or Windows 2000 platform resides.
81
Chapter 4 - Managing and Using the UDSerial Service
Introduction
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 NT or
Windows 2000 system, any serial device connected to the Windows NT or Windows 2000 system
via UDSerial can have complete Telnet capabilities throughout the Windows NT or Windows 2000
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
Informix recommends you install UDSerial even if your immediate plans do not include accessing
UniData via 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
Your system must meet the following criteria to use the UniData Terminal Server.
Operating System
Your system must be running Windows NT 4.0 (or greater). UDTelnet runs with Windows NT or
Windows 2000 Server and Windows NT or Windows 2000 Workstation.
TCP/IP Protocol
Your system must have TCP/IP installed.
Note
Consult your Microsoft documentation for information about TCP/IP.
82
Introduction
Serial Ports
Your system must have one or more serial ports. These may be native ports built into the PC, or
multi-port cards (provided the cards have Windows NT or Windows 2000 drivers). UDSerial
functions with any serial device that is supported by Windows NT or Windows 2000.
Note
Consult your hardware documentation or hardware vendor if you are not sure whether a serial
device or serial port is supported by Windows NT or Windows 2000.
Disk Space
UDSerial uses less than one megabyte of disk space.
Memory
The UniData Terminal Server and configuration screens take less than one megabyte of system
memory to run. You need approximately 100Kb of additional memory for every UDSerial user
logged into your system, over and above the memory required for the application.
UDTelnet Service
To access UniData via UDSerial, you must also have the UniData Telnet Server (UDTelnet)
installed and running. UDSerial connects asynchronous terminals to Telnet via the UDTelnet
Service.
83
Security
Users cannot login via the Terminal Server unless:
They have a valid login on the Windows NT or Windows 2000 workstation or domain.
They belong to a local group that has the User Rights Access this computer from
network and Log on locally assigned.
Because of these constraints, users logged in via the terminal server have only the permissions
already associated with their Windows NT or Windows 2000 system account, just as if they had
logged in 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 NT or Windows 2000 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 NT or Windows 2000 system errors that
pertain to the Terminal Server.
84
Integration with UniData Telnet Service

Connecting the UniData Terminal Server with the UniData Telnet Service (UDTelnet) provides the
same functionality for users logged in via Telnet.
85
Configuring the UniData Terminal Server

Permissions
You need to log in as a member of your local Administrators group (or as the Administrator) to
modify the configuration settings for the UniData Terminal Server.
You configure the UniData Terminal Server through UniData Admin. Select one of the following
methods to access the Terminal Server dialog box from UniData Admin:
From the UniData Admin menu, click Configure, and then click UDSerial Server.
From the UniData Admin window, double-click Configuration, and then double-click
UDSerial Server.
From the UniData Admin toolbar, click the UDTelnet Server icon, as shown in the
following example:
UDSerial Server
Icon
86
Regardless of the method you choose, the Terminal Server dialog box appears, as shown in the
following example:
The following table describes the dialog tabs for Terminal Server dialog box.
Dialog Tab
Service
Use
Settings for escape sequence, terminal type, event logging level,
and logon banner.
Terminal Server Dialog Box Tabs
87
Dialog Tab
Ports
Use
Configuration settings for each serial port used by UDSerial.
Terminal Server Dialog Box Tabs
Service Option
The Service dialog box enables you to configure your terminal service.
Set Escape Sequence

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

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

Determine the level of event capturing you desire. You can capture errors, warnings, and
information. Choose the level by selecting the corresponding checkbox.
Note
To review the information you capture, from the Start menu, select Programs, then
Administrative Tools, and then click Event Viewer.
Specify Logon Banner

In the Logon Banner box, enter a message to display when a user successfully connects to
UDSerial.
88
Starting, Stopping, and Pausing the Telnet Server

Click Start to start the UDSerial Service. The Start button appears dimmed unless the service is
paused or stopped.
Click Stop to stop the UDSerial Service. The Stop button appears dimmed unless the service is
running.
Click Pause to pause the UDSerial Service. The Pause button appears dimmed unless the service
is running.
Click OK to save the new settings and exit the Terminal Server dialog box. Click Apply to save
the new settings and keep the Terminal Server dialog box open. Changed settings do not affect
UDSerial sessions that are already started. New sessions started after you change the service
parameters use the new parameters. Click Cancel to exit the Terminal Server dialog box without
saving change
Warning
Do not stop the terminal server if UDSerial users are logged in. You could cause file corruption by
disrupting writes in progress.
Reminder
You can also control the UDSerial service from the Control Panel or from the MS-DOS command
prompt.
Port Configuration
Configuring a port depends on the serial device to which you are attaching. You need to know
about the characteristics of your terminal device to select the appropriate settings.
89
Click the Ports tab. A dialog box similar to the following appears:
90
To modify the configuration information for a port, either double-click the port name, or select the
port name and click Properties. The Port Properties dialog box appears, similar to the following
example:
By default this dialog box displays with the Settings tab selected. Notice that the dialog box offers
additional dialog tabs for Modem Options, Logon Script, Auto Connection, and Control Keys.
Reminder
You can choose which ports to use with UDSerial. If you have COM ports that are reserved for
other uses (for instance, serial printers or other software), you can leave those ports disabled in
UDSerial configuration. Even if ports share the same serial card, they do not all have to be
managed by UDSerial.
Select Baud Rate

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

Data bits are the number of data bits per character. Valid settings are be 5, 6, 7, or 8. The most
common setting is 8. Refer to your vendor documentation and select the appropriate value from
the list.
Select Parity
Parity determines the method of marking boundaries of characters. Parity can be none, even, odd,
or mark. Consult your vendor documentation and select the appropriate value from the list.
Select Stop Bits

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

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

Set the terminal type to vt100. If the port is only used for direct access to UniData, you can set it to
a valid entry in udtermcap.
92
Control Keys
If you select the Control Keys tab on the Port Properties dialog box, a dialog box similar to the
following example appears:
Determine Escape Character

The value in the Escape Character box determines the character sequence to disconnect a session
with a remote system and return your serial device to the Telnet prompt. You must enter this value
as the hexadecimal equivalent of the actual sequence. The default is 1d (hex equivalent of Ctrl-]).
Set X on
X on is required if Flow Control in the Settings dialog box is Xon/Xoff. You must enter the value
in hexadecimal. The default is 11 (hex equivalent of Ctrl-Q).
93
Set X off
X off is required if Flow Control in the Settings dialog box is Xon/Xoff. You must enter the value
in hexadecimal. The default is 13 (hex equivalent of Ctrl-S).
Tip
If your terminal supports Xon/Xoff flow control, you probably do not need to modify the Control
Keys.
Modem Options
If you have connected a modem to your COM port, and you want the modem to be managed by
UDSerial, select the Modem Options tab from the Port Properties dialog box. A dialog box
similar to the following example appears:
94
Enter Modem Initialization String

Enter the initialization commands for the modem, one command per line (for instance, auto answer
and echo off) in the Modem Initialization String box.
The Modem Initialization string contains commands for the modem. Insert one command per line.
For example, the following initialization string is proper if you are using a US Robotics Courier V
modem and are using hardware flow control:
+++
ATH0
AT &R1 &I0
AT &B0 & N0
AT &H1 &R2
AT S0=1
Force modem back to Command mode

Hang up modem
Disable flow control entirely
Makes the serial port and connect rates equal
Sets hardware flow control
Enables auto answer
The following example illustrates the Modem Options box using the initialization commands
above:
95
Set Modem Delay

The value in the Modem Delay box determines the delay, in milliseconds, between each line in the
initialization string. The default is 1000 milliseconds. Valid values are between 1000 and 5000.
Logon Script
If you select the Logon Script tab, a dialog box similar to the following example appears:
Enter Login Script

In the Script window, enter a login script, one input per line. The window is scrollable. The default
is blank, meaning no string is sent to the remote computer.
Enter Delay
Enter the delay, in milliseconds, between each line of the login script in the Delay box.
96
Determine Output Suppress

Check the Output Suppress check box to prevent the end user of the serial device from seeing the
input string as it is passed to the remote computer.
Warning
Configuring a login script (userid, password) is generally unwise for a terminal. Automatically
passing an ID and password can compromise your security. If you are configuring a device such as
a bar code reader, where a user cannot directly access your system, passing a preset user ID and
password may be desirable. In either case, consider selecting Auto Connection.
Auto Connection
Select the Auto Connection tab if you want the device attached to your port to connect to a
particular remote host.
Tip
Auto Connection is extremely useful for devices that do not accept direct user input, like printers
or bar code readers. Auto Connection can also simplify the interface for users of terminal devices.
97
When you select the Auto Connection tab, a dialog box dimilar the following example appears:
Determine Auto Connect

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

In the Computer Name box, enter the name or IP address of the computer to which you want to
connect. The computer name must be resolvable by your Windows NT or Windows 2000 system.
98
Determine How to Activate Remote Connection

The Type box determines the method for activating the remote connection. The default is None.
The following table describes valid Types.
Type
Description
None
Auto Connection is disabled.
CTS
Connect/disconnect when CTS signal is raised/dropped. Will not

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

work if Flow Control for this port is DTR/DSR.
Carrier
Connect/disconnect when carrier is detected (RLSD) or dropped.
Always
Connect/disconnect when UDSerial is started/stopped. Make sure

there is a receiving host if you pick this Type.
Auto Connection: Valid Types
99
Starting and Stopping the UniData Terminal

Server
You can control the Terminal Server from the Terminal Server dialog box or from the Control
Panel.
Controlling UDSerial from UniData Admin

You can start, stop, or pause the UniData Terminal Server from the Service tab in the Terminal
Server dialog box.
100
Click Stop to stop the UniData Terminal Service. Users already logged in can continue to
work, but no additional users can log in via UDSerial until you Start the service.
Click Start to start the UniData Terminal Service (if it is stopped) or continue the service
(if it is paused).
Click Pause to pause the UniData Terminal Service. Users already logged in can continue
to work, but no additional users can log in via UDSerial until you Start the service.
Starting and Stopping the UniData Terminal Server
Controlling UDSerial from the Control Panel

You can start, stop, or pause the UniData Terminal Service from the Control Panel. Select the
Services icon from the Control Panel, and scroll through the list of services to display UniData
Terminal Service. The Status column indicates whether the service is presently running, and the
Startup column indicates whether the service is started automatically when your system is
restarted. The following example shows the appearance of the Services window:
Notice that, in the example, both the Telnet service and the Terminal Server are running.
Warning
Do not stop the terminal server if UDSerial users are logged in. You could cause file corruption by
disrupting writes in progress.
101
102
Chapter 5 - UniData and

Services
This chapter explains what services are, and describes services specific to UniData.
103
Chapter 5 - UniData and Services
What Is a Service?
A service is a background process that performs a specific task or set of tasks. Services wait in the
background until they receive a request for their specific function. A number of standard Windows
NT and Windows 2000 services run to control system processes, schedule commands, handle print
requests, and to perform other similar functions. Consult your host operating system
documentation for detailed information about the services that run on your system.
104
Principal UniData Services

UniData Database services control your UniData environment. When a user starts a UniData
session, the users process, called a udt, communicates with the services. The udt process runs with
the permissions valid for the user, preventing inappropriate file access by the UniData services.
Lock trackingsmm records all UniBasic locks and semaphore locks, identifying which
UniData user holds each.
Process cleanupAt periodic intervals, the cleanupd service checks to see if terminated
process flags have been set. If cleanupd detects a terminated process flag, it deletes the
associated process from internal tables, removes any requests from the queue, and
removes any messages sent to the terminated process. If cleanupd receives a message from
a process, it checks to see if the message was sent from a terminated process. If so, it
throws away the message.
Shared Basic Code Server (sbcs)

The shared basic code server, sbcs, manages shared memory used by globally cataloged UniBasic
programs.UniData starts sbcs when you execute startud and stops it when you execute stopud. The
functions of sbcs include:
Loading and tracking globally cataloged programssbcs loads globally cataloged

programs into shared memory as needed, and keeps track of the programs loaded and the
number of processes executing each one. When a user executes a globally cataloged
program, sbcs checks in shared memory, then takes the following actions:
If the program is already loaded, sbcs increments the counter for the number of users
executing it, and tells the udt process which segment to attach to execute the program.
If the program has not been loaded, sbcs loads the program into shared memory and
starts a counter for it.
Periodically, sbcs checks shared memory and removes loaded programs that are no longer
in use.
Controlling shared memoryThe sbcs daemon can attach up to 20 shared memory

segments.
105
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 cleanupAt periodic intervals, the sbcs process checks the cleanupd service to
see if terminated process flags have been set. If sbcs detects a terminated process flag, it
removes all messages sent for the process. If the terminated process is the only process
using a program in shared memory, it removes the program from shared memory. sbcs
uses the process ID to determine if a message it receives is from a terminated process. If
so, sbcs discards the message.
Note
Refer to Chapter 16 - Managing and Using Tape Devices, for additional information about sbcs.
106
Shared Memory Manager (smm)

The shared memory manager, smm, builds and manages structures and tables within shared
memory. UniData starts smm when you start the UniData Database Service, and stops it when you
stop the UniData Database Service.
UniData processes (udt processes) communicate with smm to request and return shared memory.
The UniData processes request shared memory from smm for the following tasks:
License controlThe smm process tracks the number of users for which a site is licensed,
and prevents more than that number of users from logging in to UniData. smm also
displays warning messages when a license is about to expire.
User process trackingWhen a user logs in to UniData, smm assigns an internal tracking
number to the users 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 cleanupAt periodic intervals, the smm process checks the cleanupd service to
see if terminated process flags have been set. If smm detects a terminated process flag, it
checks all ipc IDs. If one of the ipc IDs is invalid, smm exits, bringing down UniData.
smm also checks all process groups to see if a group leader terminated abnormally. If so,
smm removes all self-created shared memory pieces and reclaims all global pages
occupied by the terminated group. smm also corrects any inconsistencies the global
control tables (GCT) may have. An inconsistency could exist if the process was updating a
GCT when it terminated.
The startud command starts smm, which creates a control table (CTL) in shared memory. The CTL
tracks all information about the shared memory segments that smm manages. The size of the CTL
is related to the number of users on the system and to a series of configuration parameters.
107
Clean Up (cleanupd)
The clean up process, cleanupd, detects terminated user processes at check time intervals. If
cleanupd detects a terminated process, internal flags are set. The smm and sbcs services
periodically check to see if cleanupd has set internal flags. If these services detect flags, each
service performs the necessary clean up and resets its own flag to zero. The cleanupd service
performs clean up that is not handled by smm or sbcs. When the smm and sbcs services have reset
their flags to zero, the cleanupd service resets its flag to zero, makes the user process ID available,
and frees the local control table.
108
Monitoring UniData Services

To monitor UniData services, click the Start menu, point to Settings, click Control Panel, and
then double-click Services. A window similar to the following appears:
In the previous example, the UniData Database Service, NFA Server, ObjectCall Service, ODBC
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 NT or Windows
2000 system.
109
Log Files
The sbcs, cleanupd, and smm services each record messages in a pair of logs in the udtbin
directory. In addition, the udt process writes messages to a log file called udt.errlog if a UniData
process encounters file corruption in a data file. The following table lists these log files.
Daemon
/ Process
Routine Messages
Error Messages
smm
udtbin/smm.log
udtbin/smm.errlog
smm
udtbin\smm.log
udtbin\smm.errlog
sbcs
udtbin\sbcs.log
udtbin\sbsc.errlog
cleanupd
udtbin\cleanupd.log
udtbin\cleanupd.errlog
udt
N/A
udtbin\udt.errlog
startud
udtbin\startud.log
udtbin\startud.errlog
Log Files for UniData Daemons and Processes

See Chapter 8 - Starting, Stopping, and Pausing UniData, for additional information and
examples.
The udt.errlog file

If a UniData process encounters file corruption in a data file during processing, UniData writes a
message to the udt.errlog in udtbin. System administrators can monitor this log and take corrective
action for the specified file.
The following example illustrates errors printed to the udt.errlog when a SELECT statement is
executed against a corrupt file:
Screen Example
udtno=1,pid=937,uid=1172,cwd=/home/claireg,Jun 12 12:44:46
1:grpno error in U_blkread for file 'TEST', key '', number=3
110
1:blkread error in U_read_group for file 'TEST', key '', number=3

1:read_all_block_in_group error in U_gen_read_group for file ' ', key ' ', number=0
111
112
Chapter 6 - UniData and

Memory
This chapter describes how to configure, attach, and release shared memory.
113
Chapter 6 - UniData and Memory
Windows NT or Windows 2000 and Shared

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

UniData interacts with shared memory by using system-level calls, UniData services, and UniData
configuration parameters to build its own structures in shared memory.
UniData defines shared memory segments that can be attached by UniData processes. The sbcs
(shared basic code server) service creates shared memory structures for storing active globally
cataloged UniBasic programs.
Reminder
See Chapter 16 - Managing and Using Tape Devices, for more information about sbcs.
The smm (shared memory manager) service creates shared memory structures for internal tables
required by UniData processes. UniData processes request memory for:
Buffering UniBasic variables
Storing intermediate results
Storing a current modulo table for dynamic files
smm and Shared Memory

The shared memory manager (smm) creates shared memory segments as needed. The size and
characteristics of segments smm or the UniData Database Service create are determined by
UniData configuration parameters. Whenever UniData is starts, it reads the udtconfig file located
in udthome\include and stores these values in shared memory. smm subdivides each of its
segments into global pages, and subdivides each global page into local pages.
smm also creates and maintains internal tables that track the use of the structures it creates. These
internal tables, stored in a shared memory structure called CTL, allow smm to protect shared memory pages against accidental overwriting, and to optimize the efficiency of memory use by releasing unneeded shared memory pages back to the operating system.
115
Control Table List (CTL)

When you start UniData, smm creates one shared memory segment for the UniData control table
list (CTL). The CTL remains in memory as long as UniData is running, and is returned to the
operating system when you stop UniData.
CTL is subdivided into three regions, as shown in the following figure:
Control Table List (CTL)

Virtual Memory Pool
shared
memory
pool
shared memory segment
CTL
Control Table List

GI
general
information
GCT
GCT
global
control
table
GCT
GCT
LCT
LCT
local
control
table
LCT
Process Information
Counter Table
Memory Information
Control Information
116
local page
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, or a user executing UniData system-level commands from
the operating system level.
PI (process
information) table
Each PI table registers all processes within a process group.
CT (counter table)
Each CT records information about the behavior of the process group.
MI (memory
information) table
Each MI table records all global pages or self-created shared memory

segments used by the process group.
CI (control
information) table
Each CI table records all blocks allocated from shared memory for
temporary buffers.
Structures Within UniDatas CTL
117
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.
Configuration
Parameter
Description
SHM_GNTBLS
The number of GCTs in the CTL, which is also the maximum number
of shared memory segments that UniData can attach at one time.
NUSERS
The number of LCTs in the CTL, which is also the maximum number
of UniData process groups that can run at the same time.
SHM_GNPAGES
The number of global pages in a shared memory segment.
SHM_LPINENTS
The number of entries in the PI table of each LCT, which is also the
number of processes that can be included in a UniData process group.
SHM_LCINENTS
The number of entries available in the CI table of each LCT; this is the
maximum number of local memory segments that can be used by a
process group at one time. A local segment is made up of one or more
contiguous local pages.
SHM_LMINENTS
The number of entries available in the MI table of each LCT; this is the
maximum number of global pages or self-created memory segments a
process group can use at one time.
Configuration Parameters for CTL Structures
The size of the CTL is the sum of the size required for the GI table, the GCTs, and the LCTs. You
can calculate these by following these steps:
1. The size of the GI table is fixed at 69 bytes.
2. Compute the space (in bytes) needed for GCTs:
((2+SHM_GNPAGES)*4)*SHM_GNTBLS
3. Compute the space (in bytes) needed for LCTs:
((96+(4*SHM_LPINENTS)+
(12*LMINENTS)+(8*SHM_LCINENTS))*NUSERS
118
4. Add the values from the first three steps.

You can also use the UniData command shmconf to calculate the size of CTL. See Chapter 15 Managing Cataloged Programs, for more information.
Note
The size of the shared memory segment reserved for CTL does not need to match the size of the
segments smm manages. All the segments managed by smm are the same size (computed by
multiplying the number of global pages per segment by the size of a global page by 512), but they
are not necessarily the same size as CTL.
Creating and Assigning Memory Structures

When a UniData process requests memory, smm assigns one or more global pages, as requested,
and updates the GCT (or GCTs, if global pages are assigned from more than one shared memory
segment). smm also updates the information in the LCT of the requesting process. When the
requesting process finishes using the assigned memory, the process sends a message to smm,
which releases the global page or pages and updates the GCTs and LCT.
119
The following figure illustrates the smm shared memory structures:
Memory
virtual memory pool
CTL
shared
memory
pool
global page
global page
local page
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.
Configuration
Parameter
SHM_LPAGESZ
Description
The size (in 512-byte blocks) of a single local page of shared memory.
Configuration Parameters for Memory Structure Sizes
120
Configuration
Parameter
Description
SHM_GPAGESZ
The size (in 512-byte blocks) of a global page of shared memory.

SHM_GPAGESZ must be an integral multiple of SHM_LPAGESZ.
Divide SHM_GPAGESZ by SHM_LPAGESZ to obtain the number of
local pages in a global page.
SHM_GNPAGES
The number of global pages in a shared memory segment. Compute the

size, in bytes, of a shared memory segment by multiplying the size of a
single global page (512*SHM_GPAGESZ) by the number of global
pages per segment (SHM_GNPAGES). This total cannot exceed the
maximum segment size defined by your operating system.
Configuration Parameters for Memory Structure Sizes (continued)

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.
Configuration
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.
Configuration Parameters for Creating Shared Memory Segments
121
Displaying Parameter Settings

Use the UniData system-level command sms -h to display the current settings for configuration
parameters related to shared memory. The following screen shows the output for this command for
a system with a 32-user license:
Screen Example
C:\UniData52\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)
-------------------SHM_GNTBLS
= 40
SHM_GNPAGES = 32
SHM_GPAGESZ = 256
GENERAL INFO --------------------(max 40 global segments / system)

(32 global pages / global segment)
(128K bytes / global page)
NUSERS
SHM_LPINENTS
SHM_LMINENTS
SHM_LCINENTS
SHM_LPAGESZ
=
=
=
=
=
128
10
32
100
8
(max 128 process groups / system)

(max 10 processes / group)
(max 32 global pages / group)
(max 100 control entries / group)
(4K bytes / local page)
SHM_FREEPCT
SHM_NFREES
SHM_FIL_CNT
JRNL_BUFSZ
N_FILESYS
=
=
=
=
=
25
1
2048
53248
200
C:\UniData52\Bin>
Note
See Appendix A - UniData Configuration Parameters, for further information about these
parameters.
122
Learning about Global Pages

The gstt command displays information about smms use of global pages in shared memory.
Syntax:
gstt
The following example shows the output from the gstt command:
Screen Example
# 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 ----------------
123
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%.
124
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:
Screen Example
# lstt
----------------------- LCTs Statistics ----------------------Total LCTs (Process Groups allowed): 50
LCTs Used (Active Process Groups): 1 (2% of 50)
Total Ps: 2
Total Global Pages Used: 2 (256K bytes)
Total Self-created.....: 0 (0K bytes)
Total memory used......: 256K bytes
-------------------- End of LCTs Statistics -------------------
Tip
Use the output from lstt, along with the visual display from sms, to monitor use of local control
tables. Informix recommends increasing the number of LCTs (NUSERS) if the value of LCTs
used is consistently higher than 80%. Also, if Total Self-created is consistently greater than
zero, consider increasing SHM_GPAGESZ or optimizing your application to minimize use of
self-created segments.
125
Use the -l or -L option to display additional information about a specific local control table. The
following screen shows an example:
Screen 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 (Leaders pid: 24230)
PI Entries Used (Processes):
MI Entries Used (LSMs).....:
Global Pages...........:
Self-created...........:
Total memory used......:
2 (20% of 10)
2 (6% of 32)
2 (256K bytes)
0 (0K bytes)
256K bytes
CI Entries Used (BLKs).....: 6 (6% of 100)

Local Blocks Used......: 5
Local Blocks Freed.....: 1
-------------------- End of LCTs Statistics -------------------
Reminder
See the UniData Commands Reference for additional information about the parameters of the lstt
syntax.
126
sbcs and Shared Memory

sbcs creates structures in shared memory as needed for storing active globally cataloged UniBasic
programs. The limits for structures created by sbcs are different from those for smm. The
following table describes two udtconfig parameters that control the size of sbcs segments.
Configuration
Parameter
Description
SBCS_SHM_SIZE
Size, in bytes, of shared memory segments created by sbcs. sbcs uses

the segments to store globally cataloged programs. sbcs can attach a
maximum of 20 segments.
MAX_OBJ_SIZE
Maximum size, in bytes, of object code files that sbcs can be load into
shared memory. sbcs loads object code files larger than this size into
the users address space instead of shared memory.
Configuration Parameters for sbcs
Self-Created Segments
A UniData process can attach a segment of shared memory larger than a standard global page.
UniData requires that a UniBasic variable read into memory be contained in a single global page.
If a variable is larger than the size of a global page, udt creates a special segment in shared
memory. These self-created segments, also called indirect segments, are attached to the
requesting udt process and managed by smm. Some circumstances resulting in self-created
segments are:
Editing a large report with AE. AE is a UniBasic program, and it reads a report in as a
single variable.
Reading a large array as a single variable.
smm creates a segment large enough to hold the variable. The self-created segment is counted as a
global page used by the UniData process that created the segment.
127
Warning
Creating these segments of memory is not an efficient resource use, and may result in poor
performance or in thrashing. Use the system-level lstt command or the ipcstat command to
determine if your application is using self-created segments on a regular basis. If so, analyze the
sizes of variables the application uses. Consider increasing the value of SHM_GPAGESZ (the size
of a global page) to handle the variables. Also, consider modifying the application to read arrays
by element rather than as a single variable.
128
Chapter 7 - Configuring
Your UniData System
This chapter outlines configuration considerations that may be appropriate when you first
implement UniData or when you make major changes to your system. Major changes include
adding or reconfiguring hardware, installing a new software application, or upgrading or
relicensing UniData.
This chapter does not present detailed information, but outlines the considerations and refers you
to sources of additional information.
129
Chapter 7 - Configuring Your UniData System
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. The initial
estimates in Installing and Licensing UniData Products should allow you to install and run
UniData. However, Informix recommends that you evaluate your system, including your operating
system, your hardware configuration, and your application, to develop accurate disk space
requirements. Informix offers the following suggestions.
Disk RequirementsUse 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/OFor best results, configure your disk system so that access is balanced across all
devices. Informix suggests the following:
\TEMP directoryLocate your \TEMP directory on a different physical drive from

your data for improved performance.
UniData accountsIf your application uses more than one UniData account, locate
the account directories on separate drives to distribute load.
2. Identify Memory Requirements

The initial estimates in Installing and Licensing UniData Products should allow you to install and
run UniData with a minimal configuration. However, memory requirements can be platform
dependent as well as application dependent. Estimate the memory required for the following
components of your application:
130
The control table list (CTL)
The memory segments controlled by smm
The memory segments for sbcs
See Chapter 6 - UniData and Memory, for information about estimating memory needs.
3. Verify Version Compatibilities

If you are considering major upgrades to your hardware or to your operating system, consult your
Informix account representative early in your planning process to determine if your current
UniData version is supported by the hardware or software you are considering.
4. Check/Reset System-Level Parameters

Depending on your version of Windows NT or Windows 2000, you may or may not be able to
modify system-level parameters directly. You may need to adjust the following categories of
parameters when you first implement UniData:
MemoryReview parameters that limit the number of shared memory segments systemwide, the maximum and minimum size of a segment, and the maximum number of
segments per process. See Chapter 6 - UniData and Memory, for additional information.
Files and UsersReview 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.
131
ipc FacilitiesReview parameters that define the number and size of message queues, the
number of semaphore sets and semaphores, and the number of semaphore undo structures
your system supports.
5. Check/Reset UniData Configuration Parameters

The UniData udtconfig file, located in udthome\include, contains a set of parameters that are given
default values when you install UniData. When you start a UniData session, UniData sets
environment variables for each value in the udtconfig file.
Note
The udtconfig file is always located in udthome\include. Do not move the directory to another
location, or UniData will not run.
The udtconfig file enables you to define values for each parameter that applies to your UniData
environment. You can adjust most udtconfig parameters for your environment, but some should
not be changed. Refer to Appendix A - UniData Configuration Parameters, for detailed information about each udtconfig parameter.
Permissions
You must log in as Administrator to modify udtconfig parameters.
6. Define Peripherals within UniData

You must define tape devices, printers, and line devices within UniData before you can access
them from UniData. Before defining a device within UniData, make sure that it is properly
installed and functioning in your Windows NT or Windows 2000 environment. Refer to your
operating system documentation for information about setting up peripherals on your system.
Use the ECL SETTAPE, SETLINE, and SETPTR commands to define your peripherals to
UniData. See Chapter 14 - Managing Printers in UniData, and Chapter 16 - Managing and
Using Tape Devices, for additional information.
132
7. Create UniData Accounts

When you implement UniData, you may need to create one or more UniData accounts for your
application. A UniData account is a directory that contains a UniData VOC file and its dictionary.
The VOC file identifies commands, paragraphs, and all data files that are used in the UniData
account. The data files may be in the same directory as the VOC file, or the VOC file may contain
pointers to data files in other file systems. Your system may have a single UniData account or
several, depending on your application.
Reminder
A Windows NT or Windows 2000 account (login, password) is not the same as a UniData account.
Every UniData user should have a separate Windows NT or Windows 2000 account (login and
password), but many users can access the same UniData account.
Use the Windows NT or Windows 2000 mkdir command and the UniData system-level newacct
command to create UniData accounts. See your host operating system documentation for information about the mkdir command, and see Chapter 9 - Managing UniData Accounts, for information about the newacct command.
8. Add Windows NT or Windows 2000 Users

Accessing UniData requires each user to have a login and password on your Windows NT or
Windows 2000 system. Informix recommends you create a separate Windows NT or Windows
2000 account for each UniData user. See your host operating system documentation for detailed
information on creating Windows NT or Windows 2000 accounts. See Chapter 10 - Managing
UniData Security, for UniData-specific information.
9. Set Environment Variables

You do not have to set the UDTHOME and UDTBIN environment variables on Windows NT or
Windows 2000, unless your udthome and udtbin directories differ from those defined in the
Registry. A user wishing to access UniData using a different udthome and udtbin than those
defined in the Registry must have two environment variables set: UDTHOME and UDTBIN. The
settings you assign for these variables depend on whether you performed a basic or an advanced
UniData installation.
133
Tip
See Installing and Licensing UniData Products for information about installation types.
UDTHOMEThis variable identifies the path of the UniData home directory. The home
directory contains subdirectories UniData needs for processing.
UDTBINThis variable identifies the path for the directory that contains UniData executables.
By default, udtbin is a subdirectory under udthome.
Setting UDTHOME and UDTBIN

You can add commands to set these environment variables to each users profile, if the user is
accessing UniData with a different udthome or udtbin than defined in the Registry. Use the
following commands to set these variables:
set UDTHOME \directory-name
set UDTBIN \directory-name
set PATH \directory-name
134
You can also set environment variables from the System window. From the Start menu, point to
Settings, click Control Panel, and then double-click System. Click the Environment tab. The
following dialog box appears:
Enter the name of the environment variable you want to establish or change in the Variable box.
Enter the setting for the environment variable in the Value box. Click Set to set the variable, or
Delete to delete the variable.
Setting Additional Environment Variables

Appendix B - Environment Variables for UniData, lists an additional set of variables that are
significant for UniData users. These can be set in the same manner as the environment variables in
the previous example before entering UniData.
135
Note
While you are in a UniData session, you cannot change environment variables for that session.
10. Review UniData Security

Depending on your application, you may need to implement additional measures to ensure data
security and separation of duties. Review your application and implement any or all of the
following:
Default PermissionsModify the default permissions for udthome and its contents that
were set when you installed UniData.
Users and domainsAssign UniData users to separate domains, and set permissions on
your database so that each group of users has access to the data they need.
VOC fileCustomize your VOC file to limit access to powerful commands.
Remote entriesUse remote pointers to files and commands to allow more fine-grained
protection.
SQL PrivilegesFor SQL access, use the UniData SQL GRANT and UniData SQL
REVOKE commands to customize access to tables.
Query PrivilegesFor UniQuery access, use the QUERY.PRIVILEGE file.
See Chapter 10 - Managing UniData Security, for additional information.
11. Convert Data Files

Depending upon the nature of your system change, you may need to perform some conversion of
UniData hashed files. Consider the following:
136
SchemaIf you are implementing UniData ODBC or UniOLEDB, you may need to
make UniData files accessible to UniData SQL, and you may also need to utilize the
Schema API to incorporate ODBC compliance for field and attribute names. See Using
VSG and the Schema API for detailed information.
File characteristicsUniData also offers you the capability to convert files from static to
dynamic, change file characteristics such as block size and modulo, change hashing
algorithm for a static file, and change file format between high-byte and low-byte formats.
See Chapter 11 - Managing UniData Files, and the UniData Commands Reference for
additional information.
12. Review Backup Procedures

Special considerations are needed to back up UniData accounts. Make sure your backup
procedures have the following capabilities:
SubdirectoriesYour backup procedure should be able to back up at least three levels of

subdirectories. This is required to support UniData MULTIDIR and MULTIFILE files.
Backing up selected files Your backup procedure should allow you to input a list of
files to back up. This is required to support full backups of UniData accounts. Simply
backing up the directory that contains the VOC file may be insufficient, since data files are
not necessarily located in the same directory as the VOC file. The ECL SETFILE
command creates VOC entries with pointers to files in other locations. However, backup
utilities may not follow these SETFILE pointers. To create a complete backup of an
account, you need to make sure you back up and verify each physical file associated with
the account.
137
138
Chapter 8 - Starting,
Stopping, and Pausing
UniData
This chapter describes procedures for normal startup and shutdown of UniData, and also describes
commands used to log out users, stop processes, and remove ipc facilities, if needed. These
commands are also documented in the UniData Commands Reference.
139
Chapter 8 - Starting, Stopping, and Pausing UniData
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 processes, in the correct order.
Permissions
You must log in as Administrator to execute startud or stopud. Make sure you define the
environment variables UDTHOME and UDTBIN, and make sure your PATH includes udtbin. If
you are running more than one version of UniData, make sure that these environment variables are
set for the version of UniData you want to start and stop.
UniData Log Files

startud makes entries in the log files (smm.log, sbcs.log, and cleanupd.log) that identify the system
resources used by the daemons.
The following example is a sample sbcs.log:
Screen Example
%# type sbcs.log
SBCS version: 5.2
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)
140
Normal Operation
q - 207 (new version queue)

m - 408
The next example shows a sample smm.log:
Screen Example
% type smm.log
SMM version: 5.2
Number of users......: 16
SMM checking interval: 60 seconds
SMM process id.......: 108
IPC
q q m m m s s s s s s s s s s s s s s s s s s s -
facilities:
0 (request queue)
1 (reply queue)
1094717696 (ctl)
-1795163136 (glm)
-1795163134 (shmbuf)
-2126512128 (ctl)
-2126512127 (journal)
-2126512103 (SUPERRELEASE/SUPERCLEAR.LOCKS)
-2126512128 (latch)
-2126512127 (latch)
-2126512126 (latch)
-2126512125 (latch)
-2126512124 (latch)
-2126512123 (latch)
-2126512122 (latch)
-2126512121 (latch)
-2126512120 (latch)
-2126512119 (latch)
-2126512118 (latch)
-2126512117 (latch)
-2126512116 (latch)
-2126512115 (latch)
-2126512114 (latch)
-2126512113 (latch)
The next example is a sample cleanupd.log:
141
Screen Example
% pg cleanupd.log
CLEANUPD
CLEANUPD
CLEANUPD
CLEANUPD
142
daemon:
checking interval: 20 seconds
minimum interval: 10 seconds
process id.....: 880
Normal Operation
Start UniData with startud

The following screen shows the normal output from the startud command:
Screen Example
C:\UniData52\Bin>startud
Wait for Unidata Service to be started ...
The Unidata Service has been started successfully.
Note
When you install UniData for Windows NT or Windows 2000, UniData installs the UniData
Database 5.2 Service with a setting to automatically start when you boot your computer. You can
change this setting to manually start the UniData Database Service 5.2. See your host operating
system documentation for detailed information about starting and stopping services.
Stop UniData with stopud

For normal operation, use the stopud command with no options. You need to make sure users are
logged out of UniData before you execute this command.
The following screen shows the expected response to the stopud command:
Screen Example
C:\UniData52\Bin>stopud
DBpause is OFF.
Stop Unidata Service now ...
CLEANUPD stopped successfully.
The Unidata Service has been stopped successfully.
#
143
Pausing UniData
This section describes the commands you can use to temporarily suspend updates to your system.
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
Permissions
You must log in as Administrator to issue the dbpause command.
dbpause blocks most updates to the database that are made within UniData. Writes or transactions
in process when you issue the dbpause command are completed before dbpause takes effect.
UniData blocks updates until the system administrator executes the dbresume command.
UniData does not block system-level commands, such as COPY or MOVE. In addition, UniData
does not block updates to the _HOLD_ file and the _PH_ file, and does not interrupt report
printing.
Note
Some UniData system-level commands, such as verify2, require that UniData not be running.
These commands do not execute successfully with dbpause in effect. You cannot stop UniData
with dbpause in effect.
144
Pausing UniData
UniData does not block the following ECL commands when dbpause is in effect:
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)
MIN.MEMORY
SET.DEC, SET.MONEY, SET.THOUS, SET.WIDEZERO
145
SETOSPRINTER, SETPTR, SP.ASSIGN, SP.EDIT
TERM
WHAT
The following example illustrates the output from the dbpause command:
Screen Example
C:\UniData52\bin>dbpause
DBpause successful.
#
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:
Screen Example
C:\UniData52\bin>dbpause_status
DBpause is ON.
%
146
Pausing UniData
Resuming Processing
To resume processing after issuing the dbpause command, issue the dbresume command. User
processes resume, and writes that were blocked when the dbpause command was issued complete.
Syntax:
dbresume
Permissions
You must log in as Administrator to issue the dbresume command.
The following screen illustrates the output from the dbresume command:
Screen Example
C:\UniData52\bin>dbresume
DBresume successful.
#
147
Additional Commands
UniData provides a number of system-level commands to assist you in clearing users, processes,
and system resources from UniData if needed. These commands are intended for removing hung
processes, clearing ipc facilities for a clean start of UniData, or logging users and resources off for
an emergency shutdown. These commands are listed in the following table.
UniData
Command
Function
listuser
Lists all current UniData users.
stopudt
Logs a user out of UniData; a current write completes, but subsequent

operations for that udt do not take place.
deleteuser
Forces a user out of UniData and removes the users entry from the internal
tables.
ipcstat
Lists all ipc structures in use on the system; identifies those used by UniData
processes.
stopud -f
Forces all UniData processes to stop regardless of system activity.

UniData System-Level Commands
Warning
Notice that stopudt, deleteuser, and stopud -f all carry the risk of disturbing the integrity of your
data. You should never use them as a routine substitute for normal user logoff.
148
Additional Commands
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, found in the USRNBR column of listuser
command.
Use this command if you need to log out a user you cannot reach, or to clear a hung user process.
The following screen shows the action of stopudt.
Screen Example
C:\UniData52\Bin>listuser
Licensed/Effective # of Users
16 / 16
UDTNO USRNBR
UID
USRNAME
USRTYPE
Udt
Sql
Total
TTY
IP-ADDRESS
TIME
DATE
324 1049668 claireg
udt
pts/1
Console
09:06:21 Jun 19 1999
136 1049668 claireg
udt
pts/2
Console
09:06:29 Jun 19 1999
C:\UniData52\Bin>stopudt 324
C:\UniData52\Bin>listuser
16 / 16
UDTNO USRNBR
2
UID
USRNAME
136 1049668 claireg
USRTYPE
udt
Udt
Sql
Total
TTY
IP-ADDRESS
TIME
pts/2
Console
09:06:29 Jun 19 1999
DATE
149
Permissions
You must log in as Administrator to execute stopudt. If you run listuser immediately after stopudt,
the user may still be included in the display. This is because the cleanupd process performs its
checking and cleanup routines at a predefined interval.
Note
The argument for stopudt is the process ID (pid) associated with the udt process you are removing.
Use the UniData listuser command, as shown in the preceding example. The pid is under the
USRNBR column.
Stopping a User Process with deleteuser

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.
Syntax:
deleteuser pid
The argument pid is the process ID.
Warning
Because deleteuser may execute the Terminate Process, it is particularly important that you verify
the pid carefully.
150
Additional Commands
The following screen shows an example of the deleteuser command:
Screen Example
% listuser
16 / 16
UDTNO USRNBR UID
USRNAME
1
324 1049668 claireg
2
136 1049668 claireg
Udt
2
USRTYPE
udt
udt
16 / 16
UDTNO USRNBR UID
USRNAME
2
136 1049668 claireg
TTY
pts/1
pts/2
# deleteuser 324
# listuser
TTY
pts/2
Total
2
IP-ADDRESS
Console
Console
Udt
2
USRTYPE
udt
Sql
Sql
0
TIME
DATE
09:06:21 Jun 19 1999
09:06:29 Jun 19 1999
Total
2
IP-ADDRESS
Console
TIME
DATE
09:06:29 Jun 19 1998
Permissions
You must log in as Administrator to execute deleteuser.
Displaying ipc Facilities with ipcstat

The ipcstat command displays a list of all ipc facilities (message queues, semaphores, and shared
memory segments) in use on a system, and identifies those facilities used by UniData processes.
You do not need to log in as administrator to execute ipcstat.
Syntax:
ipcstat [-q] [-m] [-s]
151
The following screen shows an example of ipcstat output:
Screen Example
C:\UniData51\Bin>ipcstat -m
T
ID
SIZE CPID
m1094717696 1085952
366 -> smm R5.1 (ctl)
m-1795163135
288848
366 -> smm R5.1 (msg)
m-1795163136 4194304
366 -> smm R5.1 (glm)
m-1795163134 4194304
366 -> smm R5.1 (buf)
#
Notice that, because the -m option was specified, the output lists shared memory segments only.
Use ipcstat -q to display message queues, ipcstat -s to list semaphores, and ipcstat with no options
to list all ipc facilities.
Note
UniData does not use all the ipc facilities on the system. The output from ipcstat indicates which
ones are used by UniData processes. The ones that correspond to unknown are not associated
with UniData processes.
Stopping UniData with stopud -f

The stopud -f command stops all processes and UniData services regardless of activity on the
system. Use this only if your system is hung and stopud fails.
Syntax:
stopud -f
The following example shows the expected output from stopud -f:
Screen Example
C:\UniData52\Bin>stopud -f
DBpause is OFF.
152
Additional Commands
WARNING: 'stopud -f' will stop the Unidata system with force.
This may not gurantee the consistency of the database files.
Would you like to continue?(y/n) [n]
y
Stop Unidata Service now ...
CLEANUPD stopped successfully.
The Unidata Service has been stopped successfully.
Permissions
You must log in as Administrator to execute stopud -f.
Warning
stopud -f may leave your database in an inconsistent state; use it as a last resort.
153
154
UniData Accounts
This chapter describes UniData accounts and describes procedures used to create, save, and clear
the accounts.
155
Chapter 9 - Managing UniData Accounts
What Is a UniData Account?

A UniData account is a directory that contains a default set of UniData files, including a VOC file
and its dictionary.
Note
The system-level newacct command creates the default files UniData requires for an account.
The VOC file identifies commands, paragraphs, and all data files that are used in the UniData
account. The data files may be in the same directory as the VOC file, or the VOC file may contain
pointers to data files in other directories. Your system may have a single UniData account, or
several, depending on your application.
Reminder
A Windows NT or Windows 2000 account typically means a login ID, its associated password,
and its default directory. There is no direct relationship between UniData accounts and Windows
NT or Windows 2000 accounts (logins). Many Windows NT or Windows 2000 users may access
any UniData account. A Windows NT or Windows 2000 users default directory does not have to
be (and usually is not) a UniData account.
156
Creating a UniData Account

There are three steps required to create a UniData account:
1. Use the MS-DOS mkdir command to create the directory that will house the account. The
name of the UniData account directory can be in uppercase, lowercase, or mixed uppercase
and lowercase.
2. Make the new directory your working directory. You can change to the directory with the
MS-DOS cd command.
3. Use the UniData newacct command to create the VOC and other UniData-specific files in the
directory.
Note
You do not need to log in as Administrator to create a UniData account. However, you must have
Change access in the account directory.
The following three screens illustrate how to create a UniData account. In the examples, the new
account is names ACCOUNT, and is located in the UniData directory:
The first window shows creating the account directory:
157
Next, the contents of the UniData directory now include the new folder for ACCOUNT:
The next window illustrates executing the newacct command:
Notice that the screen displays the current setting of UDTHOME and prompts you if you wish to
continue.
158
The final window shows the contents of your new UniData account:
Note
In an MS-DOS dir listing, entries enclosed in square brackets ){SAVEDLISTS}, for instance) are
subdirectories.
When you execute newacct, UniData creates the VOC file for the new account using a standard
VOC file located in the sys subdirectory of your UniData home directory.
Tip
If you want to tailor your standard VOC file before creating new accounts, you may do so. There
are a number of reasons you may wish to tailor your VOC file. You may want to add custom
paragraphs, for instance, that all users should execute. Informix recommends that you save a copy
of the standard VOC before making changes.
159
The following table describes the default subdirectories UniData creates with a new account.
Subdirectory
Description
BP
Used to store UniBasic source and object code.
CTLG
Used to store locally cataloged UniBasic programs.
SAVEDLISTS
Used to store SELECT lists.
SAVEDLISTSL
Used to store temporary information for BY.EXP sorts.

UniData automatically creates and deletes the contents
of this subdirectory.
_HOLD_
Used to store print files.
_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).
Subdirectories in a UniData Account
UniData creates the subdirectories empty and populates them as the account is used.
The next table describes the UniData hashed files that UniData creates are created in a new
account.
File
Description
MENUFILE
Stores user-generated menu definitions.
VOC
VOC (vocabulary) file, containing references for ECL

commands, sentences, paragraphs, and file names.
__V__VIEW
Used to store UniData SQL view specifications.
privilege
Used to store UniData SQL access privileges.

Hashed Files in a UniData Account
160
File
Description
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_SAVEDLISTSL
Dictionary for savedlists.
Hashed Files in a UniData Account (continued)
Note
See Developing UniBasic Applications and Using UniData SQL for information about UniBasic
and UniData SQL
161
Deleting an Account
There is no UniData command or utility that allows you to delete an entire account. If you need to
delete an account, complete the following steps:
1. Analyze the database and identify which files you want to delete. Take care not to delete
shared files that other UniData accounts still need.
2. Create and verify a full backup of at least the account you are going to delete.
3. Consider strategy. If the account is self-contained (that is, within one file system), you can use
the MS-DOS rmdir /s command to delete the account directory. If the account has file
pointers to other file systems, you may wish to use the ECL DELETE.FILE command to
delete the files before removing the account directory. Use the ECL MAX.USER command to
prevent inadvertent access to the UniData account.
Warning
Be careful with rmdir /s. This command removes all files and subdirectories below the directory
you specify. If you have nested accounts (that is, a UniData account within a UniData account) and
you remove an account directory with rmdir /s, you could remove more than one account.
162
Clearing Space in UniData Accounts
Clearing Space in UniData Accounts

UniData uses the _PH_ and _HOLD_ subdirectories of each account to store output from
background processes and temporary print files, respectively. These subdirectories can become
large, causing disk space problems. The UniData ECL CLEAR.ACCOUNT command removes
all files from either or both of these subdirectories.
CLEAR.ACCOUNT
Syntax:
CLEAR.ACCOUNT
You must log in to the UniData account you are clearing. You do not need to log in as
Administrator, however, you must have write permission for the _PH_ and _HOLD_ directories
and delete permissions for the files in the directories. When you issue the command, UniData
prompts you for confirmation to clear each directory, as shown in the following example:
Screen Example
:WHERE
C:\UniData52\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 or the
MS-DOS DEL command, if necessary, to remove only selected files.
163
164
UniData Security
Customizing Permissions
When you install UniData, UniData sets default permissions on system files and directories. After
installing UniData, you may want to customize some permissions.
165
Chapter 10 - Managing UniData Security
To customize permissions, from Windows NT or Windows 2000 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 Securites tab. The following dialog box
appears:
166
Select Permissions. A dialog box similar to the following appears:
Select the permissions you desire from the Type of Access list, then click OK.
Informix 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.
Guidelines for Permissions for UniData System Files
167
Directory or File
Guidance
udthome\sys\CTLG
Users, including programmers, need execute permission to

this global catalog directory. In general, do not allow users
to add or delete subdirectories to CTLG.
udthome\sys\ CTLG\n and

directories and files within
these subdirectories
CTLG contains a subdirectory for each letter of the

alphabet and one for symbols. Users need execute
permission to these directories and read access to the files
in them. Programmers may need Change permissions to
the subdirectories and files so they can catalog or delete
cataloged programs.
udthome\demo
Use this directory for training and experimentation. Use

any permissions settings that suit your situation.
udthome\sys\AE_BP
All users with access to AE (the line editor) need read and
write permissions.
Guidelines for Permissions for UniData System Files (continued)

When you create a UniData account, Informix suggests the following guidelines for setting
permissions for the directory, subdirectories, and files in the account:
Directory or
File
Guidance
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.
Suggested Permissions for a UniData Account
168
Directory or
File
Guidance
SAVEDLISTS
Users need read and write permissions.
_HOLD_
_PH_
VOC
(This refers to the account VOC file, not the master VOC file in
udthome\sys.) Users must have read and write access to enter their
accounts unless you have set the VOC_READONLY environment
variable. See Using UniData for more information about the VOC file.
Suggested Permissions for a UniData Account (continued)
169
Customizing a VOC File

This section describes ways to customize your VOC file.
Removing Entries
Depending on your application, you may wish to prevent users from executing certain ECL
commands. If you remove the entries corresponding to these commands from a VOC file in an
account, users logged into 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:
Screen Example
LIST VOC WITH @ID = COPY 19:03:11 May 23 2000 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 system-level commands. You may want to consider removing some or all of these from
the VOC files for your accounts. These commands allow users to perform the following tasks.
Command
!
Description
Escape to an MS-DOS shell prompt.
VOC Commands Security
170
Command
Description
CLEAR.FILE
Clears the data or dictionary of a file.
CNAME
Changes a filename.
COPY
Copys 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.
VOC Commands Security (continued)
Note
You can remove entries from the UniData master VOC file (located in udthome\sys) or from the
VOC files in one or more UniData accounts. The master VOC is installed as part of the UniData
installation, and is used to build VOC files for your accounts when you execute the newacct
command. If you remove commands from the master VOC file, and then create new UniData
accounts, users in the new accounts will not be able to execute the commands you remove.
171
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 Administrators can bypass security restrictions
created by removing entries from the VOC file. If UDT.OPTIONS 19 is on, UniData prevents even
Administrators from executing commands after the entries are removed from the VOC.
If UDT.OPTIONS 19 is off (the default), UniData allows Administrators to execute ECL
commands even if the command entries were removed from the VOC file. When a user logged in
as Administrator executes a command, UniData first reads the VOC file in the current account, just
as it does for any other user. If there is a matching entry, UniData executes the command. If there
is no matching VOC entry, and if UDT.OPTIONS 19 is OFF, Administrators can still execute the
command. The following table shows the behavior of UDT.OPTIONS 19.
UDT.OPTIONS
19
ON
Command
Status
VOC entry exists
Behavior
Administrators can execute
command
Others can execute command
UDT.OPTIONS 19
172
UDT.OPTIONS
19
OFF
Command
Status
VOC entry exists
Behavior
command
Others can execute command
ON
No VOC entry
Administrators cannot execute

command
Others cannot execute command
OFF
No VOC entry

command
Others cannot execute command
UDT.OPTIONS 19 (continued)
UDT.OPTIONS 19 is turned off by default. Leave it off to allow a user with Administrator
privileges to execute commands that users cannot; turn it on to make Administrators consistent
with other users.
Tip
See the UDT.OPTIONS Commands Reference for detailed information about the UDT.OPTIONS
command.
173
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 a record definition to be stored in a
location other than the VOC file. You can substitute remote items for sentences, paragraphs,
commands, locally cataloged programs, or menus. See Using UniData for more information about
R-type items.
R-type items enable you to customize security in two ways:
You can use a remote item as a pointer to a location with different Windows NT or
Windows 2000 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:
Screen Example
:LIST VOC F1 F2 F3 F4 WITH @ID = LIST 11:05:23 May 24 2000 1
VOC....... F1........ F2............. F3............. F4.............
LIST
R
1 record listed
OTHER_LIST
LIST
SECTEST2
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.
174
Remote Items
The next screen shows the security subroutine:
Screen Example
: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:
Screen Example
:LIST VOC WITH F1 = PA
Not a verb
LIST
The next example shows what happens if VALID is 1 (true):
Screen Example
:LIST VOC WITH F1 = PA
LIST VOC WITH F1 = PA 11:13:27 May 24 2000 1
VOC.......
ECLTYPE
CP
CT
SP.OPEN
listdict
175
LISTDICT
6 records listed
176
The SETFILE Command
The SETFILE Command

You can also customize security by placing data files in a location with different NTFS
permissions than your UniData account, and then modifying the corresponding VOC entries to
point to the location. Use the SETFILE ECL command to establish the file pointers, as shown in
the following example:
Screen Example
:SETFILE \USERS\SECURE\INVENTORY INVENTORY
Tree name
\USERS\SECURE\INVENTORY
Voc name
INVENTORY
Dictionary name
\USERS\SECURE\D_INVENTORY
SETFILE completed.
You can set the NTFS permissions at the location of the file to limit access. If a user with
insufficient permissions tries to access the file, UniData displays an error message similar to the
one shown in the following example:
Screen Example
:LIST INVENTORY ALL
Open \usr\SECURE\INVENTORY error.
Open file error.
:
See the UniData Commands Reference for information about the SETFILE command.
177
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 then
invokes an application menu. A typical LOGOUT paragraph executes a routine that cleans up
application files and exits the application in an orderly manner. If you define the environment so
that a user logs directly into a UniData account and executes the udt command, and the LOGIN
paragraph defines the UDT.OPTIONS and displays a menu, the user does not see either the
MS-DOS command prompt or the ECL prompt.
The behavior of LOGIN and LOGOUT paragraphs are summarized as follows:
When you enter UniData, UniData checks the VOC file in the account you are entering for
a LOGIN paragraph. If there is one, UniData automatically executes it.
If you change accounts with the ECL LOGTO command, UniData does NOT execute the
LOGOUT paragraph in the account you are leaving. UniData looks in the VOC file of the
account you are entering, and executes the LOGIN paragraph there, if there is one.
When you exit UniData, UniData checks the VOC file in your current account and
executes the LOGOUT paragraph, if one is there.
Note
You can also use the ECL ON.ABORT command to prevent users from accessing the ECL or
MS-DOS prompt. ON.ABORT defines a paragraph that executes whenever a UniBasic program
aborts. See the UniData Commands Reference for information about ON.ABORT.
178
LOGIN and LOGOUT Paragraphs
The following sample session shows simple examples of LOGIN and LOGOUT paragraphs in a
UniData account, and a different LOGOUT paragraph in a second account:
Screen 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 \UniData52\demo
:CT VOC LOGOUT
VOC:
LOGOUT:
PA
RUN BP EXIT_PROG
DISPLAY LOGGING OUT OF UNIDATA
:
In the preceding example, the second LOGOUT paragraph executes a program called
EXIT_PROG, which simply prints a message. A user-written exit program can perform a variety
of tracking and reporting functions.
179
The next example shows the response when two of these paragraphs are executed:
Screen Example
C:\USERS\TEST
% udt
UniData Release 5.2 Build: (3033)
(c) Copyright 2000 Informix Software, Inc.
All rights reserved.
Current UniData home is \UniData52.
Current working directory is \USERS\TEST.
ENTERING UNIDATA APPLICATION
:LOGTO \UniData52\demo
:WHERE
C:\UniData52\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 users .login or .profile file sets their
working directory to a UniData account and executes the udt command, and the LOGIN paragraph
defines the UDT.OPTIONS and displays a menu, the user does not see either the MS-DOS
command prompt or the ECL prompt.
Notice also that logging out of UniData after the LOGTO command executes the LOGOUT
paragraph of the current account only.
Note
If UDT.OPTIONS 20, U_IGNLGN_LGTO, is on, users logged in as an Administrator can access
an account through the LOGTO command without executing the LOGIN paragraph. If a user
logged in as an Administrator accesses the account directly, UniData executes the LOGIN
paragraph regardless of the setting of UDT.OPTIONS 20.
180
UniData SQL Privileges
UniData SQL Privileges

When you create a UniData SQL table or view, you have exclusive UniData SQL access to it.
Regardless of file permissions set at the system level, no other user can execute UniData SQL
operations against the table or view until you grant privileges via the UniData SQL GRANT
command. The UniData SQL REVOKE command allows you (or any other user with ALL
privileges) to revoke privileges that were granted. UniData SQL privileges can be granted or
revoked for an entire table or for specified commands.
Note
UniData and UniData SQL share data and dictionary files. Therefore, depending on the systemlevel file permissions, tables created in UniData SQL can be accessed by other UniData tools such
as ECL or UniQuery. The GRANT and REVOKE commands affect UniData SQL operations only.
Note
See the UniData SQL Commands Reference and Using UniData SQL for more information about
UniData SQL privileges.
181
Field-Level Security for UniQuery

UniData includes functionality to determine UniQuery access on a attribute-by-attribute basis.
System administrators can set privileges for UniQuery access at the file or attribute level for a
single user or for all users in a domain by creating a QUERY.PRIVILEGE table in a specified
format and adding records to that table.
You can also set a default for your system, defining all files as OPEN or SECURE. In an OPEN
system, the ability to access a file or a field with UniQuery is a function of system-level file
permissions, other UniData security implementations, and privileges granted using the
QUERY.PRIVILEGE table. In a SECURE system, unless privileges are granted in the
QUERY.PRIVILEGE table, users cannot access files via UniQuery, regardless of system-level
permissions or other implementations.
Points to Remember about Field-Level Security

Remember the following points about field-level security:
182
Implementing and maintaining field-level security is a completely manual process. You

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

UniQuery security depends on the existence of the QUERY.PRIVILEGE file, which must be
located in udthome\sys. If this file does not exist, UniQuery functions as it has previously, with no
field-level security.
Warning
If you create the QUERY.PRIVILEGE file, but do not populate the file with any records, UniData
does not allow any user to access any files on the system through UniQuery.
When you install UniData, the UniQuery security is not implemented, and there is no
QUERY.PRIVILEGE file. If you wish to turn this feature on, you must create
QUERY.PRIVILEGE and D_QUERY.PRIVILEGE manually.
Records in the QUERY.PRIVILEGE file grant the SELECT privilege to users or groups of users,
at the file level or the attribute level. Each QUERY.PRIVILEGE record has one attribute. The
dictionary of the QUERY.PRIVILEGE file contains four records.
Following is a sample of the dictionary of the QUERY.PRIVILEGE file:
Screen Example
:LIST DICT QUERY.PRIVILEGE
LIST DICT QUERY.PRIVILEGE BY TYP BY @ID TYP LOC CONV NAME FORMAT SM ASSOC
15:20:26 Jun 02 2000 1
@ID............ TYP LOC.......... CONV NAME........... FORMAT SM ASSOC.....
@ID
PRIV
FULLPATH
D
D
V
USERNAME
0
1
FIELD(@ID'*'
,2)
FIELD(@ID,'*'
,1)
QUERY.PRIVILEGE 50L
PRIVILEGES
5R
File Path
25T
S
M
S
User Name
25T
4 records listed
183
The following table describes each QUERY.PRIVILEGE attribute.

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

granting privileges, by location. PRIV is a multivalued attribute.
To grant privileges to all attributes in a file, set PRIV to ALL. If
you are setting a system default, set PRIV to OPEN to grant
privileges. To restrict privileges to every attribute in a file, set
PRIV to SECURE.
FULLPATH
Virtual attribute formula that designates the full path of the file
affected by PRIV. This formula has the format
FIELD(@ID,*,2).
USERNAME
Virtual attribute formula that designates the user affected by PRIV.

This formula has the format FIELD(@ID,*,1).
QUERY.PRIVILEGE Record Attributes
Note
You can customize the length of the dictionary attributes in the QUERY.PRIVILEGE file. The
length of @ID should be sufficient to contain the longest UNIX username 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 username, respectively.
184
The following example shows a very simple example of a QUERY.PRIVILEGE file:
Screen Example
LIST QUERY.PRIVILEGE PRIV 15:28:31 Jun 02 2000 1
QUERY.PRIVILEGE................................... PRIVILEGES
user01*C:\UniData\demo\INVENTORY
user01*C:\UniData\demo\CLIENTS
DEFAULT
3 records listed
1
2
3
4
5
11
ALL
OPEN
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 turn on the security feature by creating and populating the QUERY.PRIVILEGE file, every
time a user logs in to UniData, their udt process reads the contents of QUERY.PRIVILEGE and
stores the information for reference. Then, when a user attempts a UniQuery access, UniData
checks the stored information, following these steps:
1. Check for privileges granted to the users domain.

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

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

Privileges granted to PUBLIC apply to all system users. If PUBLIC has sufficient privileges for
the requested access, grant the access. Otherwise, proceed to step 4.
4. Check for a DEFAULT entry.

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

Complete the following steps to implement the UniQuery field-level security feature:
1. Log in to your system as Administrator.

UniData must be running. Users do not need to log off.
2. Create QUERY.PRIVILEGE
Change your working directory to udthome\sys, and enter udt to start a UniData session. Use the
ECL CREATE.FILE command as follows:
Screen Example
:WHERE
\UniData52\sys
:CREATE.FILE QUERY.PRIVILEGE 101
Create file D_QUERY.PRIVILEGE, modulo/1,blocksize/1024
Hash type = 0
186
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 on QUERY.PRIVILEGE

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

Use UniEntry, AE, or ED to edit D_QUERY.PRIVILEGE. The dictionary must look like the
following example:
Screen Example
@ID............ TYP LOC.......... CONV NAME........... FORMAT SM ASSOC.....
@ID
PRIV
FULLPATH
D
D
V
USERNAME
0
1
FIELD(@ID,'*'
,2)
FIELD(@ID,'*'
,1)
QUERY.PRIVILEGE 50L
PRIVILEGES
5R
File Path
25T
S
M
S
User Name
25T
Reminder
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

For this step, you may prefer to have users logged out of UniData. As you add records to the
QUERY.PRIVILEGE file, users logging into UniData access whatever records are present at the
time they log in, which may cause unexpected results.
187
Use AE, UniEntry, or ED to populate the QUERY.PRIVILEGE file.
188
UniData Files
UniData stores your data in hashed files of several different types. UniData also supplies other
types of files to support your database, including index files, program files, and directory files.
This chapter describes the types of UniData hashed files and explains the commands you can use
to manage them.
189
Chapter 11 - Managing UniData Files
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. You can specify hash type 1 when you
create a file, and you can switch between hash types with the memresize command.
190
Static Hashed Files
Static Hashed Files

UniData creates static hashed files with a specified block size multiplier and a specified modulo
(number of data groups). UniData stores the block size and modulo in the header of the file.
Groups in static hashed files can overflow in two ways, as shown in the following table.
Overflow
Type
Description
Level 1
overflow
The amount of space required for the data in the group is larger than the amount
of space available. This happens if the length of a data record is too long for the
block size, or if the number of records in the group grows so large that not all of
the data fits. UniData appends overflow blocks to the original file, and stores the
data portions of records in overflow. The pointers and keys remain in the primary
data file; accessing a record can require two reads, one to determine the address
and the second to read the data in overflow.
Level 2
overflow
The amount of space required for pointers and keys is larger than the total size of
the group. This happens if too many records are hashed to the group. UniData
creates overflow blocks which contain both data and keys. Record access can
require multiple reads to determine the location and find the data.
Level 1 and Level 2 Overflow
Note
When a group in a static file overflows, UniData links the overflow blocks to that specific group. If
overflow blocks are freed (by deleting records, for example) they remain linked to the original
group and are not available to handle overflow from any other group in the data file. The space
used by the blocks is not returned to the operating system. Level 1 overflow eventually impacts the
performance of a static hashed file. Level 2 overflow impacts performance earlier and more
severely, so correct sizing to prevent level 2 overflow is critical.
191
Dynamic Hashed Files

Dynamic hashed files automatically increase modulo (number of groups) to minimize level 2
overflow. When you view the structure of dynamic files at the operating system level, the structure
is different from that of static files. A dynamic file is actually an NTFS directory containing at
least two binary files:
One or more data files named dat00x. These are hashed files. dat001 is the primary data
file. Each group in a dat file contains a group header, keys, pointers, and data.
One or more overflow files named over00x. Blocks in these files hold data when a group
in a data file is in level 1 overflow.
The following example shows the structure of the ORDERS file in the UniData demo database:
Screen Example
C:\Unidata52\demo>DIR ORDERS
Volume in drive C has no label.
Volume Serial Number is E476-B561
Directory of C:\UniData51\demo\ORDERS
10/27/98
10/27/98
10/08/98
10/08/98
4 File(s)
11:14a
11:14a
03:02p
03:02p
<DIR>
<DIR>
24,576
9,216
33,792
2,842,187,776
.
..
dat001
over001
bytes
bytes free
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 data is added to them.
You create a dynamic file with a specified initial modulo, which is the minimum modulo of the
file. As records are added, UniData adds groups to the data file (dat001) to prevent level 2
overflow and adds blocks to the overflow file (over001) to contain level 1 overflow.
192
If you specify the OVERFLOW option with the CREATE.FILE command, UniData creates a
dynamic file with an overflow file for each dat file. For example, over001 corresponds to dat001,
over002 corresponds to dat002, and so forth. When the file is cleared, UniData maintains this
overflow structure. For more information about the CREATE.FILE command, see the UniData
Commands Reference.
Splitting and Merging

When a group in the primary data file reaches level 1 overflow, UniData stores the overflowed
data in blocks in the overflow file. Blocks in over001 are linked (internal to UniData) to groups in
the primary data file dat001. When the overflow file runs out of blocks, UniData adds blocks to it.
To prevent level 2 overflow, UniData splits groups (increasing the modulo of the primary file)
whenever the load factor of an existing group reaches a level called the splitting threshold (or
SPLIT.LOAD). The splitting process is transparent to the user. When a group splits, UniData adds
the additional group to the primary data file, increasing its modulo and physical size.
As records are removed from a dynamic file, groups that had been split can merge back together if
all the following conditions are true:
The current modulo of the file is greater than the minimum modulo of the file.
The combined load factor of the two groups is less than a value called merging threshold
(or MERGE.LOAD).
One of the two groups is the last group in the file.
UniData provides two different split/merge types for dynamic files, KEYONLY and KEYDATA.
You can set the split/merge type when you create a dynamic file, and you can change an existing
split/merge type for a file with the CONFIGURE.FILE command or the memresize command. Use
FILE.STAT, ANALYZE.FILE, or GROUP.STAT to display the split/merge type for a file.
193
KEYONLY Type
The KEYONLY split/merge type is the default for UniData dynamic files. For KEYONLY
dynamic files, the load factor of a group is the percentage of the group space that is filled with keys
and pointers. By default, the splitting threshold for a group in a KEYONLY dynamic file is 60%,
meaning that the group can split into two when the space occupied by keys and pointers reaches
60% of the size of the group. By default, the merging threshold for a KEYONLY dynamic file is
40%, meaning that if the total load in a pair of groups that resulted from a split is under 40% of the
size of a single group, the pair are eligible to merge. You can change the splitting threshold for a
single KEYONLY file with the CONFIGURE.FILE or memresize commands, and you can change
the defaults for all files by changing the SPLIT_LOAD and MERGE_LOAD parameters in the
UniData configuration file (\udthome\include\udtconfig).
KEYDATA Type
The KEYDATA split/merge type is also available for UniData dynamic files. For KEYDATA
dynamic files, the load factor of a group is the percentage of the group space that is filled with
keys, pointers, and data. By default, the splitting threshold for a group in a KEYDATA dynamic
file is 95 percent, meaning that the group can split into two when the space occupied by keys,
pointers, and data reaches 95 percent of the size of the group. By default the merging threshold for
a KEYDATA dynamic file is 40 percent, meaning that if the total load in a pair of groups that
resulted from a split is under 40 percent of the size of a single group, the pair are eligible to
merge.You can change the splitting threshold for a single KEYDATA file with the
CONFIGURE.FILE or memresize commands, and you can change the defaults for all files by
changing the KEYDATA_SPLIT_LOAD and KEYDATA_MERGE_LOAD parameters in the
UniData configuration file (\udthome\include\udtconfig).
Selecting a Split/Merge 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.
194
Dynamic Files and Hash Type

For both static and dynamic files, the default hash type was is 0. This hash type provides a more
even distribution of keys in groups in dynamic files. If key 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.
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.
The following example illustrates creating a dynamic file in the current account directory:
Screen Example
:CREATE.FILE DYN_TEST 3,1 DYNAMIC
Create file D_TEST.DYN, modulo/1,blocksize/1024
Hash type = 0
Create dynamic file TEST.DYN, modulo/3,blocksize/1024
Hash type = 0
Split/Merge type = KEYONLY
Added "@ID", the default record for UniData to DICT TEST.DYN.
:!DIR DYN_TEST
195
Directory of C:\UniData51\claireg\DYN_TEST
11/09/98
11/09/98
11/09/98
11/09/98
01:47p
<DIR>
.
01:47p
<DIR>
..
01:47p
4,096
01:47p
1,024
4 File(s)
5,120
2,842,173,440
dat001
over001
bytes
bytes free
In the preceding example, the primary data file (dat001) includes a file header and the three data
groups for a total of four 1K blocks. The overflow file (over001) includes a 1K file header. Since
MAX_FLENGTH is larger than minimum modulo * block size, the primary data file and overflow
file each have only one part.
Tips and Constraints for Creating a Dynamic File

This sections 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. 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.
196
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. Informix recommends you choose a block size that is at least 10 times the average
record length. UniData bases the load factor in a KEYDATA file on the percentage of the space in
each block that is occupied by both keys and data. If the block size is not large with respect to
record size, the file will occupy a large amount of space, and much of that space will be unused.
If you are creating a KEYONLY dynamic file, make sure the block size is large with respect to the
average key length. Informix recommends you choose a block size that is at least ten times the
average key length. Load factor in a KEYONLY file is based on the percentage of the space in
each block that is occupied by keys and pointers. If the block size is not large with respect to the
average key length, and the hashing is not even, certain groups will be split over and over, resulting in an inefficient distribution.
Dynamic Files and Disk 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.
Tip
See Appendix A - UniData Configuration Parameters, for a list of the configuration parameters.
If you remove all records from a dynamic file with either the ECL CLEAR.FILE command or the
ECL DELETE command with the ALL option, the file returns to its minimum modulo, and the
disk space is returned to the operating system. However, if you remove all records from a dynamic
file using a select list, the file may not return to its minimum modulo. Depending on the order in
which records are removed, some groups resulting from earlier splits may not become eligible for
merging, even though they do not contain any records.
The following examples show splitting and merging in a dynamic file. The first example shows
creating a dynamic file with a minimum modulo of 3:
197
Screen Example
:CREATE.FILE SIZE.TEST 3,2 DYNAMIC
Create file D_SIZE.TEST, modulo/1,blocksize/1024
Hash type = 0
Create dynamic file SIZE.TEST, modulo/3,blocksize/2048
Hash type = 0
Split/Merge type = KEYONLY
Added "@ID", the default record for UniData to DICT SIZE.TEST.
:FILE.STAT SIZE.TEST
File name(Dynamic File)
= SIZE.TEST
Number of groups in file (modulo)
= 3
Dynamic hashing, hash type
= 0
Split/Merge type
= KEYONLY
Block size
= 2048
Number of records
= 0
Total number of bytes
= 0
.
.
.
File has 1 over files, 1 prime files
:!DIR SIZE.TEST
Directory of C:\Informix\ud52\claireg\SIZE.TEST
11/09/98
11/09/98
11/09/98
11/09/98
02:01p
<DIR>
.
02:01p
<DIR>
..
02:01p
8,192 dat001
02:01p
2,048 over001
4 File(s)
10,240 bytes
2,841,095,680 bytes free
198
Because the file was created with a block size multiplier of two, the size of each block is
2048 bytes.
The primary file (dat001) has one block for the file header, and three for the data.
The overflow file (over001) is initially allocated one block for its header.
Because the split/merge type was not specified, the file was created as a KEYONLY file.
The next example shows what happens when the dynamic file is populated with records:
Screen Example
:COPY FROM DICT VOC TO DICT SIZE.TEST ALL
@ID exists in SIZE.TEST, cannot overwrite
58 records copied
:COPY FROM VOC TO SIZE.TEST ALL
489 records copied
:!DIR SIZE.TEST\*
11/09/98
11/09/98
11/09/98
11/09/98
02:01p
<DIR>
02:01p
<DIR>
02:05p
02:05p
4 File(s)
.
..
24,576 dat001
12,288 over001
36,864 bytes
2,841,068,032 bytes free
The FILE.STAT command shows the following output:
Screen Example
= SIZE.TEST
= 12
= 0
Split/Merge type
= KEYONLY
Block size
= 2048
File has 3 groups in level one overflow.
Number of records
= 489
= 12590
Average number of records per group
Standard deviation from average
= 44.5
= 13.2
199
Average number of bytes per group

= 1144.5
= 459.4
Average number of bytes

Average number of bytes
Standard deviation from
Minimum number of bytes
Maximum number of bytes
=
=
=
=
=
in a record
in record ID
average
in a record
in a record
Minimum number of fields in a record

Maximum number of fields in a record
Average number of fields per record
25.7
7.9
35.5
6
379
= 1
= 10
= 2.2
= 0.7

:!DIR SIZE.TEST
11/09/98 02:01p
<DIR>
.
11/09/98 02:01p
<DIR>
..
11/09/98 02:05p
26,624 dat001
11/09/98 02:05p
20,480 over001
4 File(s)
47,104 bytes
2,841,068,032 bytes free
200
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:
Screen Example
:SELECT SIZE.TEST
>DELETE SIZE.TEST
Do you want to delete records in select
.
.
.
=
=
=
Split/Merge type
=
Block size
=
Number of records
=
=
.
.
.
.
.
.
::!DIR SIZE.TEST
list?(Y/N)Y
SIZE.TEST
10
0
KEYONLY
2048
0
0
11/09/98 02:01p
<DIR>
.
11/09/98 02:01p
<DIR>
..
11/09/98 02:05p
26,624 dat001
11/09/98 02:05p
20,480 over001
201
4 File(s)
47,104 bytes
2,841,068,032 bytes free
Merging has reduced the modulo to 10.
The file size as measured at the operating system level has not changed from the previous
example.
Some groups did not merge, and the groups that were added remain allocated to the file.
The final example shows the results of CLEAR.FILE:
Screen Example
:CLEAR.FILE SIZE.TEST
SIZE.TEST is cleared.
Split/Merge type
Block size
Number of records
=
=
=
=
=
=
=
SIZE.TEST
3
0
KEYONLY
2048
0
0
Average number of records per group

Average number of bytes per group
=
=
=
=
0.0
0.0
0.0
0.0
Average number of bytes in a record

Minimum number of bytes in a record
Maximum number of bytes in a record
= 0.0
= 0
= 0
Minimum number of fields

Maximum number of fields
Average number of fields
File has 1 over files, 1
= 0
= 0
= 0.0
in a record
in a record
per record
prime files
:!DIR SIZE.TEST
202

11/09/98
11/09/98
11/09/98
11/09/98
02:01p
<DIR>
.
02:01p
<DIR>
..
02:01p
8,192 dat001
02:01p
2,048 over001
4 File(s)
10,240 bytes
2,841,095,680 bytes free
The ECL CLEAR.FILE command returns the file to its original modulo and size.
203
Sequentially Hashed Files

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

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. Registers
within UniData track how blocks in over001 are linked to groups in dat001. If over001 gets too
large, UniData adds additional blocks to it. If the current file system becomes full, or over001
grows larger than a UniData limit, UniData creates an over002 file.
If the sequentially hashed file has level 2 overflow, the file should be rebuilt using the shfbuild
command.
The gmekey File

Each sequentially hashed file contains a static, read-only file called the gmekey file. UniData reads
this file into memory when you open a sequentially hashed file. The gmekey file contains
information about the type of keys in the file (alpha or numeric), and controls which group a
record is hashed to when it is written.
You create a sequentially hashed file by converting an existing dynamic or static file with the
shfbuild command:
204
Sequentially Hashed Files
Syntax:
shfbuild [-a |-k] [-n | -t] [-f] [-e empty percent] [-m modulo] [-b block size multiplier] [-i
infile] outfile
To convert an existing file, execute the shfbuild command from the system level prompt, as shown
in the following example:
Screen Example
% shfbuild -m 59 SEQUENTIAL
175 keys found from SEQUENTIAL.
175 records appended to SEQUENTIAL; current modulo is 59.
After converting a file to a sequentially hashed file, you must manually enter a file pointer in the
VOC file in order to access the sequentially hashed file, as shown in the following example:
Screen Example
:AE VOC SEQUENTIAL
Top of New "SEQUENTIAL" in "VOC".
*--: I
001= F
002= SEQUENTIAL
003= D_SEQUENTIAL
*--: FI
Filed "SEQUENTIAL" in file "VOC".
205
DIR-Type Files
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:
Screen Example
:!DIR BP\*
Volume in drive D has no label.
Volume Serial Number is 4CD1-467F
Directory of D:\UniData\ACCOUNT\BP
11/11/98
11/11/98
11/11/98
11/11/98
11/11/98
11/11/98
10:58a
<DIR>
.
10:58a
<DIR>
..
10:58a
34 MAINPROG
10:58a
58 SUBPROG
10:58a
86 _MAINPROG
10:58a
168 _SUBPROG
6 File(s)
346 bytes
796,589,568 bytes free
In the example, MAINPROG and SUBR are UniBasic source files. _MAINPROG and _SUBR are
compiled programs.
Multilevel Files (MULTIFILES)

A UniData multilevel (LF type) file is a NTFS directory that contains one or more UniData hashed
files. All of the UniData hashed files share a common dictionary. To access a record, you must
specify both the directory and the hashed file where the record is located. The following screen
shows an example of a multilevel file:
206
DIR-Type Files
Screen Example
:CT VOC MULTI1
VOC:
MULTI1:
LF
MULTI1
D_MULTI1
:!DIR MULTI1\*
Directory of D:\UniData\ACCOUNT\MULTI1
11/11/98
11/11/98
11/11/98
11/11/98
11/11/98
11:00a
<DIR>
11:00a
<DIR>
11:00a
11:00a
11:00a
5 File(s)
.
..
4,096 MULTI1
4,096 MULTI2
4,096 MULTI3
12,288 bytes
Note
If the subfile of a multilevel file has the same name as the directory, you can use the directory
name only to access the subfile. For instance, LIST MULTI1 is correct syntax if the directory
MULTI1 contains subfile MULTI1.
Points to Remember About Multilevel Files
A UniData multilevel file is a NTFS directory that contains UniData hashed files.
Each multilevel file may contain a mixture of static and dynamic hashed files.
All of the hashed files in a multilevel file share the same dictionary.
UniData supports multilevel files to simplify conversion for legacy applications. The
multilevel structure allows a number of data files to share a single dictionary. However,
207
multilevel files are less efficient than ordinary static or dynamic files. The leveled structure means more system resources are needed to read and update these files. For this
reason, Informix recommends using ordinary static or dynamic hashed files rather than
multilevel files whenever possible. You can share a single dictionary between UniData
files by modifying the VOC entries for each file to reference the same dictionary.
208
Multilevel Directory Files
Multilevel Directory Files

A UniData multilevel directory (LD) file is a NTFS directory. The NTFS directory contains one or
more NTFS subdirectories (UniData DIR type files). All of the DIR files share the same dictionary. To access a record, you must specify both the multilevel directory file and the DIR file where
the record resides. The following example shows some characteristics of a multilevel directory
file:
Screen Example
:CT VOC MULTID
VOC:
MULTID:
LD
MULTID
D_MULTID
:!DIR MULTID\*
Directory of D:\UniData\ACCOUNT\MULTID
11/11/98
11/11/98
11/11/98
11/11/98
11/11/98
11:01a
<DIR>
.
11:01a
<DIR>
..
11:01a
<DIR>
TEST1
11:01a
<DIR>
TEST2
11:01a
<DIR>
TEST3
5 File(s)
0 bytes
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.
209
Points to Remember About Multilevel Directory Files
210
A UniData multilevel directory file is a NTFS directory that contains UniData DIR files
(NTFS subdirectories).
All of the DIR files in a multilevel file share the same dictionary.
Each record in a multilevel directory is a NTFS file.
UniData supports multilevel directory files to simplify conversion for legacy applications.
However, multilevel directory files are less efficient than ordinary DIR files. The leveled
structure means that more system resources are needed to read and update these files. For
this reason, Informix recommends using ordinary DIR files rather than multilevel
directory files whenever possible. You can share a single dictionary between UniData DIR
files by modifying the VOC entries for each file to reference the same dictionary.

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 updata a UniData data file, its associated indexes are updated at the
same time. You can turn off automatic indexing on one or more data files (using the ECL
DISABLE.INDEX command) to speed performance during periods of heavy activity on your
system. If you turn off automatic indexing, UniData stores all index updates in an index log file.
The ECL UPDATE.INDEX command applies updates from index logs to indexes in batch mode,
and the ECL ENABLE.INDEX command turns automatic updating back on. The
ENABLE.INDEX command also creates an index log file if one is not already there.
DELETE.INDEX (with the ALL option) removes the index log file.
See the UniData Commands Reference for additional information about index handling
commands.
Index-Related Files for a Static Hashed 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 example shows a sample account where a static file
named STATIC.TST has been indexed:
Screen Example
:!DIR/D
211
Directory of D:\UniData\ACCOUNT
[.]
[..]
AE_COMS
[AE_SCRATCH]
[CTLG]
D_AE_COMS
D_AE_SCRATCH
D_BP
D_CTLG
D_MENUFILE
D__SCREEN_
D_MULTI1
D___V__VIEW
D_MULTID
L_STATIC_TST
D_SAVEDLISTS
MENUFILE
D_STATIC_TST
[MULTID]
D_VOC
[SAVEDLISTS]
D__HOLD_
[SAVEDLISTSL]
D__PH_
STATIC_TST
D__REPORT_
udt_shell4B.tmp
37 File(s)
259,060 bytes
VOC
X_STATIC_TST
[_HOLD_]
[_PH_]
_SCREEN_
__V__VIEW
X_STATIC.TST is the index file for the data file STATIC.TST, and L_STATIC.TST is the index
log file.
Index-Related Files for a Dynamic Hashed File

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:
Screen Example
:!DIR ORDERS\*
Directory of D:\UniData\demo\ORDERS
11/11/98
11/11/98
11/11/98
11/11/98
11/05/98
11/11/98
212
11:16a
<DIR>
11:16a
<DIR>
11:16a
11:16a
10:58a
11:16a
6 File(s)
.
..
24,576 dat001
20,480 idx001
9,216 over001
20 xlog001
54,292 bytes

:
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).
213
File-Handling Commands
UniData includes a variety of commands for users to create and delete UniData files as well as to
obtain status information, change file parameters, and diagnose and repair damaged hashed files.
The following table describes ECL file-handling commands and indicates the UniData file types
they affect.
Command
Description
CREATE.FILE
Creates a UniData file; works for static and dynamic hashed files,
dictionary files, DIR files, multilevel files and multilevel directories.
DELETE.FILE
Deletes a UniData file; works for static, dynamic, and 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 hashed 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.
ECL File Commands
214
File-Handling Commands
Command
Description
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 and static hashed multilevel subfiles.
Does not work on directories, multilevel directories or subdirectories,
dictionaries, or any dynamic hashed file or subfile.
ANALYZE.FILE
Displays statistics, including current and minimum modulo, hash type,

block size, split/merge type, split load, merge load, and record
distribution for a dynamic file. Works on dynamic and sequentially
hashed files and dynamic hashed multilevel subfiles only.
CONFIGURE.FILE
Changes split/merge type, split load, merge load, part table, or minimum
modulo for a dynamic file. Works on dynamic hashed files and dynamic
hashed multilevel subfiles only.
REBUILD.FILE
Reconstructs a dynamic file using current settings for split load, merge
load, and minimum modulo. Used after CONFIGURE.FILE. Works on
dynamic hashed files and dynamic hashed multilevel subfiles only.
CHECKOVER
Checks UniData hashed files for level 2 overflow. Works on all UniData
hashed files and subfiles. Used to check all files in a UniData account
directory.
ECL File Commands (continued)
See the UniData Commands Reference for detailed information about the syntax of the
file-handling commands.
215
The next table describes UniData system-level file-handling commands.

Command
Description
checkover
Checks UniData hashed files for level 2 overflow. Works on all UniData hashed
files and subfiles. Checks all files in a UniData account directory. The systemlevel version can be executed with UniData shut down or with UniData running.
dumpgroup
Unloads the contents of a damaged group in a hashed file; can be executed with
UniData shut down or with UniData running.
fixfile
Repairs damaged groups in a file; can be executed with UniData shut down or
with UniData running.
fixgroup
Repairs a damaged group; can be executed with UniData shut down or with
UniData running.
guide
Identifies damaged hashed files or dictionary files. Cannot be executed if

UniData is shut down.
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 it is executed from the systemlevel prompt, you cannot run it UniData is shut down. memresize also converts
static files to dynamic files, dynamic files to static files, and changes the
split/merge type and part table for dynamic files.
shfbuild
Converts a static or dynamic file to a sequentially hashed file.
verify2
Identifies damaged hashed files or dictionary files; you cannot execute if

UniData is running.
UniData System-Level File Commands
216
File Corruption
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 enable you to detect and repair
damaged files.
Note
UniData file tools do not detect or repair invalid or inconsistent data in files. Detecting data
inconsistencies should take place at the application level.
What Causes File Corruption?

File corruption can result from a variety of causes:
Hardware failures, including CPU crashes, media or memory failure, controller failures,
bad spots on a disk.
Interrupting a write in progress; for example, terminating a UDTelnet Service while users
are still logged in.
Incomplete writes; for example, a disk runs out of space before a write is complete.
Note
Overflowed files are more likely to become corrupted, since multiple I/O operations can be
required to accomplish a single read or write to an overflowed file. An interrupted write can result
in a condition where a primary data block and corresponding overflow blocks are out of synch.
The increased chance of corruption is particularly significant for files in level 2 overflow.
217
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. Informix strongly
recommends you monitor and minimize level 2 overflow. Using dynamic files versus static files
minimizes level 2 overflow, which provides some protection. However, using dynamic files
greatly increases level 1 overflow, making the risk of file corruption greater than that for static
files.
Certain UniData commands carry a direct risk of file corruption, as shown in the following table.
Command
Risk Factor
deleteuser
This UniData command first tries to gracefully terminate a

process. If unsuccessful, deleteuser forces the process to
terminate.
stopud -f
This syntax of the stopud command does not allow writes to

complete before logging users off.
UniData Commands That Can Corrupt a File
There are other operations that can corrupt UniData files; the following list contains some
examples:
218
Stopping the UniData Telnet Service (UDTelnet) or the UniData Terminal Server
(UDSerial) while users are logged in.
Attempting to view/edit a UniData file with an MS-DOS text, octal, or binary editor can
damage the file whether or not UniData is running. In many cases, the file damage is
irreversible.
Backing up and restoring a UniData file while users are accessing the file during backup
may damage the restored file. Any UniData file can be damaged in this way, but the risk is
particularly great for dynamic files.
File Corruption
Note
The file being backed up is not damaged. Danger is only to the file being restored.
219
UniData Detection Tools

UniData supplies the following tools for detecting damaged files:
guide Use the guide command to detect file damage when UniData is running.
verify2 Use the verify2 command to detect file damage when UniData is not running.
guide
Syntax:
guide [file1, file2,...][-options]
Note
You may supply guide with the name of a single UniData file or a series of file names separated by
commas or spaces. If you do not specify any files, guide processes all files in the current UniData
account directory.
Description
guide is a Unidata-supplied, system-level utility that provides detailed statistics and suggestions
for optimizing file size and ensuring data integrity.
220
Options
The following table lists the options available for the guide command.
Option
-a |-A [filename]
-na | -NA
(no advice)
-b | -B [filename]
-nb | -NB
Description
Controls whether management advice is included in the output. The
default file name for the advice information is GUIDE_ADVICE.LIS.
You cannot combine the -a and -o options, because UniData assumes the
-a option when the -o (output) option is present. You may use the -na
option in combination with the -o option.
Controls whether UniData produces a file containing a brief summary of
statistical information. The default file name is GUIDE_BRIEF.LIS.
(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.
UniData assumes the -e option when the -o (output) option is present, and
may not be specified at that time. You may, however, use the -ne option in
combination with the -o option.
-ne | -NE
(no errors)
-f | -F [filename]
Specifies the file that should receive a list of damaged groups. The default
filename, if none is specified, is GUIDE_FIXUP.DAT. UniData creates
this file only if it detects errors.
guide Command Options
221
Option
Description
-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
test) option. This option has no effect when specified for a dynamic file.
new_modulo
-o | -O [filename]
Controls whether output is combined or directed to separate files. If you

specify -o, UniData directs all output to the file specified by filename. If
you do not specify a file name, UniData directs the output from guide to
standard out (usually, your terminal).
guide Command Options (continued)
222
Option
Description
-p | -P page_length
Controls the display of guide output when you specify the -o option and
direct output to the terminal. Specify -np to scroll the output past with no
pause. Specify -p page-length to pause after displaying each page and
prompt with the following message: Press RETURN to continue... The
following responses are accepted at the prompt:
-np | -NP
(no pagination)
<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
GUIDE_STATS.LIS. (The -s (statistics) option is assumed when the -o
(output) option is present, and may not be specified at that time.) You may
use the -ne (no errors) option in combination with the -o option.
-ns | -NS
(no statistics)
guide Command Options (continued)
223
guide Output
The guide utility can create five output files. The following table lists these files. You may 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
Contains a list of damaged groups that can be used as input for fixfile.
This list can also be used to input file names/group numbers for
dumpgroup/fixgroup.
guide Output Files
If you do not specify options, UniData selects the default options: -a, -e, -f, and -s, and places the
results in the default files.
The guide utility checks for existing output files. If there are existing output files, guide appends a
timestamp to the end of the existing file before it creates the current output file. The most current
output files will not have this time stamp. UniData does not overwrite output files generated in a
previous analysis. As a result, you may accumulate a large number of files that you should purge
periodically.
guide Report File

You can use the -r option of guide to create a UniData file containing statistical information about
your database. To use the option, complete the following steps:
1. Create a UniData file in the account where you are running guide.
2. Copy the records from udthome\sys\D_UDT_GUIDE to the dictionary of the file you created
in step 1.
224
3. Execute guide -r filename, where filename is the UniData file you created in step 1.
The guide utility creates statistical information in filename about the evaluated files. The records
contain 62 attributes and are keyed by VOC entry name. You can use UniQuery or ECL
commands, or write UniBasic code, to analyze the data and produce reports.
guide Example
The following example shows output from guide executed against a directory that contains a
damaged file:
Screen Example
# guide -na -ns
# pg GUIDE_ERRORS.LIS
TEST.FILE
File Integrity:
Group 1, block 2, record number 0 = "10053"
invalid offset 2047 or length 110
Primary group 1, block 2 has 1 offset(s) less than the offset of the group
header
Group 1, block 2 bytes left 790 is wrong.
Group 1, block 1 is pointed to by multiple links
Group 1, block 1 has incorrect group number 0
Files processed:
183
Errors encountered: 5
# pg GUIDE_FIXUP.DAT
TEST.FILE
1
Notice that group 1 of TEST.FILE is damaged.
Note
guide works only if UniData is running.
225
guide_ndx
Syntax:
guide_ndx{-x | -X} {1 | 2 | 3}, {index_names, ... | ALL} [-t template | -T template] filename
Description
As with other UniData file types, an index file could become corrupt due to hardware failures, the
interruption of a write to the index file, or an incomplete write. The guide_ndx utility checks for
physical and logical corruption of an index file.
If an index file is corrupt, UniData displays a run time error when a UniData process tries to access
the index. If the index file is associated with a recoverable file, a message is written to the sm.log.
The guide_ndx command creates two files, the GUIDE_XERROR.LIS and the
GUIDE_STATS.LIS. GUIDE_ERROR.LIS lists any corruption found in the index file, and
GUIDE_STATS.LIS list statistics about the index. If you have a corrupt index, you must rebuild it
using the CREATE.INDEX and BUILD.INDEX commands. For more information and creating
and building indexes, see Using UniData.
Note
Informix recommends deleting the index with the DELETE.INDEX ALL command. Using the
ALL option deletes all alternate key indexes and the index file itself.
Parameters
The following table describes each parameter of the syntax.
Parameter
-x{1 | 2 | 3}
Description
Determines the type of checking guide_ndx performs:
1 Perform physical checking
2 Perform logical checking
3 Perform physical and logical checking
guide_ndx Parameters
226
Parameter
Description
index_names
The index names you want guide_ndx to check. Separate each index name
with a comma, or enter ALL to check all indexes for the file.
-t template
The template to use for output files. The default is GUIDE.
filename
The name of the data file containing the index.

guide_ndx Parameters (continued)
Example
The following example illustrates the contents of the GUIDE_XERROR.LIS file when guide_ndx
detects corruption:
Screen Example
% pg GUIDE_XERROR.LIS
INVENTORY
Checking index 'INV_DATE' physically...
Invalid key length (30569, key item 65) in node 24576.
Bytes left not matched (recorded 3157, calulated 4933) in node 24576.
Checking index 'FEATURES' physically...
Checking index 'COLOR' physically...
The next example illustrates the GUIDE_XSTATS.LIS file:
Screen Example
% pg GUIDE_XSTATS.LIS
INVENTORY
Large index..........
Alternate key length.
Node/Block size......
OV blocks............
# of indices.........
INVENTORY/idx001
60
6K
1
3
227
Index auto update.... Enabled, No updates pending

Index Name
INV_DATE
FEATURES
COLOR
F-type
D
D
D
V-type
S
S
M
K-type
N
T
T
Nulls
Yes
Yes
Yes
Dups
Yes
Yes
Yes
F-No/VF-pos (Root)
1 (24576 [1-4])
4 (30720 [1-5])
5 (36864 [1-6])
The following table describes the column heading that display in output for the X_STATS.LIS
file.
Column
Heading
Description
Index name
Name of the index.
F-type
Type of attribute indexed: D for data attribute, V for a virtual attribute.
V-type
Value code for the attribute. S for singlevalues, M for multivalued or multisubvalued.
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 built on data attributes
(D-type) or the virtual attribute definition for alternate key indexes built on
virtual attributes (V-type).
X_STATS.LIS Display
verify2
Syntax:
verify2 [-Y | -y] [-H | -h block address] [-O | -o block address]
228
Description
The verify2 command, like guide, detects file corruption. Although verify2 does not produce as
much information as guide, and does not produce the damaged group list for repair, verify2 runs
much more quickly, runs with UniData down, and can be used for a rapid scan of files.
Parameters:
Parameter
Description
[-Y | -y]
Writes the filename and @ID of damaged records to a file called

\tmp\vrfy2.pid, where pid is the process ID of the process that
executed verify2.
[-H | -h block address]
Bypasses checking the block whose hexadecimal address is

block address. This option allows you to bypass a single
damaged block, if you know its address, and examine the rest of
the file.
[-O | -o block address]
Same as -h option, but -o allows you to bypass a block in the

overflow portion of a dynamic file.
verify2 Parameters
229
The following example shows typical output from verify2 on files that are not damaged:
Screen Example
# verify2 ORDERS
Static File Name -------------->
File Size --------------------->
Modulo ------------------------>
Hash Type --------------------->
Block Size -------------------->
Number of groups checked: 101
file is in good status.
# verify2 DYN.TEST
Dynamic File Name ------------->
Primary File Number ----------->
Overflow File Number ---------->
Modulo ------------------------>
Minimal Modulo ---------------->
Hash Type --------------------->
Block Size -------------------->
file is in good status.
ORDERS
104448 (102 blocks)
101
0
1024
DYN.TEST
1
1
3
3
0
1024
The next example shows output from verify2 on a damaged file:
Screen Example
# verify2 TEST.FILE
Static File Name --------------> TEST.FILE
File Size ---------------------> 104448 (102 blocks)
Modulo ------------------------> 101
Hash Type ---------------------> 0
Block Size --------------------> 1024
the 0th[10053] off_lens error,offset=7ff,len=110.
group 1 errors in header(2048).
1 key(s) are damaged.
file has something damaged.
230
Notice that group 1 is damaged.
231
UniData Recovery Tools

UniData includes the following commands to recover corrupted hashed files:
dumpgroupUse this command to unload complete and valid records from a damaged
group, separating valid records from damaged records.
fixgroupUse this command to clear records from a damaged group and to reload and
rebuild the group with the valid records unloaded by dumpgroup.
fixfileUse fixfile in conjunction with guide. guide provides a FIXUP.DAT file that lists
corrupt files and groups. fixfile uses FIXUP.DAT to unload, clear, and rebuild the damaged groups.
dumpgroup
Syntax:
dumpgroup filename group.no [-doutputfile] [-p]
Description
The system-level dumpgroup command unloads readable records from a group you specify in a
UniData file. If the file was corrupted, dumpgroup unloads complete, valid records, leaving behind
any information it cannot read.
Parameters
Parameter
Description
filename
Specifies the name of the file containing groups to be dumped.
group.no
Specifies the number of the group to dump. The output from either guide or
verify2 identifies groups that are damaged. Use this information to select
groups to process.
Parameters of dumpgroup Command
232
Parameter
Description
[-doutputfile]
Specifies the name of a file that contains the readable records from the dumped
group, in an uneditable form. If you do not specify the -d parameter with an
outputfile, the output prints to screen. To load outputfile back into the file, use
fixgroup. Note: No space is allowed between -d and outputfile.
[-p]
Converst nonprinting field markers to printable characters in editable output

file. This option is only valid if -d is used.
Parameters of dumpgroup Command (continued)
If you execute dumpgroup without specifying an output file, the output simply displays on the
screen. You will not be able to use that output to verify records or repair the damaged group. If you
do specify an output file, UniData places the records in uneditable form, suitable for reloading,
into the output file. UniData also creates a directory within your current account for each dumped
group. The directory is named FILE_GROUP, where FILE and GROUP are the filename and
group number you specify on the command line. This directory contains an ASCII file for each
record, so that you can check them for consistency before reloading the damaged file.
Warning
When you use the -d option, make sure you name your output file with a name that does not
already exist in your account name. If you specify a duplicate name, the preexisting file may be
overwritten.
fixgroup
Syntax:
fixgroup filename group.no [-iinputfile] [-k]
The system level fixgroup command reloads a hashed file group based on a file created by the
dumpgroup command.
233

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.
fixgroup Parameters
Warning
If you execute fixgroup without an input file argument, UniData clears the damaged group. Be
sure that you have saved the readable records with dumpgroup before clearing the group. If you
clear the damaged group and you have not saved the readable records, the data in that group is lost.
The syntax for clearing a group without reloading it is:
fixgroup filename group.no
UniData displays a warning message before clearing the group, as shown in the following
example:
%fixgroup INVENTORY 5
Fixgroup INVENTORY 5 will make group 5 empty,
do you wish to do it ?
[y/n]
234
fixfile
Syntax:
fixfile {-t | {-dfilename | -k | -p | -f}} [-mfilename] [-wdirectory]
[-ifilename | filename group.no]
The system-level fixfile command repairs damaged groups in UniData files by clearing the group
and optionally restoring readable records to the group. Use fixfile in conjunction with the guide
utility. Do not let users access files while fixfile is running because you could lose records.
The following table describes each parameter of the fixfile syntax.
Parameter
{-t}
Description
Direct all output to the terminal only. Each readable record is described in a new
line that includes the record key and the record length. All attributes in the
record appear on separate lines, each line indented by two spaces. Special and
nonprintable characters are translated as follows:
Attribute Mark New line
Value Mark }
Subvalue Mark |
Text Mark {
Non-printables .
Note - The -t and -d parameters are mutually exclusive and cannot be used
together.
{-dfilename}
A file specification is required. For static files, dumps the readable records to
this file in uneditable format. For dynamic files, UniData creates this file, but
dumps the actual records to a file in \temp.
With the -d option, UniData also writes the records, in readable format, to a
directory in your current UniData account. This directory contains an ASCII file
for each readable record in the group. The records are in a format suitable for
editing. To repair any file, you need both the -d and -f options.
fixfile Command
235
Parameter
Description
{-k}
If you specify the -k option with the -d option, UniData does not clear the
damaged groups. This has the effect of dumping the readable records for
examination, but leaving the file corrupt. If you specify the -d and -f option
along with the -k option, UniData repairs the file and returns the readable
records to the group. Any unreadable records that UniData did not dump remain
in the file as well.
{-p}
If you specify the -p option with the -d option, UniData translates all
non-printing characters and characters with special meaning to UniData. This
translation applies to the editable ASCII files created by the -d option. If you do
not specify the -p option, only attribute marks are translated.
{-f}
If you specify the -f option with the -d option, UniData clears the damaged
group and restores the records that were dumped back into the group, creating a
fixed file with all readable data restored. You must specify the -d option with the
-f option.
[-mfilename]
UniData writes all error messages and statistics to the file you specify, instead of
the terminal.
[-wdirectory]
UniData creates the work files that are generated in the directory you specify.
{-ifilename}
UniData uses this file as the source of the names of damaged files and groups to
be repaired. If you do not use this option or the {filename group.no} option,
UniData uses the GUIDE_FIXUP.DAT file under the current directory. This
option is mutually exclusive with {filename group.no}.
{filename
group.no}
The file name and group number that contains the corruption. If you do not use
this option or the {-ifilename} option, UniData uses the GUIDE_FIXUP.DAT
file under the current directory. This option is mutually exclusive with the
{-ifilename} option.
fixfile Command (continued)
236
How fixfile Works with Static Files

When you run fixfile with the -t option on a static file, UniData displays the readable records from
the file and group to the terminal. UniData does not clear or repair the group. You can supply the
names of damaged files and groups from the command line or from an input file. The default input
file is GUIDE_FIXUP.DAT.
When you run fixfile with -dfilename on a static file, UniData creates:
An NTFS directory or directories for the files and groups being repaired. If only one group
in a file is damaged, the directory is named FILE_GROUP, where FILE is the damaged
file (from GUIDE_FIXUP.DAT or verify2) and GROUP is the damaged group. If several
groups in a file are damaged, UniData creates a directory named FILE_dir.
Each FILE_GROUP directory contains an ASCII file for every readable record in the
damaged group. Each filename 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 filename
is the key for the corresponding UniData record. These records are in a format suitable
for editing.
A file, with the name you specify on the command line, that contains the records fixfile
could read, in uneditable format. This file is used to reload the records into the damaged
groups after the groups are cleared.
Note
If you specify the -p option, fixfile translates nonprinting characters in the records when it creates
the editable files. Otherwise, UniData translates only attribute marks to new lines.
When you run fixfile with the -d and -f options on a static file, UniData reloads the records into the
damaged groups, taking them from the file you specify on the command line. Unless you specify
the -k option, fixfile clears the groups, removing all contents, before reloading the data. If you
specify the -k option, UniData adds the records back, but does not clear any data from the group.
237
Reminder
It is possible to run fixfile in two steps, one to dump the records for review and the second to repair
the file. To dump the records only, run fixfile with the -d option, but without the -f option. Unless
you specify the -k option, running fixfile with the -dfilename deletes the readable data from the
specified groups when it creates output. To repair the file, run fixfile with both -d and -f options.
How fixfile Works with Dynamic Files

When you execute fixfile with the -d option on a dynamic file, UniData creates the following:
An NTFS directory located in \temp for each file-group combination being repaired. The
directories are named FILE_GROUP where FILE is a damaged file (from
GUIDE_FIXUP.DAT or verify2) and GROUP is a damaged group. If several groups in a
file are damaged, UniData creates a directory for each damaged group.
Each FILE_GROUP directory contains an ASCII file for every readable record in the
damaged group. Each records 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 \temp (or in the directory
identified by the TMP environment variable) and is named ud_dp_pid, where pid is the
process ID of the process that executed fixfile.
Note
If you specify the -p option, fixfile translates nonprinting characters in the records when it creates
the editable files. Otherwise, UniData translates only attribute marks to new lines.
When you run fixfile with the -d and -f options on a dynamic file, UniData reads the file you
specify with the -d option on the command line and also reads the uneditable file of dumped
records. UniData then reloads the records from that file into the damaged groups. Unless you
specify the -k option, fixfile clears the groups, removing all contents, before reloading the data.
Otherwise, UniData adds the records back, but does not clear any data from the group.
238
Reminder
You can run fixfile in two steps, one to dump the records for review and the second to repair the
file. To dump the records for review, run fixfile with the -d option, but without the -f option. (You
do not need to use -k for dynamic files. For dynamic files, running fixfile with -dfilename and not
-f does not delete the readable data from the specified groups when it creates output.) To repair the
file, run fixfile with both the -d and -f options. If you specify the same filename with -d in both the
review and repair steps, UniData will prompt whether or not to clear the damaged groups.
239
Detection and Repair Examples

The following example shows typical output from running guide against a damaged file:
The output displays statistics and then reports which groups are damaged. In this case, group 1 is
damaged.
The next example shows the output from dumping the records from the damaged group with
dumpgroup:
240
Detection and Repair Examples
At this point you can review the directory CLIENTS_1, containing a file for each record that was
dumped from group 1.You should verify that the data in each record is valid. The following
example shows the output from rebuilding the damaged group with fixgroup:
The following examples show a damaged CLIENTS file and a damaged TESTFILE being repaired
using guide and fixfile. The first screen shows output from guide:
Screen Example
:!TYPE GUIDE_ERRORS.LIS
CALLBASIC_DEMO/EXAMPLE1/callbasic_example1.mdp
Unable to open file or file is not Unidata data file.
CALLBASIC_DEMO/EXAMPLE1/callbasic_example1.ncb
Unable to open file or file is not Unidata data file.
CLIENTS
File Integrity:
Group 3, block 23 has invalid offset 24929
TESTFILE
File Integrity:
Group 1, block 6231 has invalid offset 6381921
241
Files processed:
49
Errors encountered: 4
:
The next example shows output from fixfile:
Screen Example
:!FIXFILE -DOUTFILE -F
**** Record Key='10037', Record length=126
.
.
.
**** Record Key='SELECT.ONLY', Record length=14
Record key
: 10037
Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10037a
Record key
: 9983
Record key
: 10018
Record key
: 10094
Record key
: 10075
Record key
: 10056
6 records dumped for group 3 of D:\UniData\demo\CLIENTS.
1 block6 records written to group 3 of file D:\UniData\demo\CLIENTS.
27 records dumped for group 1 of D:\UniData\demo\TESTFILE.
1 block27 records written to group 1 of file D:\UniData\demo\TESTFILE.
:
242
How to Use guide
How to Use guide

The steps listed below provide guidelines for effectively using the guide utility.
1. Monitor File Integrity with guide

You should execute guide against your database at regular intervals, as well as when you have had
a system crash. You can set up shell scripts to run guide at specified intervals on specified lists of
files, or you can simply execute the guide command in each UniData account.You can execute
guide against static hashed files at any time, and schedule guide to run on dynamic files at a time
when the system is idle or only lightly loaded.
Reminder
The guide utility requires exclusive access to process any dynamic file. There are two
considerations: first, if you run guide against such files while the system is under heavy load, guide
may be unable to process the majority of your files. Second, if guide is able to gain exclusive
access to a file, UniData blocks other access to that file until guide completes.
2. Check Error Output (GUIDE_ERRORS.LIS)

Use the following information to determine what action to take, depending on the error output.
No Errors
If there are no errors, proceed to step 5.
Partially Allocated Block Messages

Partially allocated block messages are not false error reports; they indicate an out-of-synch
condition in a dynamic file, but they do not mean that the file must be fixed immediately. Users
can continue to access the file; this will not cause damage. Complete the repair at a convenient
time using the procedure in step 3.
243
Partially allocated block messages look like:

free block xx partially allocated, xxx bytes remaining
Block xx of primary file not a member of any group
Other guide Error Messages

guide produces many messages besides the one discussed above. If you see error messages
pertaining only to static files, or if you see other error messages pertaining to dynamic files,
proceed to step 3.
3. Repair Damaged Files

Complete the following steps:
1. Back up the damaged file(s)If time and space permit, Informix strongly recommends you
back up (or simply make a copy of) the damaged files before proceeding. In the event of a
system failure during the repair process, you will be able to restore from the backup copies and
repeat the procedures rather than attempting to recover a partially-completed repair. DO NOT
ALLOW USERS TO ACCESS YOUR FILES WHILE YOU ARE BACKING THEM UP!
2. Repair the damaged groupsAfter guide completes, you can execute either fixfile or
dumpgroup/fixgroup to repair the damaged groups. In either case, the process overview is:
dump the readable records from a damaged group, clear the group, and then reload all readable
records back into the group.
Tip
Informix recommends that you not use the -k option with fixfile or with fixgroup. The -k option
lets you reload the readable records without clearing the group. However, you may encounter
additional errors if you do not clear the group. Use fixfile or fixgroup without -k; this procedure
automatically clears the group before reloading the readable records.
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.
244
How to Use guide
3. Verify the repairRerun guide after the repair is complete to verify that the errors are fixed.
If they are not, or if additional groups are damaged, repeat the previous step.
4. Back Up the Repaired Files

Back up any files you have just completed repairing.
5. Continue Processing
If you shut UniData down to repair files, start it again before allowing users to log in.
245
Error Messages
This section lists error messages users may see and provides information about the meaning of
them. Some of the messages are generated by the guide command and others are generated by the
verify2 command.
File Access Messages

File access messages are similar to the following example:
Screen 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 or verify2 did not process the file because it was unable
to obtain an exclusive lock on the file.
Reminder
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:
Screen 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.
246
Error Messages
These indicate that a block is found to be referenced by more than one link, which should not
occur. These messages indicate damage.
Screen Example
The xxth block of file (filename) has no link.
the xxth block has no link
A block has been found that is not in the global free chain and is not used by any group. This error
can be reported when guide or verify2 encounters a corrupt block, and is therefore unable to check
blocks linked through the corrupted one.
Group Header Messages

Group header messages are similar to the following example:
Screen 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:
Screen Example
Group xx, block xx key area is corrupted,
keys xx
size xx number of keys xx
key size xx, number of

incorrect key size xx
data position xx, key
total key length xx,
247
key size xx, number of keys xx

keys xx in group header yy error
keysize=xx,keys=xx
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 other header messages, as shown in the following examples:
Screen Example
Group xx, block xx has incorrect group number
The group number recorded in the block header does not match the group being checked.
Screen Example
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.
Screen Example
Group xx, block xx data area is corrupted, incorrect data
position xx
wrong datapos=xx
A data position in a group header is damaged.
248
Error Messages
Screen Example
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 isnt an overflow group, but there is xx offset:are xx
offsets less than the offset of group header
Each group header has an area that stores offset-record length pairs, which are sorted by offset.
Each offset of a record equals the offset of the previous record plus its length. If these conditions
are not met, corruption results, and some or all of the previous messages display.
Screen Example
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.
249
Screen Example
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

Screen Example
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.
Screen Example
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 these
are similar to the following example:
Screen 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
250
Error Messages
(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 and verify2 report messages like the preceding ones.
Dynamic File Messages

Dynamic file message are similar to the following examples:
Screen Example
Overflow file number too large
Primary file number too large
The part file number stored in a data block is invalid.
Screen Example
The next_block(xx) in overflow file header error
The next_block(xx) in free block (xx) is over filesize.
251
The offset to the next global free block list is wrong.
Screen Example
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.
Screen Example
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.
252
UniData Locks
This chapter outlines file, record, and system resource locking within UniData, describes tools for
listing locks and listing the contents of the wait queue, and describes procedures for releasing
locks that remain set when a process exits UniData.
253
Chapter 12 - Managing UniData Locks
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. Prior to UniData 5.0, logical records locks were managed
by the lock control process (lcp) daemon.
How GLM Works

GLM manages local lock tables for each udt process and a shared global lock table in shared
memory, which can be accessed by multiple udt processes. The lock tables are hashed tables
containing linked lists, which contain lock nodes. When a udt process locks a record, UniData
writes the filename, record ID, and lock mode to both the local lock table and the global lock table.
When a udt process requests a lock, UniData first searches that local lock table for the udt to see if
that process is holding the lock, then the global lock table to see if another udt process is holding
the lock.
GLM udtconfig Parameters

There are four udtconfig parameters which control the size of the shared lock table and the
memory UniData allocates for each memory request.
N_GLM_GLOBAL_BUCKET
This parameter defines the number of hash buckets system-wide, used to hold the lock names in
shared memory. This setting directly affects performance. Normally, the default value of this
parameter should not be changed. However, if you notice significant degradation in performance,
or your application intensively accesses specific files, you should increase this parameter. The
value should be the closest prime number to NUSERS * 3.
N_GLM_SELF_BUCKET
This parameter determines the number of hash buckets for the local lock table, and is highly
application dependent. If the application requires a large number of locks in one transaction (more
than 20), this setting should be increased from the default of 23. The setting should be the closest
prime number to the maximum number of locks per transaction.
254
The Global Lock Manager
GLM_MEM_ALLOC
This parameter defines the number of lock nodes allocated for each memory request, and is highly
application dependent. If your application requires a large number of locks in one transaction, this
setting should be increased to the maximum number of locks per transaction * 2.
GLM_MEM_SEGSZ
This parameter specifies the segment size for each shared memory segment required for GLM.
The maximum number of segments is 16. Large application environments require a larger size.
The default value is 10.
GLM_MEM_SEGSZ must be greater than 4096 and less than SHM_MAX_SIZE. The formula for
determining SHM_MAX_SIZE is NUSERS * maximum number of locks per transaction * 512.
SHM_MAX_SIZE should be a multiple of 4096.
255
Locking in UniBasic
A series of UniBasic commands enable users to set read-only locks and exclusive locks on
UniData files and their contents.
How Locks Work

UniBasic locks are advisory rather than physical, meaning that they inform other users of a file or
record that the file or record is in use, rather than explicitly preventing access. You can set
exclusive locks or shared (read-only) locks.
Exclusive Locks (U Type)

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

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

WRITE and DELETE commands execute regardless of lock status. WRITEU, WRITEVU,
MATWRITEU, and DELETEU retain locks set by previous commands. To prevent multiple
updates to records, all WRITE and DELETE commands should be preceded by a lock-setting
command like READU.
256
Locking in UniBasic
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 previously locked with the FILELOCK command.
MATREADL
Assigns the values found in successive attributes of a record to

corresponding elements of a matrix and sets a read-only lock on the
record.
MATREADU
Assigns the values found in successive attributes of a record to

corresponding elements of a matrix and sets an exclusive lock on the
record.
MATWRITE
Writes successive elements of a matrix to the corresponding 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 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
places an exclusive lock on the record. Each subsequent READBCKU
retrieves the previous record in the index.
READFWDL
places a read-only lock on the record. Each subsequent READBCKU
retrieves the next record in the index.
READFWDU
places an exclusive lock on the record. Each subsequent READBCKU
retrieves the next record in the index.
UniBasic Commands for Locking Files and Records
257
Command
Description
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 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.
UniBasic Commands for Locking Files and Records (continued)
258
Resource Locks
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 reserved by the LOCK command.

(UniData does not automatically release these resources when
a program terminates.) This command is not needed to release
file and record locks.
LOCK
Reserves a system resource for exclusive use.
(ECL and UniBasic)

Locking System Resources
Note
Although the LOCK and UNLOCK commands enable users to set and release semaphore locks,
UniData does not necessarily use system-level semaphores to control access to system resources.
The output from LIST.LOCKS and ipcstat may not appear to be consistent, but UniData is
functioning correctly.
259
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 enables any user with access to the ECL prompt to display a
list of file and record locks set on the system.
Syntax:
LIST.READU [user_number | ALL | FILENAME filename | USERNAME user_name]
[DETAIL]
Parameters
Parameter
Description
user_number
Displays all locks held by the user number you specify.
ALL
Displays all currently active locks.
FILENAME filename
Displays all active locks associated with the file name you
specify. If the file name does not reside in the current account,
nothing is displayed.
USERNAME user_name
Displays all active locks associated with the user name you
specify.
DETAIL
Displays detailed information.

LIST.READU Parameters
Examples
The following example illustrates the output from the LIST.READU command when you do not
specify any options.
260
Listing Locks
Screen Example
:LIST.READU
UNO UNBR
UID
3
234 1049668
UNAME
TTY
claireg Console
FILENAME
INVENTORY
RECORD_ID M
TIME
DATE
10060 X 15:40:20 Jun 12
The next example illustrates the output from the LIST.READU command when you specify a user
number. The user number can be found in the output from the LIST.QUEUE and LIST.READU
commands under the UNBR column.
Screen Example
:LIST.READU 196
UNO UNBR
UID
3
196 1049668
UNAME
TTY
claireg Console
FILENAME
INVENTORY
RECORD_ID M
TIME
DATE
10060 X 08:34:39 Jun 13:
The next example illustrates output from the LIST.READU command when you specify a user
name.
Screen Example
:LIST.READU USERNAME claireg
UNO UNBR
UID
UNAME
TTY
2
220 1049668 claireg Console
3
FILENAME
VOC
INVENTORY
RECORD_ID M
TIME
DATE
LIST X 08:10:47 Jun 13
10060 X 08:39:40 Jun 13
The final example illustrates output from the LIST.READU command when you specify a file
name.
Screen Example
:LIST.READU FILENAME INVENTORY
UNO UNBR
UID
UNAME
TTY
3
FILENAME
INVENTORY
RECORD_ID M
TIME
DATE
10060 X 08:39:40 Jun 13
261
LIST.READU Display
The following table describes the output from the LIST.READU command.
Column
Heading
Description
UNO
A sequential number UniData assigns to the udt process that set the lock.
UNBR
The process ID of the user who set the lock.
UID
The user ID of the user who set the lock.
UNAME
The login name of the user who set the lock.
TTY
The terminal device of the user who set the lock.
FILENAME
The filename in which the record is locked.
RECORD_ID
The record ID of the locked record.
The type of lock. X indicates an exclusive lock. S indicates a shared

lock.
TIME
Time the lock was set.
DATE
Date the lock was set.

LIST.READU Display
LIST.LOCKS
Use the ECL LIST.LOCKS command to display semaphore-type locks that reserve system
resources for exclusive use. These locks can be set individually with the LOCK command. They
are also set by other ECL commands, including T.ATT.
Syntax:
LIST.LOCKS
The following examples shows the LIST.LOCKS command and its output:
262
Listing Locks
Screen Example
:LIST.LOCKS
UNO UNBR
UID
1
386 1049668
:
UNAME
TTY
claireg Console
FILENAME
semaphore
RECORD_ID M
TIME
DATE
1 X 09:11:42 Jun 10
Note
If you need to clear a semaphore lock that has been left set, you need to note the UNBR and the
lock number for the lock. In the example, the lock number is 1 for the lock displayed.
LIST.QUEUE
The ECL LIST.QUEUE command displays a list of all processes waiting to get locks. If a process
is waiting for a lock, LIST.QUEUE displays information about the holder of the lock and
processes waiting for the lock. Locks are set by each udt process through the general lock manager
(GLM) module.
Syntax:
LIST.QUEUE [USERNAME user_name | FILENAME filename | user_number][DETAIL]
Parameters
Parameter
Description
USERNAME user_name
Lists all locks the user is waiting for. user_name is the

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

LIST.QUEUE Parameters
The following example illustrates the output from the LIST.QUEUE command when you do not
specify any parameters.
Screen Example
:LIST.QUEUE
FILENAME
RECORD_ID
M OWNER
UNBR
UNO TTY
TIME
DATE
INVENTORY
11060
X clair
6031
2
pts/2
11:05:44 Jun 04
-------------------------------------------------------------------------FILENAME
RECORD_ID
M WAITING
UNBR
UNO TTY
TIME
DATE
INVENTORY
11060
X clair
6130
4
ttyp1
11:05:54 Jun 04
INVENTORY
11060
X clair
6188
1
ttyp3
11:06:04 Jun 04
The next example illustrates the LIST.QUEUE output when you specify a user name:
Screen Example
:LIST.QUEUE USERNAME root
FILENAME
RECORD_ID
M OWNER
INVENTORY
11060
X clair
UNBR
6031
UNO
2
TTY
pts/2
TIME
DATE
11:35:46 Jun 04
-------------------------------------------------------------------------FILENAME
RECORD_ID
M WAITING
UNBR
UNO TTY
TIME
DATE
INVENTORY
11060
X root
6259
5
ttyp2
11:35:56 Jun 04
:
The next example illustrates the LIST.QUEUE command output when you specify a file name:
264
Listing Locks
Screen Example
:LIST.QUEUE FILENAME INVENTORY
FILENAME
RECORD_ID
M OWNER
UNBR
UNO TTY
TIME
DATE
INVENTORY
11060
X root
6259
5
ttyp2
11:38:16 Jun 04
-------------------------------------------------------------------------FILENAME
RECORD_ID
M WAITING
UNBR
UNO TTY
TIME
DATE
INVENTORY
11060
X clair
6188
1
ttyp3
11:38:36 Jun 04
INVENTORY
11060
X clair
6031
2
pts/2
11:38:46 Jun 04
:
The final example shows the output from the LIST.QUEUE command when you specify a user
number:
Screen Example
:LIST.QUEUE 6763
FILENAME
RECORD_ID
M OWNER
UNBR
UNO TTY
TIME
DATE
INVENTORY
11060
X clair
6758
5
pts/3
14:16:26 Jun 04
-------------------------------------------------------------------------FILENAME
RECORD_ID
M WAITING
UNBR
UNO TTY
TIME
DATE
INVENTORY
11060
X clair
6763
6
ttyp1
14:16:46 Jun 04
:
LIST.QUEUE Display
The LIST.QUEUE display in the previous examples use the default display. Information about the
owner of the lock is listed above the line. Information about processes waiting for the lock is listed
below the line, sorted by the date and time the process requested the lock.
265
The following table describes the LIST.QUEUE default display for the owner of the lock.
Column
Heading
Description
FILENAME
The name of the file holding the lock.
RECORD_ID
The record ID holding the lock.
Type of lock held. X is an exclusive lock, S is a shared lock.
OWNER
The user name of the owner of the lock.
UNBR
The process group ID (pid) of the user who set the lock.
UNO
The sequential number UniData assigns to the udt process for the
owner of the lock.
TTY
The Terminal device of the user owning the lock.
TIME
The time the lock was set.
DATE
The date the lock was set.

LIST.QUEUE Owner Display
The next table describes the LIST.QUEUE display for the processes 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.
The type of lock requested. X is an exclusive lock, S is a shared

lock.
WAITING
The user name of the process waiting for a lock.
UNBR
The process ID (pid) of the user waiting for a lock.

LIST.QUEUE Waiting Display
266
Listing Locks
Column
Heading
Description
UNO
The sequential number UniData assigns to the udt process waiting

for a lock.
TTY
The terminal device of the user waiting for a lock.
TIME
The time the lock was requested.
DATE
The date the lock was requested.

LIST.QUEUE Waiting Display
The following example illustrates the LIST.QUEUE display when you specify the DETAIL
option:
Screen Example
:LIST.QUEUE DETAIL
FILENAME RECORD_ID M INBRH INBR DNBR OWNER
UNBR UNO TTY
TIME
DATE
INVENTORY 10060 X 1638400 9878 3832984929 claireg 325 1 Console 09:55:52 Jun 19
-------------------------------------------------------------------------------FILENAME RECORD_ID M INBRH INBR DNBR WAITING UNBR UNO TTY
TIME
DATE
INVENTORY 10060 X 1638400 9878 3832984929 claireg 296 2 Console 09:56:02 Jun 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.
The type of lock held. X is an exclusive lock, S is a shared lock.

LIST.QUEUE Detail Display
267
Column
Heading
Description
INBRH
The high integer of the inode of the file holding the lock.
INBR
The low integer of the inode of the file holding the lock.
DNBR
Used in conjunction with the INBR to define the file holding the
lock at the operating system level.
OWNER
The user name of the process holding the lock.
UNBR
The process ID (pid) of the user holding a lock.
UNO
The sequential number UniData assigns to the udt process holding

a lock.
TTY
The terminal device of the user holding a lock.
TIME
The time the lock was set.
DATE
The date the lock was set.

The following table describes the waiting information the LIST.QUEUE command displays then
you specify the DETAIL option.
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.
The type of lock held. X is an exclusive lock, S is a shared lock.
INBRH
The high integer of the inode of the file holding the lock.
INBR
The i-node of the file for which a lock is requested.

268
Listing Locks
Column
Heading
Description
DNBR
Used in conjunction with the INBR to define the file for which a
lock is requested at the operating system level.
WAITING
The user name of the process requesting a lock.
UNBR
The process ID (pid) of the user requesting a lock.
UNO
The sequential number UniData assigns to the udt process

requesting a lock.
TTY
The terminal device of the user requesting a lock.
TIME
The time the lock was requested.
DATE
The date the lock was requested.

269
Commands for 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 in. The typical manifestations of unneeded locks are:
Users cannot perform expected operations on a file or record. Over a lengthy period of
time, users receive messages indicating that the file or record is locked.
Performance suffers, either because the item that is locked is heavily used or because a
message queue has become clogged due to the lock.
Batch jobs attempting to access a locked item fail.
Specific symptoms depend on the type of lock and the frequency of usage of the locked item.
UniData includes two commands that enable an administrator with root access to release locks
held by other users.
SUPERCLEAR.LOCKS Command
SUPERCLEAR.LOCKS enables you to release semaphore locks on system resources (such as
tape drives).
Syntax:
SUPERCLEAR.LOCKS usrnbr [locknum]
Parameter
usrnbr
Description
The process ID (pid) that holds the lock. This number is
UNBR in the LIST.LOCKS display.
SUPERCLEAR.LOCKS Parameters
270
Commands for Clearing Locks
Parameter
[locknum]
Description
The number of the locked system resource. If you do not
specify locknum, the command clears all locks set by
usrnbr.
SUPERCLEAR.LOCKS Parameters
The following example shows the effects of SUPERCLEAR.LOCKS:
Screen Example
:LIST.LOCKS
UNO
UNBR UID UNAME
TTY FILENAME
1 15454 1172ump01 tyv1 semaphor
:
:SUPERCLEAR.LOCKS 15692 -1
:LIST.LOCKS
UNO
UNBR UID UNAME
TTY FILENAME
:
INBR
-1
-1
DNBF
0
0
RECORD_ID M
TIME
DATE
65 X 16:21:01 Jun 03
66 X 16:27:01 Jun 03
INBR
-1
DNBF
0
RECORD_ID M
TIME
DATE
65 X 16:21:01 Jun 03
SUPERRELEASE Command
The SUPERRELEASE command enables you to release locks you have set on records.
Syntax:
SUPERRELEASE usrnbr [inbr devnum] [record.id]
271

Parameter
Description
usrnbr
The process ID that holds the lock. This number is

UNBR in the LIST.READU display.
[inbr devnum]
The inode number and device number for the file

that has the lock set. These numbers are INBRH,
INBR and DNBR in the LIST.READU display.
[record.id]
The identifier for the record to clear. This number is

RECORD ID in the LIST.READU display.
SUPERRELEASE Parameters
Note
If you execute SUPERRELEASE and specify only usrnbr, you release all record locks held by the
process ID corresponding to usrnbr.
The following example shows the effect of SUPERRELEASE:
Screen Example
:LIST.READU
UNO UNBR
UID
UNAME
TTY
1
2
:SUPERRELEASE 376
:LIST.READULIST.READU
UNO UNBR
UID
UNAME
TTY
2
272
FILENAME
INVENTORY
INVENTORY
RECORD_ID M
TIME
DATE
10060 X 09:56:06 Jun 10
1006 X 09:56:56 Jun 10
FILENAME
INVENTORY
RECORD_ID M
TIME
DATE
1006 X 09:56:56 Jun 10
Procedure for Clearing Locks
Procedure for Clearing Locks

Complete the following steps to identify and clear unneeded locks.
1. Check for Unneeded Locks

Use the UniData LIST.READU and LIST.LOCKS commands to display the locks currently set on
the system. Use LIST.QUEUE to identify locks for which processes are waiting. Note locks that
meet the following criteria:
They are set on files or records that users cannot currently access.
They have been set for a long period of time (shown by the time and date on the list).
They were set by users who are not currently on the system.
2. Note Information for Clearing

For record locks, note UNBR, INBRH, INBR, DNBR, RECORD NO. For semaphore locks, note
UNBR and lock number. To clear record locks, proceed to step 3. To clear semaphore locks,
proceed to step 4.
3. Release Record Locks

Log in as an Administrator and use the UniData SUPERRELEASE command to clear record
locks. If possible, specify only a UNBR to clear all the locks belonging to a process ID. If you
have semaphore locks to clear, proceed to step 4. Otherwise, proceed to step 5.
Warning
Some situations that retain locks can also cause file corruption (for example, a udt process is
inadvertently killed). Consider checking the file with guide to make certain it has not been
corrupted.
273
4. Clear Semaphore Locks

Log in as an Administrator and clear semaphore locks with the SUPERCLEAR.LOCKS
command.
274
UniData Users
This chapter outlines considerations for adding UniData users to your Windows NT or Windows
2000 system, and describes how to use UniData commands to view user processes for
troubleshooting, to remove user processes when needed, and to start and stop UniData.
275
Chapter 13 - Managing UniData Users
Adding Users
To access UniData on your system, each user needs a valid Windows NT or Windows 2000
account, including an MS-DOS login and password. In Pick systems, where each login account
must be a Pick account, shared logins and passwords are common. In contrast, UniData allows
multiple relationships between user logins and UniData accounts. A user may have access to more
than one UniData account, and many users can access a single UniData account using separate
logins. Therefore, Informix strongly recommends you set up a separate Windows NT or Windows
2000 account for each user. Informix recommends separate logins for the following reasons:
It is easier to identify processes and locks belonging to an individual user, which facilitates
troubleshooting.
Using separate logins allows you to define your users responsibilities for protecting their
passwords and your data.
User Groups
When you add a user account to your Windows NT or Windows 2000 system, you can assign the
user to one or more user groups. In contrast to UNIX, Windows NT or Windows 2000 allows a
user to belong to many groups simultaneously, and allows access to objects based on all groups to
which the user is assigned.
When you install UniData on your Windows NT or Windows 2000 system, the installation
procedure sets permissions on the UniData directory structure. UniData grants permissions are
granted to three categories of users, Administrators, members of the UniData group, and all other
users. After you install UniData, you must assign your UniData users to the UniData group.
Note
Use User Manager (or Domain User Manager, if you are a domain administrator) to create user
accounts, add users to groups, and assign User Rights. From the Start menu, point to
Programs, then point to Administrative Tools (common), and then click User Manager. Refer
to your Windows NT or Windows 2000 documentation for further information.
276
Adding Users
Home Directories
On Windows NT or Windows 2000, you can define a home directory for each login. This directory
is the users working directory when they log in. You are not required to define a home directory.
If you wish, you can define the same home directory for a group of users, or create a separate one
for each user. The home directory does not need to be a UniData account.
To define a home directory for a user, from the Start menu, point to Programs, then point to
Administrative Tools (Common), and then click User Manager. The following window appears:
277
Click User, then click Properties, and then click Profile. The following dialog box appears:
Enter the path to the users home directory in the Local Path box, then click OK.
Login Scripts
You can create a login script that is executed whenever a user logs in to a Windows NT or
Windows 2000 console or Telnet session. You must create the script in the directory identified by
your Windows NT or Windows 2000 login script path. If you specify the script in the User
Environment Profile window, UniData executes the script whenever the user logs in.
278
Adding Users
To specify a login script, from the Start menu, point to Programs, then point to Administrative
Tools (Common), and then click User Manager. The following window appears:
279
Click User, then click Properties, and then click Profile. The following dialog box appears:
Enter the path to the users login script, enter the path where the login script resides in the User
Profile Path box, the script name in the Logon Script Name box, and then click OK.
280
Monitoring User Processes
Monitoring User Processes

For troubleshooting purposes, it is often necessary to identify and monitor processes owned by a
particular UniData user.
UniData Commands
UniData includes a group of commands to display a list of current UniData sessions, to display a
list of users currently logged in to the system, and to display detailed information about process
activity for a specific user, or for all users. These UniData commands are summarized in the
following table.
UniData
Command
Description
WHO
ECL command; displays a list of users currently logged in to

the system, including users who are not UniData users.
LISTUSER
ECL command; displays a list of current UniData sessions.
listuser
UniData system-level command; enter at a MS-DOS prompt;

displays the same information as the ECL LISTUSER
command.
MYSELF
ECL command; displays login ID for the current UniData

session.
UniData Commands for Monitoring User Processes
Note
You do not need to log in as an Administrator to execute these commands.
281
The following example shows the system response to the WHO, LISTUSER, and listuser
commands.
Screen Example
:WHO
claireg
claireg
claireg
Console
Console
Console
09:55:40 Jun 19 1999

09:55:49 Jun 19 1999
09:56:18 Jun 19 1999
:LISTUSER
16 / 16
UDTNO USRNBR UID
USRNAME
1
325 1049668 claireg
Udt
USRTYPE
udt
Sql
Total
3
TTY
pts/1
0
3
IP-ADDRESS
Console
TIME
DATE
09:55:40 Jun 19 1999
296 1049668 claireg
udt
pts/2
Console
09:55:49 Jun 19 1999
111 1049668 claireg
udt
pts/3
Console
09:56:18 Jun 19 1999
C:\UniData52\claireg>listuser
Udt
Sql
Total
16 / 16
UDTNO USRNBR UID
USRNAME USRTYPE
1
325 1049668 claireg
udt
3
TTY
pts/1
0
3
IP-ADDRESS
Console
TIME
DATE
09:55:40 Jun 19 1999
296 1049668 claireg
udt
pts/2
Console
09:55:49 Jun 19 1999
111 1049668 claireg
udt
pts/3
Console
09:56:18 Jun 19 1999
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 users uid number), and USRNAME. Displaying further
information about a UniData process typically requires the pid (USRNBR).
282
Stopping User Processes
Stopping User Processes

UniData includes commands that enable you to stop a users udt process if the process is hung, or
if you need to stop UniData while a user is still logged in. 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.
deleteuser
First attempts to gracefully exit and allow a write in progress

to complete. If the command is not successful in five seconds,
force logs out a user, which may interrupt a write in progress,
potentially causing file corruption.
UniData Commands for Removing User Processes
Permissions
You can log yourself out using the stopudt command, but you must be log in as an
Administrator to log out other users using stopudt. You must log in as an Administrator to execute
deleteuser.
Warning
Both of these commands can disrupt the consistency of your database, and deleteuser can also
corrupt data. Do not use these commands should as a substitute for normal user logout.
283
Using TIMEOUT
You can execute the ECL TIMEOUT command at the ECL prompt, in a LOGIN paragraph, or in a
UniBasic program. TIMEOUT forces the current udt process to log out after a specified number of
seconds. If you include TIMEOUT in the LOGIN paragraphs for your UniData accounts, you can
provide some improved security for terminals left idle.
Warning
Be careful with TIMEOUT. Because this command can cause a UniBasic program to terminate at
an INPUT statement rather than concluding normally, using TIMEOUT can cause inconsistent
data in your database.
284
Printers in UniData
This chapter explains how UniData interacts with the Windows NT or Windows 2000 spooler and
describes how to configure and access printers from within UniData.
285
Chapter 14 - Managing Printers in UniData
Configuring and Troubleshooting a Printer

In Windows NT or Windows 2000, the term printer refers to a printer driver. The term print
device refers to a piece of hardware that can be accessed using one or more printers. In order
for any user to print to a print device from UniData, all the following conditions must be true. Use
these conditions as guidelines for setting up a print device and for troubleshooting print device
problems.
Physical Configuration
Configure a print device as follows:
The print device must be physically connected to your computer or network.
If you are accessing the print device from a local printer you create, the driver for the print
device must be installed on the workstation or server from which you are printing.
Note
Depending on your network configuration, you may need to complete additional steps before you
can print successfully from your Windows NT or Windows 2000 machine. 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
286
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 NT or Windows 2000

You may either print directly to a network print device or a print to a local printer from within
UniData.
Network Print Device

A network print device is a print device that is connected to a remote print server. When you print
to a network printer, the printer driver and the configuration are downloaded to your computer. To
connect to a network printer, from the Start menu point to Settings, click Printers, and then
double-click Add Printers. The Add Printer wizard displays, as shown in the following example:
287
Click Network printer server, and then click Next to display the Connect to Printer dialog box,
as shown in the following example:
The Connect to Printer dialog box displays information about printers on your network. Select a
printer from the list displayed. If you have Print permissions to the printer object, you will be able
to connect to it. Once you have connected, an icon for the printer appears whenever you open the
Printers applet.
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.
288
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
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 in this chapter.
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 in. 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 NT or Windows 2000 system.
Note
If you are a local user (your account information is on a local Windows NT or Windows 2000
machine rather than a domain) and you log in 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.
289
Spooling From UniData

The Spooling Process
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 NT or Windows 2000 Win32 API calls, using
information from the printer setup (SETPTR for the printer to receive the output).
After the output is printed, UniData deletes the temporary file.
UniData for Windows NT or Windows 2000

Specifics
UniData for Windows NT or Windows 2000 enables you to print to any printer you can access
from outside of UniData. The DEST or AT option of SETPTR enables you to print to a particular
device. SETPTR options control some output characteristics, and you can specify other characteristics by including spooler options in a quoted string on the SETPTR command line.
By using RAW spooler mode (the default in UniData), you can control formatting by using printerspecific escape sequences rather than spooler options.
290
Creating a Local Printer

In Windows NT or Windows 2000, 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 circumstance,s 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.
5. Invoke the Printers Applet

From the Start menu, point to Settings, click Printers, and the double-click Add Printers. If you
prefer, you can access the Add Printers dialog box from My Computer by double-clicking
Printers, and then double-clicking Add Printers. A window similar to the following appears:
291
6. Identify Local Printer

Click My Computer to indicate the printer is a local printer.
Note
Your Windows NT or Windows 2000 machine becomes the server for the printer you are
creating. After you add the printer, click File, then Server Properties to view and edit settings for
this printer.
Click Next to display the following dialog box:
7. Select or Add Port

If your local printer identifies a device local to your workstation or server, scroll through the list of
ports and select the check box next to the one where the printer is connected. Click Next and
proceed to step 5.
292
If your local printer identifies a network print device, scroll through the list of Available Ports to
determine if the UNC identifier for the network print device is listed with Local Port as its
description. If so, proceed to step 5.
If the network print device is not on the list, or its description is not Local Port, click Add Port.
The following dialog box appears:
Highlight Local Port, and then double-click New Port. A dialog box similar to the one in the
following example appears. Enter the UNC identifier for the network print device in the Enter a
Port Name box, as shown:
Click OK. The Printer Ports Window appears.
293
Click Close on the Printer Ports dialog box. The Add Printer Wizard dialog box appears again,
and your printer device is now included on the list, as shown in the following example:
Click the appropriate check box, and then click Next.
Reminder
Make sure the description reads Local Port.
294
8. Identify the Print Device

After you select the port and click Next, a dialog box similar to the following appears:
Follow the instructions on the screen. Click Next when you have selected the manufacturer and
printer. A window similar the following appears:
Complete the prompts, and then click Next.
295
9. Supply Printer Name

After you identify the printer type and driver and click Next, a dialog box similar to the following
example appears:
Supply a name for the local printer.

The name you enter on this screen is the name you will use with the DEST and AT options of the
UniData SETPTR command. Make the name meaningful. In the examples, local printers are
named to match their default forms.
Warning
Do not use spaces in the printer name. Although Windows NT or Windows 2000 allows 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.
Click Next.
296
10. Set Sharing Options

After you name the printer and click Next, a dialog box similar to the following appears:
Follow the instructions on the screen, and click Next when you are done.
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 NT or Windows
2000 machine 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 in Step 8.
297
11. Complete the Installation

When you click Next after defining Sharing properties, a dialog box similar to the following
appears:
Tip
Informix recommends you print a test page to verify the printer setup.
Click Finish to add the printer to your machine. An icon for the printer appears in the Printers
window.
12. Edit Printer Properties (Optional)

Note
You must have Full Control permissions to the printer to change its properties.
298
Display the Properties sheet for the printer you just created. The following table summarizes the
dialog tab.
Dialog Tab
General
Purpose
Adds comments or location information, or changes printer
driver.
Note - 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.

Printer Properties Sheet
Note
Use caution modifying device settings. You can enter settings for a local printer that are
inconsistent with the underlying print device.
13. Assign Default Form

Note
You must have Full Control permissions on a printer to assign a default form. Click Security, and
then click Permissions on the Property sheet to determine what permissions you have.
299
To assign a default form to a printer, select the printer in the Printers applet, and select Document
Defaults. Select the Page Setup tab. A dialog box similar to the following example appears:
Select the desired form from the Paper Size list. If the form you want is not included in the list,
see to Creating a Form in this chapter. You can also choose copies, orientation, and duplex
options from this dialog tab.
Note
Options you select on either this tab or the Advanced tab only work if the network print device
supports them.
Click OK when your selections are correct.
Note
Although you can select Copy Count from this tab, the value you select here is overridden in
UniData by the COPIES option of the SETPTR command.
300
Creating a Form
Creating a Form
Windows NT or Windows 2000 stores information about forms that are available on your current
Windows NT or Windows 2000 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, point to Settings, click Printers, click File,
and then click Server Properties. A properties sheet similar to the following example appears:
Select the Forms tab on the properties sheet, and complete the following steps to create a new
form.
1. Select an Existing Form

You create new forms by editing the characteristics of existing forms. Highlight a form, and then
select the Create a New Form check box.
301
Tip
To minimize editing, pick an existing form whose characteristics are similar to the new form you
are creating.
2. Edit Form Characteristics

When you select the Create a New Form check box, the name, paper size and margins are
enabled for editing. Follow the instructions on the properties page to edit and save the new form.
The following example shows selections for a form called test_form, based on the existing form
called Letter.
Note
Although you can create forms of varying sizes, you cannot select a particular form for use on a
particular printer unless the print device can support that size of stock. Reder to your Microsoft
documentation and the documentation for your print device for information about constraints.
302
Creating a Form
The new form now displays in the form list, as shown in the following example:
Click OK to exit the Forms tab.
303
Defining a Printer Unit in UniData

Use the ECL SETPTR command to define printer units within UniData. This command maps
Windows NT or Windows 2000 printers to logical unit numbers within a UniData session.
Syntax:
SETPTR unit [width,length,topmargin,bottommargin] [,mode] [,options] [,spooler_options]
With SETPTR, you can define up to 31 logical printer units in a single UniData session.
Throughout UniData, you can define up to 255, but only 31 can be defined in a single user session.
The following table lists each parameter of the syntax.
Parameter
Description
unit
Logical printer unit number that is internal to UniData. You can map
this to a Windows NT or Windows 2000 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
SETPTR Parameters
304
Parameter
Description
[spooler_options]
Options that are valid with the Windows NT or Windows 2000 spooler.
See separate table for list of supported options. Supply these options in
a quoted string.
SETPTR Parameters (continued)
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
Directs output to a line printer only.
Must be used with DEVICE option; directs output to the

serial device specified by the DEVICE option.
Directs output to a _HOLD_ file only.
Directs output to both a _HOLD_ file and a printer.
Directs output to a line printer; suppresses display of the

_HOLD_ entry name.
SETPTR Modes
305
The next table describes options for the SETPTR command.

Option
Description
BANNER [string]
Modifies the default banner line (which is the Windows NT or

Windows 2000 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 NT or

Windows 2000 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.
SETPTR Options
306
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 printers Properties Sheet.
Duplex
Must be NONE, HORIZONTAL, or VERTICAL; default is NONE.

Note - 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 printers Properties Sheet.
Mode
RAW or WINDOW. Default is RAW, meaning that printer-specific escape

sequences are required for all formatting.
Note - Specifying formatting options (Form, Font, FontSize, Orientation,
FontStyle, DefaultSource, or Duplex) in a quoted string automatically
switches Mode to WINDOW.
Prefix
Printer-specific escape sequence, specified as a decimal (not ASCII) value.

Valid in RAW mode only. For example, PREFIX = \002
Font
Font name, for instance Courier New.

Note - The UniData spooler creates a logical font using the values you
provide for Font, FontSize, and FontStyle. Windows NT or Windows 2000
attempts 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).

computer.
SETPTR Spooler Options
307
Option
FontStyle
Description
Must be Regular, Italic, Bold, Underline, or StrikeOut. Default is Regular.
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.

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

Note - 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.
SETPTR Spooler Options (continued)
308
Examples
You can define local or network printers to UniData using the SETPTR command, as shown in the
following examples:
Screen Example
:SETPTR 0,,,,,1,AT LETTER,TopMargin=1,BottomMargin=1,Font=Courier,FontSize=12
Unit
0
Mode
1
Options are:
Destination LETTER
Lp options : TopMargin=1,BottomMargin=1,Font=Courier,FontSize=12
OK to set parameters as displayed?(enter y/n) y
:SETPTR 0
Unit
Width
Length
Top margin
Bot margin
Mode
0
105
31
3
3
1
Options are:
Destination LETTER
Lp options : TopMargin=1,BottomMargin=1,Font=Courier,FontSize=12
:SETPTR 1,,,0,0,1,AT \\DENVER4\hpzone3,"Priority=99"
Unit
1
Top margin 0
Bot margin 0
Mode
1
Options are:
Destination \\DENVER4\hpzone3
Lp options : Priority=99
:SETPTR 2,,,,,1,AT LEGAL
Unit
2
Mode
1
309
Options are:
Destination LEGAL
OK to set parameters as displayed?(enter y/n) Y
:SETPTR 3,,,,,1,AT \\DENVER4\hpzone2,"Form=A4"
Unit
3
Mode
1
Options are:
Destination \\DENVER4\hpzone2
Lp options : Form=A4
:
The default print device (printer unit 0) is now mapped to the local printer LETTER. If
you use the PRINT command or LPTR with no print unit specified, UniData directs your
print job to LETTER.
Use SETPTR unit to display the current settings for a print unit.
When you specify spooler options (TopMargin, BottomMargin), UniData automatically

recalculates the width and length taking these into account. When you specify formatting
options in a quoted string, UniData implicitly changes the spooler Mode from RAW (the
default) to WINDOW.
You can specify spooler options in a quoted string either before or after SETPTR options
like AT, DEFER.
You can map a printer unit to a network print device even if that device is not displayed in
your Printers dialog.
After you have defined printers with SETPTR, you can display a list with the LISTPTR command,
as shown below:
Screen Example
:LISTPTR
Unit.. Printer................... Port.......................Status..
310
0
1
2
3
LETTER
\\DENVER4\hpzone3
LEGAL
\\DENVER4\hpzone2
\\DENVER4\hpzone3
hpzone3
\\DENVER4\hpzone3
hpzone2
Running
Running
Running
Running
Notice that, in the previous example, the two local printers point to the same network print device.
Use PTRDISABLE and PTRENABLE (STOPPTR and STARTPTR) to control printers:
Screen Example
:PTRDISABLE LETTER
:LISTPTR
Unit.. Printer...................
0
LETTER
1
\\DENVER4\hpzone3
2
LEGAL
3
\\DENVER4\hpzone2
:PTRENABLE LETTER
:LISTPTR
Unit.. Printer...................
0
LETTER
1
\\DENVER4\hpzone3
2
LEGAL
3
\\DENVER4\hpzone2
:
Port.......................Status..
\\DENVER4\hpzone3
Paused
hpzone3
Running
\\DENVER4\hpzone3
Running
hpzone2
Running
Port.......................Status..
\\DENVER4\hpzone3
Running
hpzone3
Running
\\DENVER4\hpzone3
Running
hpzone2
Running
Only users with Full Control permissions on a printer can control the printer with PTRDISABLE
and PTRENABLE. Check Permissions on the Security tab of the Properties sheet for the printer
to determine who has permissions.
Notice that the argument for PTRDISABLE and PTRENABLE is the name of the printer (as
specified with DEST or AT in SETPTR).
You can use the ECL SP.STATUS command to display information about printers defined with
SETPTR and print jobs started from your UniData session.
The following example shows SP.STATUS output:
311
Screen Example
:SP.STATUS
Device for LETTER: \\DENVER4\hpzone3
LETTER is Running.
Device for \\DENVER4\hpzone3: hpzone3
\\DENVER4\hpzone3 is Running.
Device for LEGAL: \\DENVER4\hpzone3
LEGAL is Running.
Device for \\DENVER4\hpzone2: hpzone2
\\DENVER4\hpzone2 is Running.
JobId.... User............ Size.... Status... Unit.. Printer..................
241
terric
543
Defered
3
\\DENVER4\hpzone2
\
:
The status of all the printers is Running, and the network print device has a deferred job.
Depending on how a print device was configured, users in console sessions may see printer
notification messages when a job completes. The following example shows such a message:
Note
The Printing Notification only displays if you log in to a console session. If you log in to UniData
via Telnet, you will not see the notification.
312
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:
Screen Example
:SETPTR 0,,,,,3
Unit
0
Mode
3
Options are:
Hold Entry _HOLD_/P_0000
:LIST VOC SAMPLE 10 LPTR
:LIST _HOLD_
_HOLD_....
P_0000
P_0000.SET
PTR
2 records listed
_HOLD_ entry P_0000 is the output from the LIST command, and P_0000.SETPTR contains the
printer settings. You can display the contents of P_0000.SETPTR, as they can display any
_HOLD_ entry, with SP.EDIT, as shown in the following example:
Screen Example
:SP.EDIT P_0000.SETPTR
Hold item P_0000.SETPTR - (t) terminal (f) find (s) spool (d) delete or (q) quit
?
T
Spooler Options:
313
Orientation.....
0
PaperSize.......
0
PrintQuality....
0
Color...........
0
Duplex..........
0
PaperSource...
0
TopMargin.......
0.000000
BottomMargin....
0.000000
LeftMargin......
0.000000
RightMargin.....
0.000000
Font............
NULL
FontStyle.......
Hold item P_0000.SETPTR - (t) terminal (f) find (s) spool (d) delete or (q) quit
?
Selecting a Spooler Mode

The UniData spooler interface enables you to print to an Windows NT or Windows 2000 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.
Examples
In the following example, the spooler mode is changed from RAW (the default) to WINDOW.
Notice that UniData changes the width and length automatically:
314
Screen Example
:SETPTR
Unit
Width
Length
Top margin
Bot margin
Mode
0
132
60
3
3
1
Options are:
:SETPTR 0,,,,,1,"Mode=WINDOW"
Unit
0
Mode
1
Options are:
Lp options : Mode=WINDOW
:SETPTR
Unit
0
Width
80
Length
56
Top margin 3
Bot margin 3
Mode
1
Options are:
Lp options : Mode=WINDOW
:
In the next example, setting Font to COURIER implicitly changes the spooler mode to WINDOW,
even though the display does not indicate this. Notice that width and length were adjusted:
Screen Example
:SETPTR
Unit
Width
Length
Top margin
0
132
60
3
315
Bot margin 3
Mode
1
Options are:
:SETPTR 0,,,,,1,Font=COURIER
Unit
0
Mode
1
Options are:
Lp options : Font=COURIER
:SETPTR
Unit
0
Width
80
Length
56
Top margin 3
Bot margin 3
Mode
1
Options are:
Lp options : Font=COURIER
:
If you combine incompatible options on the SETPTR command line, the command fails with an
error message as shown in the following example:
Screen Example
:SETPTR 0,,,,,,"Mode=RAW,Font=COURIER"
Unit
0
Options are:
Lp options : Mode=RAW,Font=COURIER
Invalid combination of spooler options 'Mode=RAW,Font=COURIER'
:
316
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.
317
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.
Command
Description
SETPTR
Defines logical printer units within a UniData session.
SPOOL
Prints the contents of a record to the printer.
PTRDISABLE
or STOPPTR
Pauses a Windows NT or Windows 2000 printer. You must supply the printer
name (the name you used with the DEST or AT option) rather than the
UniData logical print unit number.
PTRENABLE
or STARTPTR
Resumes a Windows NT or Windows 2000 local printer. You must supply

the printer name (the name you used with the DEST or AT option) rather
than the UniData logical print unit number.
SP.CLOSE
Closes a print file.
SP.ASSIGN
Sets characteristics of the default UniData print device, printer unit 0 (Pick
compatible syntax).
SP.EDIT
Views or prints files in the _HOLD_ directory
SP.KILL
Cancels a job.
SP.OPEN
Opens a continuous print job. This command is equivalent to the UniData

SETPTR,,,,,,OPEN command.
SP.STATUS
Provides printer and queue information.
LISTPTR
Displays the names of printers and the paths of devices associated with them.
LISTPEQS
Lists entries in the _HOLD_ file of the current account.

ECL Printing Commands
318
UniData Printing Commands
Note
See the UniData Commands Reference for the syntax of these ECL commands.
319
320
Cataloged Programs
This chapter describes the behavior of global, direct, and local cataloging for UniBasic programs.
The chapter also describes how to create an alternate global catalog space using the newhome
command.
321
Chapter 15 - Managing Cataloged Programs
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.
Reminder
In a UniData DIR-type file, such as BP, each record is a file.
Each UniData account may contain numerous DIR files for UniBasic source.
UniBasic Compiled 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.
Reminder
See the UniData Commands Reference and Developing UniBasic Applications for information
about the BASIC command.
322
UniBasic Source and Compiled Programs
The following example shows the contents of a program file:
Screen Example
: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.
Reminder
Use the ECL RUN command to execute a compiled program. See the UniData Commands
Reference and Developing UniBasic Applications for information about the RUN command.
323
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.
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
Points to remember about direct cataloging are:
Compiled code is located in the program file in the UniData account where the program
was compiled and cataloged.
The VOC file in the account contains a pointer to the compiled code in the program file.
Users in the same account can execute the program by entering the program name at the
ECL prompt.
Because users access the compiled code in the program file, developers do not need to
recatalog the code if they recompile.
When you execute a directly cataloged program, UniData loads a copy of the program into
your address space.
Local Cataloging
Points to remember about local cataloging are:
324
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.
Cataloging UniBasic Programs
The VOC file in the account contains a pointer to the compiled program in the CTLG.
Users in the same account can execute the program by entering the program name at the
ECL prompt.
Developers must recatalog a program after recompiling to place a new copy of the
compiled code into the CTLG.
When you execute a locally cataloged program, UniData loads a copy of the program into
your address space.
Global Cataloging
Points to remember about global cataloging are:
If you execute the CATALOG command without specifying local or direct cataloging,
your program is globally cataloged.
Compiled code is located in a system-wide global catalog. The default global catalog is
udthome\sys\CTLG.
Developers must recatalog a program after recompiling it to place a new copy of the
compiled code into the global catalog.
Note
A UniData installation can have more than one global catalog space. The environment variable
UDTHOME determines which global catalog space a particular UniData session accesses. See
Creating an Alternate Global Catalog Space in this chapter 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 nonalphabetic characters are stored in
a subdirectory named X. The cataloged program name can be the same as the source and
object, or you can specify a different name when you execute CATALOG.
325
Tip
Consider your program naming conventions if you are using global cataloging. Since UniData
places the compiled code in subdirectories according to name, you may have an unbalanced
situation if a large number of your program names begin with the same letter (for instance, a
general ledger application where all the files begin with gl).
A globally cataloged program is available to users in all UniData accounts.
When you execute a globally cataloged program, the shared basic code server (sbcs)
checks to see if a copy already exists in the shared memory it controls.
If so, sbcs notifies the udt process which shared memory segment to attach to access
that copy.
If not, sbcs loads a copy into one of its shared memory segments for you to execute.
Any object file located in the udthome\sys\CTLG file system is handled by sbcs,
regardless of how the program is accessed.
The sbcs process can manage up to 20 shared memory segments for globally cataloged
programs. UniData determines the size of each segment by the SBCS_SHM_SIZE
parameter in the UniData configuration file (\udthome\include\udtconfig). The default
value for SBCS_SHM_SIZE is 1,048,576 bytes (1 MB), which is set when you install
UniData. You will encounter run-time errors if this size is insufficient. You can increase
the segment size as long as you do not exceed the configuration parameter
SHM_MAX_SIZE.
Tip
Refer to Appendix A - UniData Configuration Parameters, for more information about
SBCS_SHM_SIZE and SHM_MAX_SIZE.
326
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:
Screen Example
:LIST CTLGTB ALL
LIST CTLGTB ALL 15:33:59 Jun 14 2000 1
CATALOG NAME................ T ARG ORIGINATOR............ WHO....
SCHEMA_UPDATE_PRIVILEGES
SCHEMA_LIST_USERS
SCHEMA_VIEW_CHECK
US_EXECUTOR
BUILD.CHARTBL
508E
RPROG2_AE
S
S
JRNL_TEST
51 @UDTHOME/SYS_BP SCHEMA
_UPDATE_PRIVILEGES
_LIST_USERS
_VIEW_CHECK
51 @UDTHOME/SYS_BP US_EXE
CUTOR
01 @UDTHOME/DENAT_BP BUIL
D.CHARTBL
41 @UDTHOME/SYS_BP 508E
11 @UDTHOME/AE_BP RPROG2_
AE
0 @UDTHOME/SYS_BP JRNL_T
EST
root
root
root
root
root
root
root
root
327
SCHEMA_DELETE_MAP
NFA.EXECSEL.U
70E0
.
.
.
41 @UDTHOME/SYS_BP SCHEMA root

_DELETE_MAP
31 @UDTHOME/SYS_BP NFA.EX root
ECSEL.U
41 @UDTHOME/SYS_BP 70E0
root
The _MAP_ file also contains information about the contents of a global catalog. In addition to the
information in CTLGTB, _MAP_ includes the size of each compiled program, the date it was
cataloged, and the last date it was executed. The _MAP_ file is not dynamically maintained by
UniData. The ECL MAP command updates the _MAP_ file to reflect recent activity. The MAP
command clears the _MAP_ file, updates the file, and displays its contents, as shown in the
following example:
Screen Example
:MAP
MAP 15:49:59 Jun 10 1999 1
NAME............ TYPE ARG ORIGINATOR.......... WHO.... OBJ... DATE.... LAST REF
508E
COUNT.MSG
S
S
SORT_AE
7201
NFA.EXECSEL.U
S
S
S_VALID_FILE_CHE S
CK
ERRMSG.COMMON
M
RPROG_AE
11A2
S
SCHEMA_OBJECT_TY S
PE
S_VALID_NAME_CHE S
CK
328
41 @UDTHOME/SYS_BP 508E
31 @UDTHOME/DENAT_BP CO
UNT.MSG
11 @UDTHOME/AE_BP SORT_
AE
41 @UDTHOME/SYS_BP 7201
31 @UDTHOME/SYS_BP NFA.
EXECSEL.U
61 @UDTHOME/SYS_BP S_VA
LID_FILE_CHECK
0 @UDTHOME/DENAT_BP ER
RMSG.COMMON
11 @UDTHOME/AE_BP RPROG
_AE
81 @UDTHOME/SYS_BP 11A2
41 @UDTHOME/SYS_BP SCHE
MA_OBJECT_TYPE
31 @UDTHOME/SYS_BP S_VA
LID_NAME_CHECK
root
root
184 06/03/99 06/08/99

582 06/03/99 06/08/99
root
1650 06/03/99 06/08/99
root
root
180 06/03/99 06/08/99

154 06/03/99 06/08/99
root
1712 06/03/99 06/08/99
root
92 06/03/99 06/08/99
root
4710 06/03/99 06/08/99
root
root
850 06/03/99 06/08/99

1914 06/03/99 06/08/99
root
2184 06/03/99 06/08/99
SCHEMA_REMOVE_SC S
.
.
.
31 @UDTHOME/SYS_BP SCHE root
1364 06/03/99 06/08/99
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. The following example shows output from
VCATALOG:
Syntax:
VCATALOG filename catalog.name program.name
Parameter
filename
Description
Name of the file containing the program (BP, for
instance).
VCATALOG Parameters
329
Parameter
Description
catalog.name
Name given to the program when you executed

CATALOG. For example, the command CATALOG BP
TRIAL TEST creates a global catalog entry named
TRIAL from a program called TEST. So catalog.name
is TRIAL.
program.name
Name of the program source file. In the example in the

previous row of this table, program.name is TEST.
VCATALOG Parameters
Note
If catalog.name and program.name are the same, you need only supply the name once.
Screen Example
:VCATALOG BP TEST
Program 'TEST' does not verify.
:CATALOG BP TEST
C:\UniData52\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'.
:CATALOG BP TEST
\UniData52\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.
330
Reminder
See the UniData Commands Reference for more information about the VCATALOG command.
Activating Newly Cataloged Programs and

Subroutines
Main Programs
When you globally catalog a UniBasic main program, UniData:
Copies the new compiled code into the global catalog.
If there is a version of the program in shared memory, marks that version as obsolete.
The users already executing the main program continue to execute the previous version. Users that
execute the program after the new version is cataloged get the new version. Once all users exit the
previous version, UniData removes the copy of that version from shared memory.
Note
A user executing a main program continues to execute that version until it completes.
Subroutines
If a subroutine is recataloged while the main program is running, users will not execute the newlycataloged subroutine until the next time they execute the main program. This prevents inconsistent
execution of a subroutine during one execution of the main program. Under certain circumstances,
however, a user or system administrator can override the default behavior. Overrides are dangerous
in a production environment, but may be useful in a development or test environment.
331
NEWVERSION Keyword
The NEWVERSION keyword for the CATALOG command allows a user logged in as an
Administrator to dynamically replace a globally cataloged subroutine. If a subroutine is cataloged
with NEWVERSION, any user executing the main program accesses the new version of the
subroutine with the next CALL or EXECUTE of the subroutine, rather than waiting until the main
program completes. Consider the following sequence of events:
1. A user executes the main program MAIN.
2. MAIN calls a subroutine called SUBR, which completes and returns to MAIN.
3. MAIN continues with other processing.
4. MAIN calls SUBR again. SUBR completes and returns to MAIN.
5. MAIN completes.
If SUBR is recataloged after step 1 without the NEWVERSION keyword, the same version of
SUBR is used for both calls (step 2 and step 4). With the next execution of MAIN, the newly
cataloged SUBR is used.
If SUBR is recataloged after step 1, with the NEWVERSION keyword, there are three possible
results:
CATALOG happens after step 1 but before step 2. In this case, the newly cataloged SUBR
gets accessed in both step 2 and step 4.
CATALOG happens after step 2, but before step 4. In this case, the prior version of SUBR
gets accessed in step 2, and the newly cataloged version gets accessed in step 4.
CATALOG happens after step 4. In this case, the prior version gets accessed in both step 2
and step 4. With the next execution of MAIN, the newly cataloged SUBR is accessed.
Warning
Using the NEWVERSION keyword to CATALOG a subroutine can produce inconsistent results
for users who are currently executing the main program. For example, the number of arguments
could change.
The following sample CATALOG command shows the syntax including the NEWVERSION
keyword:
332
Screen Example
:CATALOG BP SUBR NEWVERSION
\UniData52\sys\CTLG\s\SUBR has been cataloged, do you want to overwrite?(Y/N) Y
:
newversion System-Level Command

The UniData system-level command newversion allows a user logged in as an Administrator to
dynamically replace a cataloged subroutine (just as the NEWVERSION keyword does) but limits
the behavior to a selected user or users.
Syntax:
newversion path userno...
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.
newversion Command Parameters
The following screen shows an example of the newversion command:
Screen Example
:LISTUSER
16 / 16
UDTNO USRNBR UID
USRNAME
1
325 1049668 claireg
Udt
USRTYPE
udt
3
TTY
pts/1
Sql
Total
0
3
IP-ADDRESS
Console
TIME
DATE
09:55:40 Jun 19 1999
333
296 1049668 claireg
udt
pts/2
Console
09:55:49 Jun 19 1999
111 1049668 claireg
udt
pts/3
Console
09:56:18 Jun 19 1999
:CATALOG BP SUBR
\UniData52\sys\CTLG\s\SUBR has been cataloged, do you want to overwrite?(Y/N) Y
:
:!newversion \UniData51\sys\CTLG\s\SUBR 325
In the example, the newly cataloged subroutine is dynamically available to claireg, the owner of
user number 325. If claireg 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 claireg, 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:
Screen Example
* PROGRAM MAINPROG
* NEWPCODE EXAMPLE
EXECUTE "MAINPROG2"
EXECUTE "BASIC BP MAINPROG2"
EXECUTE "CATALOG BP MAINPROG2 DIRECT"
EXECUTE "NEWPCODE \UniData52\sys\CTLG\m\MAINPROG2"
EXECUTE "MAINPROG2"
END
334
In the example, a user executing MAINPROG accesses the current version of MAINPROG2 in the
first statement. Including the NEWPCODE command before the next execution of MAINPROG2
causes the program to access the newest version. (In the example, MAINPROG2 was recompiled
and recataloged after the first step, so the next execution accesses the newly cataloged
MAINPROG2.)
Tip
If you are developing programs with the AE editor, the N option of the FI command equates to the
NEWPCODE command. For example, FIBCFN compiles a program and catalogs it (locally) with
NEWPCODE. You need to use F (force) in conjunction with the N option.See the online help for
the AE editor or Developing UniBasic Applications for more information.
Note
The NEWPCODE command is effective only in the udt session where it is executed. Although
NEWPCODE is an ECL command, you cannot affect a different user or even a different window
with NEWPCODE.
335
Listing Programs in Use

The UniData system-level sbcsprogs command enables any user with access to the system-level
prompt to display a list of globally cataloged programs currently in use, with counters for the
number of processes currently accessing each one. The following example shows typical output
from sbcsprogs:
Screen Example
# sbcsprogs
Program Name
Reference Count
\UniData52\sys\CTLG\a\AE
\UniData52\sys\CTLG\a\AE_ICOM1
\UniData52\sys\CTLG\a\AE_AE
\UniData52\sys\CTLG\a\AE_UPS
2
1
2
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.
336
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:
Screen Example
C:\UniData52\sys>dir
Directory of C:\UniData52\sys
10/27/98
10/27/98
10/08/98
10/08/98
10/08/98
10/27/98
10/08/98
10/08/98
10/08/98
10/02/98
10/27/98
10/27/98
10/27/98
10/08/98
10/27/98
10/08/98
09/03/98
04/28/98
04/28/98
10/27/98
04/28/98
11:13a
11:13a
03:03p
03:03p
03:03p
11:15a
03:05p
03:05p
03:06p
09:20a
11:15a
11:15a
11:15a
03:07p
11:15a
03:07p
01:43p
01:17p
01:17p
11:15a
01:17p
<DIR>
<DIR>
3,151
4,041
54,365
<DIR>
2,048
9,216
360,448
<DIR>
<DIR>
<DIR>
<DIR>
81,920
<DIR>
12,288
<DIR>
21,504
21,504
<DIR>
2,048
.
..
@readme
@README-IMPORTANT
@VERSIONS
AE_BP
Ae_coms
AE_COMS_DEMO
Ae_doc
AE_SCRATCH
AE_SECURITY
AE_SYSTOOLS
AE_UPCHARS
Ae_xcoms
BP
COLLATIONS
CTLG
Ctlgtb
CTLGTB.BAK
DENAT_BP
DICT.DICT
337
04/28/98
10/08/98
10/08/98
10/08/98
10/08/98
10/02/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/08/98
10/05/98
10/05/98
10/27/98
10/13/98
10/08/98
10/08/98
10/08/98
10/08/98
10/05/98
11/10/98
04/28/98
10/05/98
338
01:17p
03:17p
03:17p
03:17p
03:17p
09:20a
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:17p
03:18p
03:18p
03:18p
03:18p
03:18p
03:18p
03:18p
03:18p
10:54a
10:54a
11:15a
01:30p
03:23p
03:23p
03:23p
03:23p
10:54a
04:15p
01:21p
10:54a
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
2,048
5,120
4,096
2,048
2,048
339,968
339,968
352,256
4,046,848
247,808
387
1,240
<DIR>
<DIR>
<DIR>
71
527
15,360
111,616
3,588,096
<DIR>
17,408
8,192
<DIR>
DICT.DICT.BAK
D_ae_bp
D_AE_COMS
D_AE_COMS_DEMO
D_ae_doc
D_AE_SCRATCH
D_AE_XCOMS
D_bp
D_COLLATIONS
D_ctlg
D_ctlgtb
D_DENAT_BP
D_ENGLISH.MSG
D_ENGLISH_G2.MSG
D_french.msg
D_HELP.FILE
D_JAPANESE.MSG
D_MSG.DEFAULTS
D_SAVEDLISTS
D_sys_bp
D_UDT_GUIDE
D_voc
D__map_
D__ph_
English.msg
ENGLISH_G2.MSG
French.msg
HELP.FILE
Japanese.msg
Langgrp
MULTIBYTE.CONFIG
SAVEDLISTS
savedlistsl
SYS_BP
udtpath
UDTSPOOL.CONFIG
uniapi.msg
Voc
X_HELP.FILE
_HOLD_
_map_
_MAP_.BAK
_PH_
64 File(s)
9,696,550 bytes
2,832,872,960 bytes free
The following directories make up the program catalog spaces:
D_CTLGTB
CTLGTB
D_CTLG
CTLG, including subdirectories a through z and X for storing globally cataloged

programs.
newhome does not create the entire directory structure that exists in the default UniData home
directory, and it does not copy UniBasic executables developed at your site.
Procedure for Creating an Alternate Global

Catalog Space
Follow the steps below to create an alternate global catalog space:
1. Change to the New Account Directory

At the operating system prompt, change to the directory in which you intend to locate the new
UniData account, as shown in the following example:
Screen Example
C:\UniData50>cd \UniData52\claireg
2. Execute newhome
Execute the newhome command, indicating the path to the new account. In this example, a new
directory, testenv, will be created under \UniData52\claireg.
339
Notice that the newhome command is executed from the ECL prompt, and therefore is preceded
by the ! ECL command:
Screen Example
:!newhome testenv
Creating new udt home \UniData52\claireg\testenv ...
Unidata has created the new home account. This account contains only
the include and sys directory with Unidata's cataloged programs. To access
your new home account, you must reset the UDTHOME environment variable
or change the value in your registry.
3. Modify VOC Entries for Users

Decide which UniData accounts should access the new global catalog space. For each account,
modify the VOC entry for CTLGTB. The entry should point to the new global catalog space, as
shown in the following example.
Notice that this example uses a soft pointer to @UDTHOME. This ensures that the VOC always
points to the correct catalog space.
Screen Example
: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.
*--:
You do not need to log in as an Administrator to edit the VOC entries; however, you need write
permissions on the VOC file in each account.
340
4. Modify UDTHOME for Users

You need to reset the UDTHOME environment variable for each user who needs to access the
alternate global catalog space. The value of UDTHOME that is defined during a particular
UniData session determines the global catalog space a user accesses.
Note
Even if the VOC file is set up to point to the alternate global catalog (CTLGTB), a user whose
UDTHOME is set to the default value accesses the default global catalog space.
5. Copy Application Programs

After resetting UDTHOME to point to the new space, start UniData from an account that has
access to the site-specific programs that you want to access from the new account, and recatalog
those programs. Because you have reset the UDTHOME environment variable, the recataloged
programs are placed in the new space.
6. Use the Alternate Global Catalog Space

The alternate global catalog space is now ready to use. The following example shows the output of
the sbcsprogs command when two global catalog spaces are used:
Screen Example
% sbcsprogs
Program Name
...
1
\UniData52\testenv\sys\CTLG\a\AE
\UniData52\testenv\sys\CTLG\a\AE_UPS
\disk1\ud52\sys\CTLG\a\AE
\disk1\ud52\sys\CTLG\a\AE_ICOM1
\disk1\ud52\sys\CTLG\a\AE_UPS
...
%
Reference Count
1
1
1
1
341
Notice that AE is running twice, but that the two copies are cataloged in different global catalog
spaces.
342
and Using Tape Devices
This chapter describes UniData commands for identifying and accessing Windows NT or
Windows 2000 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.
343
Chapter 16 - Managing and Using Tape Devices
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.

ECL Tape Handling Commands
344
UniData Tape Handling Commands
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
Reasd the next available record from tape.
RESIZET
Changes the block size used by the WRITET statement.
REWIND
Rewinds a tape to the beginning.
WEOF
Writes an end-of-file mark to a tape.
WRITET
Writes the value of a specified expression as a record on a

tape.
UniBasic Tape Handling Commands
Note
See the UniBasic Commands Reference for information about these UniBasic commands.
345
SETTAPE
Syntax
SETTAPE unit.no [dn.path.nr][dn.path.r][blocksize]
Description
The SETTAPE command defines logical tape units in your UniData environment. This command
establishes a link between a UniData internal tape unit number and a tape device. You can use
SETTAPE to relate unit number to tape devices or disk files.
Any user can execute SETTAPE unit.no to display the current settings for a tape unit. However,
you must be log in as an Administrator to define a tape unit or modify settings.
Once a tape unit has been defined using SETTAPE, it can be accessed by users in any UniData
account on your system. The tape unit definition remains the same unless it is changed by an
Administrator.
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:
Screen Example
:SETTAPE 0 \\.\TAPE0 R\\.\TAPE0 16384
Writing to a File
To relate a tape unit number to a disk file, use the full path and file name in the SETTAPE
command syntax. The disk file must already exist. The following example shows how to identify a
disk file with SETTAPE:
346
SETTAPE
Screen Example
:SETTAPE 1 A:\TAPEFILE RA:\TAPEFILE 4096
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; must be a multiple of 512. If you do not

specify blocksize, the default value is 4096.
SETTAPE Parameters
347
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 execute the SETTAPE command to define up to 10 tape
units for the UniData environment.
Reminder
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 NT or Windows 2000
device names.
Warning
When defining tape units, be sure to define unit 0. Some of the UniData tape handling commands
require unit 0 to be defined so that it can be used as a default.
When you define a tape device or modify a definition, you create or update an entry in the text file
udthome\sys\tapeinfo.
2. Attach a Tape Device

You must attach a logical tape device to your process before accessing it. The T.ATT command
attaches a tape device. Any user can execute T.ATT from the ECL prompt or from within a
UniBasic program. The following screen shows some typical outputs from T.ATT:
Screen Example
: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
348
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 execute T.ATT successive times to change the tape block size and also the tape
length. If you do not specify BLKSIZE, T.ATT uses the default tape block size specified in
SETTAPE.
Only one process can attach a tape unit at any time. You can attach more than one tape unit
to a single process, but you cannot attach the same tape unit to more than one process.
You can use the ECL T.STATUS command to list all defined tape units, and see which
ones are attached and which are available. The following screen shows sample output
from T.STATUS:
Screen Example
:T.STATUS
UNIT
NUMBER
0
1
2
STATUS
UDTNO
ASSIGNED
ASSIGNED
ASSIGNED
103
121
128
USER
NAME
CHANNEL
NAME
ASSIGNED
BLOCKSIZE
USER01
\\.\TAPE0
16384
Administrator
A:\TAPEFILE
terric
\USERS\DEFAULT\TAPE
4096
1638\
4
:
Notice that the tape devices for tape units 1 and 2 are actually disk files. A:\TAPEFILE is a FAT
file, while \USERS\DEFAULT\TAPEFILE is a NTFS file. When using a disk file as a tape device
the functionality is naturally limited to simple loads and unloads, but this may be useful for
demonstration or testing.
349
Warning
Do not specify a disk drive (for instance, A:) as a tape device. SETTAPE may succeed, but you
will be unable to write to the disk drive. If you wish to dump files to disk, create disk files and then
specify the disk files as tape devices.
3. Read From, or Write To, the Tape Device

When a tape unit is attached, you can access it from ECL or within a UniBasic program. The
following example shows some typical outputs when a process with tape unit 1 attached executes
the ECL T.DUMP command:
Screen Example
:T.STATUS
UNIT
NUMBER
0
1
2
:SELECT VOC
STATUS
AVAILABLE
ASSIGNED
AVAILABLE
WITH F1=PA
UDTNO
128
USER
NAME
terric
CHANNEL
NAME
A:\TAPEFILE
ASSIGNED
BLOCKSIZE
16384

>T.DUMP VOC MU 02
Unit 2 not attached yet.
>T.DUMP VOC MU 4
Unit 0 not attached yet.
>T.DUMP VOC MU 01
7 record(s) dumped to tape
:
Notice the following points about the example:
350
You cannot write to a tape device unless it is attached with T.ATT. If you have attached
more than one device, you must specify the device to write to or read from. If you have
attached only one device, UniData accesses the device you attached.
With T.DUMP, you can write from an active select list.
If you supply a single-digit value (for instance, 4) UniData interprets the digit as the
conversion code, and attempts to attach the default device (unit 0).
Reminder
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.
351
352
Chapter 17 - CALLC and

CallBasic
UniData provides the UniBasic CALLC command for executing functions written in C, C++, or
Delphi from UniData, and the CallBasic API for executing UniBasic subroutines from external
programs. This chapter describes commands and procedures for using these tools.
Note
See the UniBasic Commands Reference for more information about the syntax and use of the
CALLC command.
353
Chapter 17 - CALLC and CallBasic
Dynamic Link Libraries (DLLs) and UniData

Both the CALLC implementation and the CallBasic implementation in UniData for Windows NT
or Windows 2000 use the Microsoft Windows Dynamic Link Library (DLL) facility. This facility
allows separate pieces of code to call one another without being permanently bound together.
Linking between the separate pieces is accomplished at runtime (rather than compile time) through
a Dynamic Link Library (DLL) interface. Both the CALLC interface (for calling external functions from UniData) and the CallBasic interface (calling UniData functions from external code)
are implemented as DLLs.
For CALLC, developers create a DLL and then call that DLL from UniData. Special VOC
entries for each function called from a DLL communicate interface information to
UniData.
For CallBasic, developers link their code with UniData.LIB (located in the UniData bin
directory) and then make calls into the UniData DLL. The .LIB file supplies interface
information.
Because linking between caller and DLL is accomplished at runtime, either the caller or the DLL
can be modified independently. For UniData, this means that you can upgrade your UniData
version without the need to relink with external routines, and you can update your external DLL
without the need to relink UniData.
A DLL is language independent. Many software development environments for Windows can
produce a DLL.
Note
Consult the documentation for your software development environment for information about
linking code into a DLL.
354
Calling External Routines From UniData

Many applications use functions written in high-level languages like C++ for purposes like
environment definition, security, or low-level data transfers (similar to the UniBasic GET and
SEND functions). Through the CALLC command, UniData allows 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).
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,
355
they must be in the range 1 through n, where n is the number of functions exported by the
DLL.
Tip
See Examples in this chapter 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 NT or Windows 2000 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 NT or Windows 2000.
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.
356
Note
For C and C++, the default calling convention is _cdecl. For Delphi, the default calling convention
is Pascal. You can use the Pascal convention in C or C++, and you can use the _cdecl convention
in Delphi; consult the documentation for your development environment for information about
choosing a calling convention.
UDT.OPTIONS 88 allows CALLC to function correctly with both _cdecl and Pascal style calling
conventions. The following table describes the behavior of CALLC commands with this option
turned on or off:
UDT.OPTIONS
88
_cdecl Convention
Pascal Convention
OFF (default)
CALLC fails, terminating

the UDT
CALLC executes.
ON
CALLC executes
CALLC fails, terminating the udt.
UDT.OPTIONS 88
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)
357

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.
CALLC Parameters
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.
Data Types for CALLC
358
Data Type
Description
BSTRING
Pointer to a binary string descriptor.
NONE
Use for functions that do not return anything

(for instance, VOID).
Data Types for CALLC (continued)
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.
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 via the users Path environment variable.
Attribute 3
Function name in the DLL.
Attribute 4
Data type for return value.
Attribute 5
Data type for first argument.
Attributes 6 - n
Data types for second through nth arguments.

Attributes of E Type VOC Entry
359
The following screen shows the VOC entry for a function named callcpp_subr1:
Screen Example
: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
Informix recommends that you keep your development environment clearly separate from your
production environment when developing a CALLC application. Separating environments is
useful in any case, but can be critical because difficulties in the external functions can terminate
udt sessions and potentially damage data.
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.
360
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.
361
C Example
The C example contains the components shown on the following window:
The example also includes the UniBasic program EXAMPLE_C, in the BP file in the demo
account.
Notice that, in the C example, a single program source file was compiled and linked to form the
DLL. One function, called ps, can be called from the DLL. The function accepts a process ID,
opens the Registry, and collects information about that process. The information is returned to the
UniBasic program that called the ps function.
The next screen shows a portion of the source code in psdll.c:
Program Example
.
.
.
#define DllExport
#define DllImport
362
_declspec( dllexport )
_declspec( dllexport )
.
.
.
struct _TIME_FIELD
{
INT
Hours;
INT
Mins;
INT
Secs;
INT
mSecs;
};
DllExport int ps( int processid, char *process_name, char *process_creator, cha\
r *processor_time, int *vmemory )
{
HANDLE
essToken;
.
.
.
hProcess, hProc\
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 screen shows the VOC entry for the ps function:
Screen Example
:CT VOC ps
VOC:
ps:
E
CALLC_DEMO\CALLC_C\psdll.dll
ps
INT
363
INT
STRING
STRING
STRING
INT_PTR
:
The following example is a portion of the sample UniBasic program that calls the ps function:
Program Example
.
.
.
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"
364
STOP
END
The function name in the CALLC statement matches the name in the E type VOC entry.
By default, the calling convention for a C program is the _cdecl convention. Therefore,
UDT.OPTIONS 88 must be turned on.
Error handling is based on the RESULT from the C function rather than the STATUS of
the CALLC statement. The statement can complete successfully (STATUS of 0) even if
the C function has encountered an error.
The next example shows output from the sample program:
Screen Example
:RUN BP_SOURCE EXAMPLE_C
THIS UNIBASIC PROGRAM CALLS A C ROUTINE AND THEN DISPLAYS
OUTPUT TO THE SCREEN.
TURNING ON UDT.OPTIONS 88; REQUIRED FOR C
THE ID OF MY CURRENT UNIDATA PROCESS IS: 149
PASSING THE ID TO THE C ROUTINE.
THE C ROUTINE RETURNED: 1
PID
COMD
CREATOR
PROCESSOR TIME
VIRTUAL MEMORY
------------------------------------------------------------------149
udt.exe
terric
00:00:04.1687
32366592
TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING

:
365
C++ Example
The following screen shows the components of the C++ example:
In this example, three functions are compiled and linked into a single DLL. The file callcpp.def
lists the functions that can be called from the DLL:
Program Example
LIBRARY callcpp_test
DESCRIPTION 'For CALLC test on .cpp files'
EXPORTS
callcpp_subr1
callcpp_subr2
callcpp_subr3
366
@1
@2
@3
Tip
The example was developed using Visual C++. Consult the documentation for your development
environment for information about file naming conventions and procedures for creating a DLL.
The EXPORTS statement is used to export the three functions that can be called from the
DLL.
The names of the functions you can call do not need to match the names of the source
files, provided they are correctly defined.
The UniBasic program EXAMPLE_CPP calls one of the three functions from callcpp_test.dll. A
segment of this program is shown in the next example:
Program Example
.
.
.
PRINT "TURNING ON UDT.OPTIONS 88 FIRST; NEEDED FOR C++"
EXECUTE "UDT.OPTIONS 88 ON"
RESULT = CALLC callcpp_subr3(int,short,long,char,string,filename)
PRINT "THE SUBROUTINE RETURNED: ":RESULT
.
.
.
PRINT "TURNING OFF UDT.OPTIONS 88 BEFORE CLOSING"
EXECUTE "UDT.OPTIONS 88 OFF"
STOP
END
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
367
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:
Screen Example
: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 via CALLC statements.
The following screen shows a portion of the program source for callcpp_subr3:
Program Example
/*
*
368
Function:
Calls several Win32 APIs to print out the values of
*
*/
received parameters to a output file.
int
callcpp_subr3(int arg_int,short arg_short,long arg_long,
char arg_char,char *arg_string,char *fname)
{
HANDLE hOutputFile;
DWORD
dwStringLen, dwByteWritten;
char
Buf[256],WriteBuf[10*256];
The next screen shows output from the sample UniBasic program:
Program Example
: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
:
369
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:
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:
370
Program Example
.
.
.
{ 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:
Program Example
.
.
.
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
.
371
.
.
The next screen shows the output from the sample UniBasic program:
Screen Example
: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
:
372
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 environmentYour 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 programsYou 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 subroutinesYou must code, compile, and globally catalog your
UniBasic subroutines.
How CallBasic Works

The CallBasic API includes four functions:
373
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.
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.
374
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.
375
Sample Programs
C Program Example
The following C program, called callbasic_example1.c, is an extremely simplified example that
illustrates the components required for CallBasic:
Program Example
#include <stdio.h>
#define NT
#ifdef NT
#include <windows.h>
#endif /* NT */
/* Declare UniData callbasic functions */
#ifdef CPP /* for c++ */
extern "C" int udtcallbasic_init(int i, int j);
extern "C" int udtcallbasic(char *xbuf, char *ybuf, int i, char *arg, ...);
extern "C" int udtcallbasic_done(int k);
extern "C" int U_callbas(char **xbuf, char *ybuf, int i, char **zbuf);
#else /* for c */
extern int udtcallbasic_init();
extern int udtcallbasic_done();
extern int U_callbas();
#endif /* CPP */
#ifdef NT
extern int udtcallbasic();
#endif /* NT */
void main()
{
/* Declare variables */
char *rtn;
char arg0[BUFSIZ];
char arg1[BUFSIZ];
376
Sample Programs
char *args[2];
int sts;
/* Initialize the UniData environment */
udtcallbasic_init(0,0);
/* Assign arguments for the UniBasic routine */
strcpy(arg0, "Plants");
strcpy(arg1, "Animals");
args[0] = arg0;
args[1] = arg1;
printf(Executing UniBasic subroutine using U_callbas()...\n");
/* Call the UniBasic routine */
sts = U_callbas(&rtn, "EXAMPLE", 2, args);
if (sts == 0){
printf("Return value from UniBasic subroutine is %s\n", rtn);
#ifdef NT
/* Variable rtn returned by UniData come
from the process heap, not the C-Runtime
heap. It cannot be free'd with free().
They must be freed with HeapFree().
*/
HeapFree(GetProcessHeap(), 0, rtn);
#else
free(rtn);
#endif /* NT */
#ifdef NT
/* Allocate memory for return variable */
rtn = (char *)malloc(256);
printf("\nExecuting UniBasic subroutine using udtcallbasic()...\n");
/* Call the UniBasic subroutine using udtcallbasic. */
sts = udtcallbasic(rtn, "EXAMPLE", 2, args[0], args[1]);
if (sts == 0){
}
377
/* Free memory */
free(rtn);
#endif /* NT */
}
/* Close everything properly */
udtcallbasic_done(sts);
}
Notice the following points about callbasic_example1.c:
C and C++ Syntax

The example shows the correct syntax for declaring the UniBasic functions in both C++ (#ifdef
CPP) and C.
Header Files
You must include stdio.h and windows.h.
Initializing CallBasic
This statement initializes CallBasic, effectively starting a udt session for your C program:
udtcallbasic_init(0, 0);
Notice that it is executed once and only once in the C program.
Warning
If you initialize CallBasic more than one time or you do not initialize at all, you will encounter
errors and your program may fail with an exception.
Calling a UniBasic Subroutine: U_callbas

In this statement, we call the subroutine and assign the return to a variable.
378
Sample Programs
Program Example
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 NT or Windows 2000,
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:
Program Example
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 freed with HeapFree().
*/
HeapFree(GetProcessHeap(), 0, rtn);
379
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:
Program Example
sts = udtcallbasic(rtn, "EXAMPLE", 2, args[0], args[1]);
if (sts == 0){
}
/* Free memory */
free(rtn);
When you use the udtcallbasic function, your calling process is responsible for allocating and
freeing the memory for the return variables. If your process fails to free the memory, your
application is said to have a memory leak, which can cause significant performance degradation
over time.
Freeing Memory
When your process allocates the memory for the return variable, you can use free( ) to free it.
Notice that the program segment illustrates this technique as well:
Program Example
sts = udtcallbasic(rtn, EXAMPLE, 2, args[0], args[1]);
if (sts == 0){
380
Sample Programs

}
/* Free memory */
free(rtn);
Ending CallBasic
The last step in the C program is:
Program Example
/* 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.
Program Example
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.
381
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);
Heres the udtcallbasic call to the subroutine:

sts = udtcallbasic(rtn, EXAMPLE, 2, args[0], args[1]);
And heres the first line of the subroutine:

SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)
Additional Information
The UniBasic subroutine must be created, compiled, and cataloged in a UniData account. The
routine may be globally, directly, or locally cataloged. However, if you catalog the routine directly
or locally, you must execute the C program from the UniData account where the subroutine is
cataloged. Regardless how you catalog the UniBasic subroutine, you must execute the C program
from a valid UniData account.
382
Steps for CallBasic
Steps for CallBasic

Complete the following steps to access UniData from an external program with CallBasic.
Warning
Informix recommends that you keep your development environment clearly separate from your
production environment when developing a CallBasic application. Separating environments is
useful in any case, but can be critical because difficulties in the external programs can terminate
udt sessions and potentially damage data.
1. Code and Compile the Application 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:
Program Example
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\
383
/out:$(OUTDIR)/callbasic_example1.exe
:
Reminder
See the C Program Example in this chapter for a listing of callbasic_example1.c. The sample
program and makefile are also in the CALLBASIC_DEMO folder in your UniData demo account.
2. Code, Compile, and Catalog the UniBasic

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:
Screen Example
: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'.
In D:\UniData\sys\CTLG\a\AE at line 995 EXAMPLE has been cataloged, do you want\
384
Steps for CallBasic
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:
Reminder
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.
385
386
Chapter 18 - Monitoring
and Tuning UniData
This chapter outlines considerations that can affect UniData performance on your Windows NT or
Windows 2000 platform and describes UniData-specific procedures for monitoring performance.
387
Chapter 18 - Monitoring and Tuning UniData
Monitoring Your Windows NT or Windows 2000

System
The Performance Monitor provides great flexibility for monitoring the behavior of your Windows
NT or Windows 2000 system. From the Start menu, point to Programs, then point to Informix,
then point to UniData RDBMS 2.0, and then click Performance Monitor to invoke the Microsoft
Performance Monitor. You can also access the Performance Monitor by pointing to Programs,
then pointing to Administrative Tools (common), and then clicking Performance Monitor from
the Start menu.
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.
Informix recommends you monitor your system performance regularly to develop baseline
expectations throughout your processing cycle. The performance history of your system provides
information you can use to implement new procedures (such as scheduling certain jobs to run offhours 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.
388
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 4K bytes.
When possible, avoid long, multivalued, variable-length records.
Locate the most frequently accessed attributes near the beginning of a record.
As far as possible, keep key lengths numeric and small in length.
Using Alternate Key Indexes

Using alternate key indexes speeds query access in a hashed file, but can slow down updates.
Consider this factor when creating indexes. The more indexes created for a file, the longer an
update takes.
Index overflows occur when the maximum length value is too small for the fields being indexed.
Index overflows can degrade performance for query as well as update access. The solution for
index overflows is to delete all the indexes for a file and rebuild them with a longer maximum
length value.
Tip
Use the UniData LIST.INDEX tool to identify index overflow problems. Consider running
LIST.INDEX periodically. See Using UniData for information about alternate key indexes.
Sizing Static Hashed Files

Performance loss results if UniData hashed files are allowed to overflow. Level 2 overflow, which
occurs when primary keys outgrow a block, has a particularly serious performance impact. Level 1
overflow, which occurs when data overflows a block, eventually affects performance as well.
For information about file sizing commands, see the UniData Commands Reference.
389
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
390
Use the EQUATE command where possible.
Use CASE statements instead of IF, THEN, ELSE structure whenever possible. Avoid
nested IF, THEN, ELSE.
Use UniData @variables.
Minimize new assignment of variables.
Eliminate GOTO statements.
Use GOSUB instead of external CALLs when appropriate; use CALL when multiple
programs access the same code.
When using CALLs:
Avoid opening files; pass through COMMON or an argument list.
Minimize local variables in subroutines.
Use inserts, COMMON, and argument lists whenever possible.
Use A += B instead of A = A + B.
Use LOOP and REMOVE when extracting data sequentially from a string.
Avoid unnecessary shell commands; minimize PERFORM, EXECUTE, and

MDPERFORM statements.
Use CALL or CHAIN to run another UniBasic program.
Avoid repeated ITYPE( ) function calls.
Minimize use of EXECUTE SELECT..... by:
Using UniBasic SETINDEX, READFWD, READBCK.
Using the UniBasic SELECT command.
Use Dynamic Arrays and Matrices Appropriately
Use dynamic arrays when you are accessing small strings and variables.
Use matrices if you are handling a large number of attributes and multivalued strings.
Use the Correct READ in Each Situation
Use READ when you are accessing small records, and the data you want is near the
beginning of each record.
Use READV if your intention is to get only one attribute.
Use MATREAD when:
You are handling records with a large number of attributes, and you want to access
more than one attribute.
You are handling large multivalued lists.
Manage Locks Carefully
Use the LOCKED clause with a loop.
Remember to release locks promptly.
391
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.
Complete the following steps to create UniBasic execution profiles.
1. Compile the Programs with -G

Compile UniBasic programs with the -G option to include information about internal subroutines
in the profile reports.
2. Execute the Programs with -G

To profile a UniBasic program, run the program with the -G option. See Developing UniBasic
Applications for information about compiling and running programs.
3. Review the Profile Output

UniData stores profile output in the NTFS directory where the UniBasic program was executed.
Output files are called profile.pid and profile.elapse.pid where pid is the process ID (USRNBR in
LISTUSER output) of the users UniData process.
The following example shows a portion of a profile report for a sample UniBasic program:
Screen Example
%time cumsecs seconds
87.6
6.7
3.3
2.4
0.19
0.20
0.21
0.21
0.19
0.01
0.01
0.01
calls name
1215
5
60
1
BP\_TIME_TST:C
BP\_TIME_TST:A
BP\_TIME_TST:B
BP\_TIME_TST
called/total
392
parents
UniBasic Profiling
index
%time
self descendents
[1]
100.0
0.01
0.01
0.21
0.19
called+self
called/total
1
5/5
name
children
index
<spontaneous>
BP\_TIME_TST [1]
BP\_TIME_TST:A [2]
----------------------------------------------
[2]
97.6
0.01
0.01
0.01
0.00
0.19
0.19
0.18
0.00
5/5
5
60/60
15/1215
BP\_TIME_TST [1]
BP\_TIME_TST:A [2]
BP\_TIME_TST:B [3]
BP\_TIME_TST:C [4]
----------------------------------------------
[3]
89.8
0.01
0.01
0.18
0.18
0.18
0.00
60/60
60
1200/1215
BP\_TIME_TST:A [2]
BP\_TIME_TST:B [3]
BP\_TIME_TST:C [4]
----------------------------------------------
[4]
87.6
0.18
0.00
0.19
0.00
0.00
0.00
1200/1215
15/1215
1215
BP\_TIME_TST:B [3]
BP\_TIME_TST:A [2]
BP\_TIME_TST:C [4]
----------------------------------------------
In this example, the main program is called TIME_TST. It has three internal functions, named A,
B, and C.
Note
profile.pid reports execution times as CPU execution time, while profile.elapse.pid reports real
time.
393
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 of the program used by the

function
cumsecs
Running sum of seconds the function and those listed above

it used within a cycle
seconds
Number of seconds used by the function in a cycle
calls
Number of times the function was invoked in a cycle
name
Name of the function

UniBasic Profiling: Summary Information
UniData sorts program functions by execution time, and assigns an index to each function for ease
of reporting. For each index, UniData computes information about functions that call, or are called
by, the function corresponding to the index. The detail section of a profile contains this
information, grouped by index. The next table describes the fields in the detail section.
Field
Description
index
Assigned by UniData. The indexes are assigned in descending order of

execution time for the functions of the program. The index in column 1
identifies the routine of interest for the group of data (the current index
function).
%time
Reported for the current index function; percentage of the execution time used
by the current index function and its descendents.
self
Time spent by the function either calling, or being called by, the function
identified by the current index.
descendents
Time spent by the descendents of the function.

UniBasic Profiling: Detail Information
394
UniBasic Profiling
Field
Description
called
For parents of the current index function, the number of times the function
calls the current index function. For descendents of the current index function,
the number of times the function is called by the current index function.
called+self
Reported for the current index function; the number of times the function is
called by others, plus the number of times the function calls itself recursively.
name
Function name.
index
Index value assigned to the function.

UniBasic Profiling: Detail Information (continued)
The following screen shows one group of data, selected from the sample UniBasic profile:
Screen Example
----------------------------------------------
[2]
97.6
0.01
0.01
0.01
0.00
0.19
0.19
0.18
0.00
5/5
5
60/60
15/1215
BP\_TIME_TST [1]
BP\_TIME_TST:A [2]
BP\_TIME_TST:B [3]
BP\_TIME_TST:C [4]
----------------------------------------------
This subset of the report contains data relative to the internal function A, which is identified by
index number 2. Parent functions, or functions which call A, are listed above it; descendents,
or functions called by A, are listed beneath it.
In the example, the report indicates that 97.6% of the execution time for the entire program is used
by A. The function is called 5 times, all by the main program, BP/TIME_TST. In turn, A is
responsible for all 60 of the calls to B, and 15 of the 1,215 calls to C.
395
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 NT or Windows 2000 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 execute the Microsoft Performance Monitor in either of two ways:
396
From the Start menu, point to Programs, then point to Administrative Tools
(Common), and then click Performance Monitor.
From the Start menu, point to Programs, then point to Informix, then point to UniData
RDBMS 5.2.0, and then click Performance Monitor.
You can select output options from the View menu. UniData monitoring categories are included in
the list of Objects for each view option. There are five UniData-specific objects you can monitor:
Select any of the UniData statistics by clicking its entry in the Object list. The following sections
describe each group of UniData statistics.
Tip
The UniData Objects are listed in alphabetical order in the Object list, and the statistics you can
monitor for each category are listed alphabetically in the Counter list for each object.
397
UniData Dynamic Array Statistics

If you choose UniData Dynamic Array, you will see a window similar to the following example:
Tip
You can scroll through the list of counters to see all values.
The Counters are counts for executions of UniBasic commands described in the following table.
Field
Description
COUNT
Number of dynamic array counts, from COUNT command.
DELETE
Number of dynamic array deletions, from DEL command.
EXTRACT
Number of dynamic array data extractions, from EXTRACT command.
FIELD
Number of dynamic array string extractions, from FIELD command.
FIND
Number of dynamic array finds, from FIND command.
INDEX
Number of dynamic array substring indices, from INDEX command.
INSERT
Number of dynamic array inserts, from INS command.
LOCATE
Number of dynamic array locations, from LOCATE command.

Dynamic Array Counters
398
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.

Dynamic Array Counters (continued)
UniData File I/O Statistics

When you select UniData File I/O from the Object list, a window similar to the following appears:
Tip
You can scroll through the list of Counters to see all values.
399
The following table describes the counters you can monitor for File I/O, and indicates
considerations for performance.
Field
Description
Dynamic File Group

Split
Number of times a group in a dynamic file splits.
Dynamic File Group

Merge
Number of times a split pair of groups merges back together.
File Close
Number of file closes at the operating system level, from UniBasic

CLOSE commands.
Level 1 Overflow
Number of operations (reads, writes, deletes) to records in level 1

overflow blocks. Compute the total activity by summing Record Read,
Record Write, 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.
Level 2 Overflow
Number of operations (reads, writes, deletes) to records in level 2

overflow blocks. If Level 2 Overflow is more than 2% of total activity,
use guide to identify files in level 2 overflow and resize them
appropriately.
Logical File Open
Number of logical file opens from UniBasic commands. Under Windows NT or Windows 2000, if a process opens a file while another process has the file open, UniData handles the second open as a logical
rather than a physical file open. Logical file opens involve less overhead than physical file opens, so performance can be improved by opening files in named COMMON at the beginning of a program, and using
logical opens for subsequent access.
Physical File Open
Number of file opens at the operating system level, from UniBasic

OPEN commands. On Windows NT or Windows 2000, 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 I/O Counters
400
Field
Description
Record Delete
Number of records deleted by UniBasic commands.
Record Read
Number of records read by UniData commands (other than UniQuery).

For most applications, Record Read is greater than Record Write.
Record Write
Number of records written by UniData commands.
TempFile Close
UniData temporarily closes the least-recently-accessed open file when

requests for file opens exceed the limit of open files per process. If the
average value in this field is consistently more than zero, consider
increasing the UniData configuration parameter NFILES.
File I/O Counters (continued)
UniData Index Statistics

When you choose UniData Index Statistics from the Object List, you will see a window similar to
Tip
401
The following table describes the Counters you can monitor for UniData Index Statistics, and
presents some tuning recommendations.
Field
Description
Index Log Read
Number of reads from an index log file; these occur when an index
which was disabled is re-enabled and updated with the contents of the
index log.
Index 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.
Index Node Merge
Number of times two nodes merge; this takes place when entries in one
or both nodes decrease.
Index 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.
Index Node Reuse
Number of times a node previously freed by a node merge is used for a

node split.
Index 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. Use the
ECL LIST.INDEX command to identify these, and then execute
DELETE.INDEX...ALL, and CREATE and BUILD the indexes with a
longer key length.
Index Node Write
Number of index node writes.
Index 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.
Index Counters
402
Field
Index Overflow
Write
Description
Number of times UniData writes an overflow node.
Index Counters (continued)
UniData Lock Statistics

When you choose UniData Lock Statistics from the Object List, you will see a window similar the
following example:
Tip
403
The following table describes the Counters you can monitor for UniData Lock Statistics, and
indicates performance considerations.
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 may be overflowed.
Identify these with guide.
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 with LIST.INDEX.
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.
Record Lock
Number of user-level record locks set by commands such as READL

and READU.
Record Unlock
Number of user-level locks released by commands such as RELEASE.
Semaphore Lock
Number of user-level resource locks set by commands such as LOCK

and T.ATT.
Semaphore Unlock
Number of user-level resource locks released by commands such as

T.DET or UNLOCK.
Shared Group Lock
UniData-level read-only lock on an entire group.
Shared Index Lock
UniData-level read-only lock on an index.

Lock Counters
404
Note
In some circumstances, the output display may indicate that more records are being unlocked than
are being locked. This is a function of how UniData gathers the statistics and does not indicate a
problem.
UniData Program Control Statistics

If you choose UniData Program Control from the list of Objects, you will see a window similar to
Tip
The following table describes the Counters you can monitor for UniData program control, and
indicates performance considerations.
Field
CALLC Call
Description
Number of calls to an external C function, from UniBasic CALLC
statements.
Program Control Counters
405
Field
Description
CHAIN Call
Number of UniBasic CHAIN statements executed.
EXECUTE Call
Number of external UniData command executions (from UniBasic

EXECUTE commands).
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.
GOSUB Call
Number of UniBasic GOSUB commands executed.
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 local
calls, examine your application and globally catalog programs for more
efficient memory use.
LOOP and
GOTO
Number of UniBasic LOOP or GOTO commands executed.
PCPERFORM
Call
Number of PCPERFORM statements, which execute 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.
Program Control Counters (continued)
406
ECL Process Monitoring Commands

On Windows NT or Windows 2000, UniData includes three ECL commands that you can invoke
to collect and display statistics for their current UniData processes. The commands are:
ENABLE.USERSTATSThis command turns on statistics collection for the users

current process. Executing this command starts statistics collection for that process, which
continues until the user exits UniData or executes the DISABLE.USERSTATS command.
DISABLE.USERSTATSThis command turns off statistics collection for the users

current process. Users can turn statistics collection back on by executing
ENABLE.USERSTATS, but all totals are zeroed out each time a user turns off statistics
collection.
LIST.USERSTATSIf the user turned on statistics collection with

ENABLE.USERSTATS, LIST.USERSTATS displays a snapshot of the statistics for the
users process that were collected since that time. If the user did not turn on statistics
collection, or turned it off before executing LIST.USERSTATS, this command displays a
list of statistics collected for the entire system since the last time the Windows NT or
Windows 2000 machine was shut down and restarted.
Warning
If you are using the Performance Monitor to monitor overall UniData behavior, and one or more
users execute ENABLE.USERSTATS, those processes will not be counted in Performance
Monitor output. Statistics for a udt process are recorded in only one place at one time, and the ECL
Statistics commands override the performance monitor.
The statistics reported by LIST.USERSTATS are virtually identical to those monitored with the
Performance Monitor, although they are organized somewhat differently. The following example
shows the output of LIST.USERSTATS for a single udt process:
Screen Example
:LIST.USERSTATS
File I/O Statistics
Physical File Opens........ 8
Logical File Opens......... 0
407
File Closes................
Temp File Closes...........
Dynamic File Split.........
Dynamic File Merge.........
Record Reads...............
Record Writes..............
Record Deletes.............
Level 1 Overflow...........
Level 2 Overflow...........
Program Control Statistics
Private Code Calls.........
Shared Code Calls..........
Shared Code Failures.......
CALLC Calls................
Chain Calls................
Gosub Calls................
Goto Calls.................
Execute Calls..............
Pcperform Calls............
Dynamic Array Statistics
DELETE.....................
FIND.......................
INSERT.....................
LOCATE.....................
MATPARSE...................
MATCHFIELD.................
COUNT......................
EXTRACT....................
FIELD......................
REMOVE.....................
REPLACE....................
INDEX......................
Lock Statistics
Record Locks...............
Record Unlocks.............
Semaphore Locks............
Semaphore Unlocks..........
Shared Group Locks.........
Exclusive Group Locks......
Shared Index Locks.........
Exclusive Index Locks......
Lock Failures..............
Index Statistics
Index Reads................
408
9
0
255
0
101
20060
1
25363
0
1
0
0
0
0
20000
0
3
0
0
0
0
0
0
0
0
20000
0
0
0
0
255
255
0
0
178
21626
0
0
0
0
Index Writes...............
Log Reads..................
Log Writes.................
Node Merges................
Node Split.................
Node Reuse.................
Overflow Reads.............
Overflow Writes............
0
0
0
0
0
0
0
0
There are a few differences in counter names between the Performance Monitor and
LIST.USERSTATS. These are described in the following table.
Performance Monitor
LIST.USERSTATS
Global Call
Shared Code Calls
Local Call
Private Code Calls
(Not reported)
Shared Code Failures (Number of times a process

called a globally cataloged program and the system
found insufficient memory to load the program.)
This number should be zero.
Counter Names
409
Examples
This section contains examples that illustrate some ways of using the Windows NT or Windows
2000 and UniData Performance Monitoring tools.
The following window shows how you can combine monitoring a system parameter (for instance,
CPU time) and a type of UniData activity (for instance, level 1 and level 2 overflow writes):
Notice that overflow writes are associated with an increase in CPU utilization.
410
Examples
The next window shows monitoring CPU use for a udt process and for the Windows NT or
Windows 2000 machine 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.
411
412
Appendix A - UniData
Configuration
Parameters
This appendix lists the names and descriptions for all UniData configuration parameters as of
Release 5.2. See Chapter 7 - Configuring Your UniData System, for more information about
modifying your udtconfig file.
The following tables describe the configuration parameters that are placed in the udtconfig file
located in \udthome\include at the time of installation. They are system-dependent and should not
be changed.
Parameter Name
Description
LOCKFIFO
The locking sequence of processes in the system. This

parameter should not be changed.
SYS_PV
Type of P/V operations used for the Recoverable File System

(RFS) only. Determined at installation; platform dependent.
Do not change unless instructed by Informix.
udtconfig File Parameters That Should Not Be Changed
413
Appendix A - UniData Configuration Parameters
The following parameters may be changed to suit your environment:

Parameter Name
Description
NFILES
Number of physical files that can be opened at the operating

system level at one time in a UniData session. This limit is
for both udt and tm processes; the name of the corresponding
kernel parameter varies among OS versions.
NUSERS
Limit for number of UniData user processes (such as udt and

PHANTOM) that can run at the same time.
WRITE_TO_CONSOLE
Switch for turning on and off messaging to your console.

Must be greater than zero for messages to display at console.
TMP
Path of a directory for storing intermediate work files.

Default is \Informix\ud52\temp.
NVLMARK
Specifies a character to print to represent the null value. The

ASCII character that represents the null value is nonprinting.
FCNTL_ON
Used with UniData Physical Lock Manager. If a UNIX

platform supports test-n-set instruction, SYS_PV is set to 3
and FCNTL_ON is set to 0. If a UNIX platform does not
support test-n-set instruction, SYS_PV is set to 2 and
FCNTL_ON is set to 1. Do not change this parameter unless
instructed to do so by Informix.
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 Informix.
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.
udtconfig File Parameters That Can Be Changed
414
Parameter Name
Description
N_FILESYS
Maximum number of UNIX file systems allowed. If you

have more than 200 UNIX file systems, increase to your
number of file systems.
N_GLM_GLOBAL_BUCKET
The number of hash buckets systemwide, used 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.
GLM_MEM_ALLOC
The number of lock nodes allocated for each memory

request. This parameter is highly application dependent. If
the application requires a large number of locks in one
transaction, this setting should be increased to the maximum
number of locks per transaction * 2.
GLM_MEM_SEGSZ
The segment size for each shared memory segment required

for the lock manager. The maximum number of segments is
16. Large application environments require a larger size.
Each udt will register the lock names it is locking in its perprocess locking table. This table is also organized as a hashed
table.
udtconfig File Parameters That Can Be Changed
415
The following parameter is related to internationalization.

Parameter Name
UDT_LANGGRP
Description
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.
Internationalization udtconfig File Parameter

The following table describes shared memory related parameters. These parameters may be
changed to suit your environment.
Parameter Name
Description
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 you attempt to load a new global program that
exceeds this limit.
SHM_MAX_SIZE
Current kernel setting for maximum size (in bytes) of a

shared memory segment. This parameter is set at installation;
if you increase the kernel parameter shmmax, you need to
increase SHM_MAX_SIZE to the same value as well.
SHM_ATT_ADD
Starting address for shared memory attachment. Set at

installation; do not change this unless instructed by Informix.
SHM_LBA
Alignment size, in bytes, for shared memory attachment. Set

at installation; do not change.
SHM_MIN_NATT
The minimum number of shared memory segments that

should be kept attached to a process.
Shared Memory udtconfig File Parameters
416
Parameter Name
Description
SHM_GNTBLS
Number of GCTs (global control tables) in CTL. Each shared

memory segment is associated with a GCT. The GCT
registers the use of global pages in its associated shared
memory segment. Cannot exceed the kernel parameter
shmmni.
SHM_GNPAGES
Number of global pages in a shared memory segment.
SHM_GPAGESZ
Size of each global page, in 512-byte units.
SHM_LPINENTS
Number of entries in the PI table of a LCT, which is the

number of processes allowed in a process group. It is set to
10 within the system, regardless of the udtconfig setting.
SHM_LMINENTS
Number of entries in the MI table of a LCT, which means the

number of global pages or self-created dynamic segments
that can be attached by a process. Cannot exceed 255.
SHM_LCINENTS
The number of entries in the CI table of each LCT, which is

the number of local pages that can be attached by a process.
SHM_LPAGESZ
Size, in 512-byte blocks, of each local page in a global page.

A global page is divided into local pages, so
SHM_GPAGESZ must be a multiple of SHM_LPAGESZ.
SHM_FREEPCT
Percentage of freed global pages in an active global shared

memory segment that UniData keeps in the global shared
memory pool. smm checks the current percentage; if the
percentage is less than SHM_FREEPCT, smm creates a new
shared segment.
SHM_NFREES
The number of inactive shared memory segments that

UniData keeps in the system. smm checks the current
number of inactive segments; if the number is larger than
SHM_NFREES, smm returns some inactive global shared
segments to UNIX.
Shared Memory udtconfig File Parameters (continued)
417
The following table describes size limitation parameters.

Parameter Name
Description
AVG_TUPLE_LEN
Number of local pages that matches the average length of

records in your applications. Specifies the length of a buffer
kept by udt for holding a record. Should not exceed the
number of local pages in a global page.
EXPBLKSIZE
Number of local pages used for expression buffers. udt keeps

a buffer of this size for intermediate results. Informix
recommends you set this parameter so the buffer is
one-quarter to one-half the size of a global page.
MAX_OBJ_SIZE
Maximum size, in bytes, of object programs that can be

loaded into shared memory. Object programs larger than this
size are loaded into the users address space instead of shared
memory.
MIN_MEMORY_TEMP
The minimum number of local pages that should be kept for

temporary buffers in a process group. Determined at
installation.
Size Limitation udtconfig File Parameters
The following table describes parameters related to dynamic files.

Parameter Name
Description
GRP_FREE_BLK
Pertains to dynamic files only; the number of free blocks kept

in the free block list at the group level. If more blocks are
freed, they are kept at the file level.
SHM_FIL_CNT
Maximum number of dynamic files that can be open

concurrently, system-wide.
Dynamic File udtconfig File Parameters
418
Parameter Name
Description
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.
MERGE_LOAD
Default loading factor (percent) at which a group pair in a

dynamic file using the KEYONLY option merges. A group
pair is eligible for merging when the sum of the percentages
of space occupied by keys and pointers in both groups is less
than MERGE_LOAD. The CONFIGURE.FILE command
lets users override this for individual files.
KEYDATA_SPLIT_LOAD
Default loading factor (percent) at which a group in a

dynamic file using the KEYDATA option splits. Splitting
occurs when the percentage of space in a group occupied by
keys and pointers reaches the split load. The ECL
CONFIGURE.FILE command overrides this for individual
files.
KEYDATA_MERGE_LOAD
Default loading factor (percent) at which a group pair in a

dynamic file using the KEYDATA option merges. A group
pair is eligible for merging when the sum of the percentages
of space occupied by keys and pointers in both groups is less
than KEYDATA_MERGE_LOAD. The CONFIGURE.FILE
command overrides this for individual files.
MAX_FLENGTH
Upper size limit, in bytes, of each partition file (dat00x) of a

dynamic file. When a part file reaches this size, UniData does
not add further blocks to it, but creates another part file using
the part table. The default value is 1073741824 bytes (1 GB).
Must be greater than 32768 bytes (32 KB) and less than
2147467264 bytes (2 GB-16KB).
Dynamic File udtconfig File Parameters (continued)
419
Parameter Name
PART_TBL
Description
Path of a UNIX text file that directs UniData where to create
dynamic file part files.
Dynamic File udtconfig File Parameters (continued)

The following parameter is for NFA server.
Parameter Name
Description
EFS_LCKTIME
Used by UniServer to specify the maximum time to wait for a

lock.
TSTIMEOUT
Used by the udtts executable to specify the maximum

number of seconds to wait for input from client about device
information. If the information is not provided, UniData
starts without the device information.
NFA udtconfig File Parameters
The following table describes parameters related to Journaling:

Parameter Name
Description
JRNL_MAX_PROCS
Maximum number of journal processes per journal path.
JRNL_MAX_FILES
Maximum number of journal files allowed per journal

process.
Journaling udtconfig File Parameters
420
The following table describes UniBasic file-related parameters.

Parameter Name
Description
MAX_OPEN_FILE
Maximum number of hashed files that can be opened by

UniBasic OPEN statements, per udt process. Includes RFS
and non-RFS, static, dynamic, and sequentially hashed files;
each dynamic file counts as one file.
MAX_OPEN_SEQF
Maximum number of sequential files that can be opened at

one time by UniBasic OPENSEQ statements, per udt
process.
MAX_OPEN_OSF
Maximum number of UNIX sequential files that can be

opened at one time by UniBasic OSOPEN statements, per udt
process.
MAX_DSFILES
Maximum number of nonrecoverable dynamic part files

(dat00x, over00x) a UniData process can open with UniBasic
OPEN statements or ECL commands. Each dynamic file has
at least two part files.
UniBasic File-Related udtconfig File Parameters
The following table describes parameters related to UniBasic.

Parameter Name
MAX_CAPT_LEVEL
Description
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.
UniBasic udtconfig File Parameters
421
Parameter Name
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.
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
VARMEM_PCT
The percentage of free memory that should be kept in the

first global page for UniBasic variables after compacting. If
the actual percentage is less than this value, UniData keeps
one free global page. Otherwise, UniData returns all free global pages to UNIX.
UniBasic udtconfig File Parameters (continued)
The following parameter is used in semaphore operations.

Parameter Name
NSEM_PSET
Description
Number of semaphores per semaphore set.
Semaphore udtconfig File Parameters
422
The following table describes index-related parameters.

Parameter Name
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.
Index udtconfig File Parameters

The following parameter is used with the UniData Physical Lock Manager.
Parameter Name
MGLM_BUCKET_SIZE
Description
Number of nodes per bucket. If this parameter is inadequate
for an application, an out of memory message is displayed.
Physical Lock Manager udtconfig File Parameters

The following parameter is used to turn the Recoverable File System off and on.
Parameter Name
SB_FLAG
Description
Toggles system buffer on and off. If zero, system buffer is
off. Must be greater than zero for RFS.
Recoverable File System on/off udtconfig Parameter
423
The following parameters are related to open files with the Recoverable File System.
Parameter Name
Description
BPF_NFILES
Per-process logical limit for total number of RFS files that

can be opened with UniBasic OPEN statements at one time.
If more RFS files are opened, UniData closes files and then
reopens them, causing heavy overhead. This parameter
cannot exceed N_AFT.
N_PARTFILE
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, so opening a dynamic file means opening at least two
part files. Even if more than one user opens the same
dynamic file, each part file is counted once toward the total.
Recoverable File System udtconfig Parameters
The following parameters are related to the active file table (AFT) used with the RFS.
Parameter Name
Description
N_AFT
System-wide limit on the number of recoverable files and

indexes that can be open at one time. This is the number of
slots in the system buffer AFT. Parameter is like
MAX_OPEN_FILES but pertains only to recoverable files.
A dynamic file counts as one file. Even if more than one user
opens the same file, it is only counted once.
N_AFT_SECTION
Number of sections in the AFT. Used for RFS only.
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.
Active File Table udtconfig Parameters
424
Parameter Name
N_TMAFT_BUCKET
Description
Number of hash buckets in each tm process active file table
(TMAFT). Used for RFS only.
Active File Table udtconfig Parameters
The following table describes parameters related to the archiving feature of RFS.
Parameter Name
Description
ARCH_FLAG
Toggles archiving function on and off for RFS. Must be

greater than 0 for archiving.
N_ARCH
The number of archive files.
ARCHIVE_TO_TAPE
Switch for turning on automatic save of archive files to

backup. Changing the value to 1 turns on this feature.
ARCH_WRITE_SZ
Size, in bytes, of blocks for the archive process to write from

the log files to the archive files. Default is zero, meaning
each write is one block. If set to a non-zero value, must be a
multiple of the log/archive block size.
Archiving udtconfig Parameters
The following parameters are used for the system buffer in the RFS.
Parameter Name
N_BIG
Description
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.
System Buffer udtconfig File Parameters
425
Parameter Name
N_PUT
Description
Number of 1,024-byte pages in the system buffer. The size of
the buffer cannot exceed SHMMAX. Sometimes the default
value of N_PUT must be decreased in order to complete a
UniData installation.
System Buffer udtconfig File Parameters
The following table describes parameters used for message queues with the Recoverable File
System.
Parameter Name
Description
N_PGQ
Number of message queues for tm processes to send

messages to udt processes. Calculated by installation; one
queue for every four licenses.
N_TMQ
Number of message queues for udt processes to send

messages to tm processes. Calculated by installation; one
queue for every four licenses.
Message Queue udtconfig File Parameters
The following table describes parameters related to the before image and after image log files used
with RFS.
Parameter Name
Description
N_AIMG
Number of after image log files in each log set.
N_BIMG
Number of before image log files in each log set.
AIMG_BUFSZ
The size of the after image buffer, in bytes.
BIMG_BUFSZ
The size of the before image buffer, in bytes.

Before Image/After Image udtconfig File Parameters
426
Parameter Name
Description
AIMG_MIN_BLKS
Minimum number of blocks required in the after image

buffer before the system flushes the blocks to the after image
logs. Block size is set in the log configuration table.
BIMG_MIN_BLKS
Minimum number of blocks required in the before image

buffer before the system flushes the blocks to the before
image logs. Block size is set in the log configuration table.
AIMG_FLUSH_BLKS
Number of blocks that are flushed to the after image logs

from the after image buffer at one time.
BIMG_FLUSH_BLKS
Number of blocks that are flushed to the before image logs

from the before image buffer at one time.
Before Image/After Image udtconfig File Parameters (continued)

The following table describes the parameters that determine flushing intervals for RFS.
Parameter Name
Description
CHKPNT_TIME
Checkpoint interval: number of seconds between flushes of

the system buffer to disk.
GRPCMT_TIME
Interval, in seconds, between flushes to the after image log

set.
LOG_OVRFLO
Path to the directory where UniData creates log overflow

files.
Flushing Interval udtconfig File Parameters
427
The following table describes the parameters related to the sync daemon.
Parameter Name
Description
N_SYNC
Determines how many sync daemons UniData should start.
SYNC_TIME
Defines the number of seconds the sync daemon should wait

before scanning the Block Index Group to flush dirty pages.
Sync Daemon udtconfig File Parameters
The following table describes the parameter related to the Century Pivot date.
Parameter Name
CENTURY_PIVOT
Description
Determines the century pivot date. Default is 1930.
Century Pivot udtconfig File Parameters
428
Appendix B Environment Variables

for UniData
This appendix lists environment variables that can be set to customize a UniData environment.
Users can set them before entering UniData to affect a particular UniData session. System
administrators can also set them for one or more users to establish defaults for some or all users.
The following table lists environment variables in alphabetical order.
Environment
Variable
Description
BACKUP_CNTL_FILE
Used by the Recoverable File System (RFS); specifies a path where

the udt.control.file can be automatically backed up at checkpoint
time. If this variable is not defined, udt.control.file is not backed
up. Valid on UniData for UNIX only.
CSTACKSZ
Establishes the maximum number of commands in the ECL

command stack. Each stack entry can hold a 2720 character
command. The default is 49.
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.
JRNL_PATH
Identifies a journaling directory if default path is not used.

Environment Variables for UniData
429
Appendix B - Environment Variables for UniData
Environment
Variable
Description
JRNL_RES_HOLD
If this variable is set to a number greater than 0, the journal restore

process sleeps for 1 second at intervals. If the value is between 1
and 100, the process sleeps after every 10,000 records are restored.
Otherwise, it sleeps after processing a number of records equal to
JRNL_RES_HOLD.
LPREQ
Identifies an alternate spooler directory. Must be a full path ending

in /. Valid on UniData for UNIX only.
MAX_CAPT_LEVEL
Number of levels allowed for nested UniBasic EXECUTE WITH

CAPTURING or MDPERFORM WITH CAPTURING clauses.
This environment variable overrides the configuration parameter in
the udtconfig file.
MAX_RETN_LEVEL
Number of levels allowed for nested UniBasic EXECUTE WITH

RETURNING or MDPERFORM WITH RETURNING clauses.
This environment variable overrides the configuration parameter in
the udtconfig file.
MAX_TRANS_
Number of TRANS fields that can be kept concurrently; default

value is 64; must not be greater than 64
FIELD
MAX_TRANS_REL
Number of TRANS files that can be open concurrently; default

value is 32; must not be greater than 32.
NFA_LOG_DIR
Used by NFA; name of a directory where NFA client-side log files

are created. If this variable is not defined, the logs are created in
\temp.
NFA_LOG_LEVEL
Used by NFA; debug level for NFA client processes. May be an

integer 0-10; level 0 logs only fatal errors, and level 10 logs all
traffic and many internal functions. The default is level 0.
NOCHKLPREQ
Bypasses UNIX printer verification; useful for large systems with

hundreds of printers defined. Valid on UniData for UNIX only.
Environment Variables for UniData (continued)
430
Environment
Variable
Description
RLBK_SECOND
Used by journaling; controls the interval (in seconds) that the

journal process waits before retrying on an operation where it
detected an error. Must be 1-10; if this variable is not defined,
UniData uses a 1-second interval.
SETINDEX_
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.
BUFFER_
KEYS
SETINDEX_
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.
VALIDATE_KEY
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.
TABSTOPS
Specifies a number of characters to tab in UniBasic PRINT

statements. Must be 1-76. The default is 8.
TMP
Identifies an alternate directory for \temp when additional work

space is needed by UniData. Must be a directory path ending with \.
UDT_EDIT
Identifies the path of the text editor UniData invokes when users
execute the ECL ED command. The default is the MS-DOS editor.
This variable cannot be set to AE.
UDT_SAVELIST
Allows you to specify a default list name for each UniData user. Set
in the users .login or .profile. Users can also specify a list name
when executing the SAVE.LIST command.
431
Appendix B - Environment Variables for UniData
Environment
Variable
Description
UDT_SELECTSIZE
Size of a buffer used to keep select list in memory. If a select list is

larger then the size of this buffer, it will be written to a file. If
UDT_SELECTSIZE is not defined, the system uses a buffer size of
10 KB.
UDTBIN
Location of UniData executables.
UDTHOME
Location of the UniData home directory, which contains directories

including sys, demo, lib, work, sybase, and include.
VFIELDSIZE
Increases the size for the stack of C routines used to process

formulas created in virtual fields. Default is 300. Define a larger
number if users see virtual field too big errors in UniQuery.
VOC_READONLY
If set to a non-zero 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.
432
Index
Symbols
/tmp directory, 130

@ID parameter of QUERY.PRIVILEGE file, 184
__V__VIEW file
component of UniData account, 160
__V__VIEWS file
dictionary for, 161
_HOLD_, 290
_HOLD_ file
dictionary for, 161
_HOLD_ subdirectory
clearing, 163
defined, 160
_MAP_ file, 328
_PH_ file
dictionary for, 161
_PH_ subdirectory
clearing, 163
defined, 160
_REPORT_ file
dictionary for, 161
_SCREEN_ file
dictionary for, 161
accounts
UniData
clearing space in, 163
creating, 133, 157
deleting, 162
described, 156
files in, 160
locating, 130
subdirectories in, 160
UNIX
creating, 133
ACCT.SAVE command
not blocked by dbpause, 145
adding
record to QUERY.PRIVILEGE file, 187
UNIX users, 133, 276
address space
attaching memory segment to, 114
algorithms, hashing, 190
ALT.BP.CMDS, 26
ALT.ECL.CMDS, 26
ANALYZE.FILE command
summarized, 215
433
Index
assigning
shared memory structure, 119
attaching
shared memory segment, 105, 114
automatic indexing
disabling, 211
enabling, 211
automatic startup of UniData, 143
B
background processes
daemon as, 104
storing output from, 160
backing up
file, 137
UniData account, 137
BLIST command
block size
changing, 136, 215
specifying
for dynamic file, 197
block usage messages, 246
BLOCK.PRINT command
BLOCK.TERM command
blocking UniData processing, 144
BP directory
defined, 160
dictionary for, 161
buffering
UniBasic variables, 115
BUILD.FULL.PATH, 27
BUILD.INDEX, 211
building
434
shared memory structures and tables, 107

BY.EXP sorts
storing temporary information for, 160
C
CallBasic, 373
C program example, 376
memory allocation, 379
preventing memory leak, 379, 380
requirements, 373
steps for use, 383
U_callbas function, 374
udtcallbasic function, 374
udtcallbasic_done function, 374
udtcallbasic_init function, 374
UniBasic subroutine example, 381
CALLC
and C, 362
and C++, 360, 366
data types, 358
PASCAL style calling convention, 357
requirements, 355
steps for using CALLC, 355
syntax, 357
CATALOG command, 324
cataloging
direct, 324
global, 325
local, 324
programs, 331
subroutines, 331
UniBasic programs after moving to NT, 26
changed command
DELETE.FILE, 15
changing
block size, 136
Index
file characteristics, 136

hashing algorithm, 136
modulo, 136
name of UniData file, 214
checking
UNIX ipc ID, 107
CHECKOVER command
summarized, 215
checkover command
summarized, 216
checkpoints
forced by dppause command, 144
cleanupd daemon
described, 108
lcp daemon and, 105
log and error log for, 110
sbcs daemon and, 106
smm daemon and, 107
cleanupd log file
entries made at UniData startup, 140
cleanupd.errlog file, 110
cleanupd.log file, 110
CLEAR.ACCOUNT command
described, 163
CLEAR.FILE command
removing records from dynamic file with, 197
security considerations for, 171
summarized, 214
CLEAR.LOCKS command
CLEARDATA command
clearing
_HOLD_ subdirectory, 163
_PH_ subdirectory, 163
hung processes, 149

locks, 270
semaphore lock, 259
space in UniData account, 163
system resources, 148
UniData process, 148
user, 148, 149
CLR command
CNAME command
summarized, 214
command
BUILD.INDEX, 211
convcode, 47
convdata, 47
convidx, 47
CREATE.INDEX, 211
DELETE.INDEX, 211
DISABLE.INDEX, 211
DISABLE.USERSTATS, 407
ENABLE.INDEX, 211
ENABLE.USERSTATS, 407
LIST.USERSTATS, 407
LISTPEQS, 318
LISTPTR, 310, 318
PRINT, 290
PTRDISABLE, 311, 318
PTRENABLE, 311, 318
SETPTR, 290, 304, 318
SETTAPE, 19, 344, 346, 348
SP.ASSIGN, 318
SP.CLOSE, 318
SP.EDIT, 318
SP.KILL, 318
SP.OPEN, 318
SP.STATUS, 311, 318
435
Index
SPOOL, 318
STARTPTR, 311, 318
STOPPTR, 311, 318
T.ATT, 19, 344, 348
T.DET, 344, 351
T.DUMP, 350
T.STATUS, 19, 344, 349
UniBasic tape commands, 345
UniData printing commands, 318
UniData tape commands, 344
UPDATE.INDEX, 211
commands
for clearing users and processes, 148
for file handling, 214
reference for, 160
UniBasic locking, 257
COMO command
captured terminal input/output and, 160
compiling
migration tools on UNIX, 28
computing
control table list (CTL) size, 118
configuration file, 194
configuration parameters
complete list of, 413
GRP_FREE_BLK, 197
KEYDATA_MERGE_LOAD, 194
KEYDATA_SPLIT_LOAD, 194
MAX_FLENGTH, 195
MAX_OBJ_SIZE, 127
NUSERS, 118
SBCS_SHM_SIZE, 106, 127, 326
setting, 132
shared memory, 115, 122
SHM_FREEPCT, 121
436
SHM_GNPAGES, 118, 121

SHM_GNTBLS, 117, 118
SHM_GPAGESZ, 121
SHM_LCINENTS, 118
SHM_LMINRNTS, 118
SHM_LPAGESZ, 120
SHM_LPINENTS, 118
SHM_MAX_SIZE, 326
SHM_NFREES, 121
CONFIGURE.FILE command
summarized, 215
configuring
automatic startup of UniData, 143
printers in UniData, 285
UDSerial service, 86
UDTelnet service, 62
UniData, 130
control information (CI) table, 117
control table list (CTL)
calculating size of, 118
creating in shared memory, 107
described, 116
memory requirements and, 130
controlling
access to ECL/UNIX prompt, 178
UDSerial Service, 100
UDTelnet Service, 78
convcode, 47
convdata, 47
conversion
device name issues, 19
moving UniData migration tools to UNIX, 27
NT steps, 24
printing issues, 21
process overview, 24
UniData migration tools, 26
Index
UNIX steps, 24
using NT_CATALOG_MAP, 41
using NT_RECATALOGGER, 52
using NT_SCOUT, 36
using NT_UPDATE_PATHS, 50
using SQL_UNIX_2_NT, 53
using TAR2FTP, 43
converting
between low-byte and high-byte format, 137
data files, 136
static file to dynamic, 136
convidx, 47, 47
COPY command
counter table (CT), 117
CREATE.FILE command
summarized, 214
CREATE.INDEX, 211
CREATE.INDEX command
creating
alternate global catalog space, 321, 337
dynamic file, 196
local printer in Windows NT, 291
pointer to file, 137
QUERY.PRIVILEGE file, 186
schema, 136
shared memory segment, 119
shared memory structure
for globally cataloged program , 115
for internal table, 115
UniData account, 133, 157
UNIX account, 133
UNIX directory, 157
user profiles in UDTelnet, 69
VOC (vocabulary) file, 157
VOC records, 137

CT (counter table) structures , 117
CTL
See control table list (CTL)
CTLG directory, 161
CTLGTB directory, 328
customizing
default permissions, 165
length of dictionary attribute, 184
VOC file, 159, 170
D
D___V__VIEW file, 161
D__HOLD_ file, 161
D__PH_ file, 161
D__REPORT_ file, 161
D__SCREEN_ file, 161
D_BP file, 161
D_CTLG file, 161
D_MENUFILE file, 161
D_QUERY.PRIVILEGE file
editing, 187
D_SAVEDLISTS file, 161
D_savedlists file, 161
D_VOC file, 161
daemons
cleanupd, 108
log files for, 110
sbcs (shared basic code server), 105
smm (shared memory manager), 107
damaged files
defined, 217
detecting, 220, 229
repairing, 232
damaged groups
repairing, 216, 235
437
Index
unloading contents of, 216

dat001 file, 192
data files
converting, 136
data integrity, 220
DATE.FORMAT command
dbpause command
described, 144
dbpause_status command
described, 146
default files for UniData account, 156
default permissions
assigned at UniData installation , 136
UNIX, 165
defining
peripheral device for UniData, 132
tape units in UniData, 346, 348
DELETE command
removing records from dynamic file with, 197
removing selected files with, 163
DELETE.CATALOG command
DELETE.FILE command
summarized, 214
DELETE.INDEX, 211
DELETE.INDEX command
DELETE.LOCKED.ACTION command
deleteuser command
described, 150
removing user process with, 283
summarized, 148
438
deleting
UniData account, 162
detecting
file corruption, 220, 229
dictionaries
for UniData account files, 161
for VOC file, 133
dictionary attributes
customizing length of, 184
direct cataloging, 324
directories
default permissions for, 165
dynamic file, 195
home, UniData, 134
DISABLE.INDEX, 211
DISABLE.INDEX command
DISABLE.USERSTATS, 407
disk input/output (I/O), 130
disk space use, 190
displaying
globally cataloged program use, 336
ipc facility, 151
list of file and record locks, 260
list of processes waiting for locks, 263
list of semaphore locks, 262
memory use, 123, 125
shared memory configuration parameters, 122
statistics for dynamic file, 215
UniData Dynamic Array Statistics , 398
UniData File I/O Statistics, 399
UniData Index Statistics, 401
UniData Lock Statistics, 403
UniData Program Control Statistics, 405
user and process activity, 281
DLL
CallBasic implementation, 354
Index
CALLC implementation, 354

UniData NT and DLL, 354
dumpgroup
example, 241
dumpgroup command
described, 232
summarized, 216
dynamic files
described, 192
disk space and, 197
estimating required space for, 195
KEYDATA split/merge type, 194
KEYONLY split/merge type, 194
locating directory and part files, 195
merging, 193
messages, 251
modulo table for, 115
overflow block, 192
repairing corruption in, 238
selecting block size for, 197
selecting minimum modulo, 196
selecting split/merge type, 194
splitting, 193
dynamic link library (DLL), 354
E
E type VOC entry, 356, 359
ECL commands
not blocked by dppause, 145
ECLTYPE command
ED command
editing
dictionary for QUERY.PRIVILEGE file, 187
ENABLE.INDEX, 211
ENABLE.INDEX command
ENABLE.USERSTATS, 407
environment variables
setting, 133
UDTBIN, 133
UDTHOME, 133
error messages
from guide command, 246
UniData error logs, 110
estimating
memory requirement, 130
space required for dynamic file , 195
exclusive locks, 256
expression buffers, storing, 107
F
field-level security
customizing security with, 182
turning on, 186
file
ALT.BP.CMDS, 26
ALT.ECL.CMDS, 26
BUILD.FULL.PATH, 27
NT_CATALOG_MAP, 26
NT_UPDATE_PATHS, 27
NTMIGRATE, 26
NTMIGRATE.LOC, 35
RESERVED.CHARS, 26
SQL_UNIX_2_NT, 27
TAR2FTP, 26
UniData.LIB, 354, 383
file access messages, 246
file characteristics, changing, 136
439
Index
file corruption
causes of, 217
detecting, 220, 229
repairing, 232
udt.errlog file and, 110
file locks
displaying list of, 260
setting, 256
FILE.STAT command
summarized, 215
FILELOCK command
summarized, 257
files
_HOLD_ file, 161
_MAP_ file, 328
_PH_ file, 161
_REPORT_ file, 161
changing name of, 214
changing parameters of, 215
checking for level 2 overflow, 215
converting data, 136
corrupted, 217
creating, 214
damaged, 216
default permissions for, 165
deleting, 214
displaying statistics for a hashed file, 215
dynamic, 192
GUIDE_ADVICE.LIS file, 221, 224
GUIDE_BRIEF.LIS file, 224
GUIDE_ERRORS.LIS file, 221, 224
GUIDE_FIXUP.DAT file, 221, 224
GUIDE_INPUT.DAT file, 222
GUIDE_STATS.LIS file, 224
hashed, 160, 190
log, 140
name, reference for, 160
440
over001 file, 192

overflow, 192
primary data, 192
removing record from, 214
repairing damaged group, 216
setting a pointer to UniData file, 214
static, 191
udtconfig file, 194
unloading contents of damaged group, 216
FILEUNLOCK command
summarized, 257
fixfile command
described, 235
repairing dynamic file with, 238
repairing static file with, 237
summarized, 216
fixfile group
fixgroup command
described, 233
summarized, 216
FLOAT.PRECISION command
forcing logoffs, 148
form
creating custom forms in Windows NT, 301
free block messages, 250
freeing
memory in CallBasic, 379, 380
FULLPATH parameter, 184
G
GCT
See global control tables (GCT)
Index
general information (GI) table

defined, 117
size of, 118
GI
See general information (GI) table
global catalog
alternate, 337
contents of, 327
described, 325
managing, 327
global control tables (GCT)
described, 117
process cleanup and, 107
size of, 118
smm daemon and, 107
global pages
determining size and number of, 120
dividing segment into, 115
number to keep free, 121
releasing, 119
globally cataloged programs
loading and tracking, 105
shared memory structure for, 115
GRANT command
customizing permissions with , 181
customizing table access with, 136
group header messages, 247
GROUP.STAT command
summarized, 215
GRP_FREE_BLK parameter, 197
gstt command
described, 123
guide command
creating UniData output file with, 224
described, 220
error messages from, 246
error output from, 243
guidelines for using, 243

output files from, 224
purpose of, 220
summarized, 216
GUIDE_ADVICE.LIS file, 221, 224
GUIDE_BRIEF.LIS file, 221, 224
GUIDE_ERRORS.LIS file, 221, 224
GUIDE_FIXUP.DAT file, 221, 224
GUIDE_INPUT.DAT file, 222
GUIDE_STATS.LIS file, 224
H
hash groups
identifying, 214
hash type
changing for static file, 215
default, 190
HASH.TEST command
hashed files
checking for level 2 overflow, 215
default hash type, 190
dynamic, 192
repairing corruption, 232
static, 191
structure of, 190
in UniData account, 160
hashing algorithms, 190
header key messages, 247
HELP command
_HOLD_ file
clearing, 163
defined, 160
dictionary for, 161
441
Index
home directory
defining for user, 277
UniData, 134
hung processes, clearing, 148
I
I/O
See input/output (I/O)
identifying
damaged file, 216
index, 211, 212, 212
applying updates, 211
creating, 211
removing, 211
index log file, 211, 212, 213
indirect segments, 127
input/output (I/O)
disk, 130
terminal, 160
intermediate results, storing, 115
internal flags, setting, 108
internal tables, shared memory structure for, 115
interprocess communication (ipc)
structure
ipc IDs, checking, 107
ipcstat command
described, 151
summarized, 148
K
kernel parameters
resetting, 131
442
shmmni, 117
KEYDATA split/merge type, 194
KEYDATA_MERGE_LOAD parameter, 194
KEYDATA_SPLIT_LOAD parameter, 194
KEYONLY split/merge type, 194
keyword
LPTR, 290
killing
user process, 150
L
LCT (local control table)
described, 117
level 1 overflow
described, 191
level 2 overflow
checking hashed file for, 215
described, 191
minimizing for dynamic file, 192
line devices, defining for UniData, 132
LINE.ATT command
setting semaphore lock with, 259
LINE.DET command
LIST.INDEX command
LIST.LOCKS command
described, 262
LIST.QUEUE command
described, 263
displaying locks requested, 273
LIST.READU command
described, 260
displaying current locks with, 273
LIST.TRIGGER command
Index

LIST.USERSTATS, 407
listing
ipc structures, 148
locks, 260
LISTPEQS, 318
LISTPTR, 310, 318
LISTUSER command
monitoring user processes, 281
listuser command
displaying process ID with , 150
summarized, 148, 281
load factor for splitting/merging groups, 193
local catalog, 324
local control table (LCT)
described, 117
size of, 118
local pages
determining size and number of, 120
subdividing global page into, 115
local printer
creating, 291
locally cataloged programs
storing, 160
LOCK command
summarized, 259
locking commands, 257
locks
clearing, 270
file
setting with UniBasic command, 256
record
clearing, 271
setting, 256
semaphore
clearing, 274
setting, 259
tracking, 105
log files
described, 140
for UniData daemons, 110
LOGIN paragraphs
defining, 178
logoff, forced, 148
logon scripts
defining, 278
LOGOUT paragraphs
defining, 178
LOGTO command
dbpause and, 145
effect on LOGOUT paragraph, 178
long record messages, 250
LPTR, 290
lstt command
described, 125
L-type locks, 256
M
makeudt command
MAP command
example of, 328
_MAP_ file, 328
MATREADL command
summarized, 257
MATREADU command
summarized, 257
MATWRITE command
summarized, 257
443
Index
MATWRITEU command
summarized, 257
MAX_FLENGTH parameter, 195
MAX_OBJ_SIZE parameter, 127
memory information (MI) table, 117
memory leak, 379, 380
memresize command
summarized, 216
MENUFILE file
dictionary for, 161
menus
definition, storing, 160
MERGE_LOAD parameter, 194
merging groups in dynamic file, 193
merging threshold, 193
message queues
MI (memory information) table, 117
Microsoft Performance Monitor, 388
migration
device name issues, 19
identifying migration issues, 26
moving UniData tools to UNIX, 27
NT steps, 24
PHANTOM, 14
printing issues, 21
process overview, 24
UniData migration tools, 26
UNIX steps, 24
using convcode, 47
using convdata, 47
using convidx, 47
using NT_CATALOG_MAP, 41
using NT_RECATALOGGER, 52
using NT_SCOUT, 36
using NT_UPDATE_PATHS, 50
444
using SQL_UNIX_2_NT, 53
using TAR2FTP, 43
MIN.MEMORY command
mkdir UNIX command
creating directory for UniData account, 133, 157
MODIFY command
modifying
user profiles in UDTelnet, 74
modulo
automatic increase in dynamic file, 192
changing, 215
selecting minimum, 196
table for dynamic file, 107, 115
monitoring
file integrity with guide command, 243
globally cataloged program use , 336
memory, 124
UniData daemons, 109
UniData performance, 396
user processes, 281
Windows NT System, 388
MULTIDIR file, 209
MULTIDIR file type, 137
MULTIFILE, 206
MULTIFILE file type, 137
multilevel directory file, 209
multilevel file, 206
MYSELF command
summarized, 281
N
network print device
printing from UniData, 287
newacct command
Index
creating UniData account with, 133

described, 157
files created by, 156
newhome command
creating UniData account with, 337
NEWPCODE command
described, 334
newversion command, 333
NEWVERSION keyword, 332
NT_CATALOG_MAP, 26
output, 40
purpose, 40
NT_RECATALOGGER, 40
purpose, 52
NT_SCOUT, 26
input files, 34
output, 35
NT_UPDATE_PATHS, 27
purpose, 50
NTMIGRATE, 27
NTMIGRATE.LOC, 35
NUSERS parameter, 118
O
object code, UniBasic, 160
ON.ABORT command
preventing access to ECL/UNIX prompts, 178
OPEN security as system default, 182
other header messages, 248
output
from background process, 160
from guide command, 221, 224
over001 file, 192
overflow
described, 191
dynamic file, 192
files, 192
P
paragraphs
LOGIN, 178
LOGOUT, 178
reference for, 160
partitioning shared memory, 114
PATH environment variable, 140
pausing
UniData, 144
performance
alternate key index use, 401
and UDTelnet, 68
application design considerations , 405
coding technique factors, 390
database design factors, 389
factors for UniData NT, 389
file and record locking impacts, 404
file overflow and, 191
file sizing impact, 389
impact of alternate key indexes, 389
UniData file I/O factors, 400
peripheral devices, defining for UniData , 132
permissions
recommended settings, 167
UniData SQL, 181
UNIX, customizing, 165
_PH_ file
clearing, 163
defined, 160
dictionary for, 161
PHANTOM command
background process and, 160
PI (process information) tables, 117
445
Index
pid
See process ID (pid)
pointers
creating, 137
to data file, 156, 214
setting, 177
stored in VOC file, 133
populating
subdirectory, 160
preventing
file corruption, 218
primary data file, 192
PRINT, 290
print files
storing in _HOLD_ directory, 160
printer
definition in UniData, 289
definition in Windows NT, 287
printers
defining for UniData, 132
printing
creating a custom form, 301
defining a printer in UniData , 304
in UniData NT, 21
redefining the default printer, 311, 317
steps for creating a local printer, 291
submitting concurrent print jobs, 317
to a network print device, 287
UniData printing commands, 318
PRIV parameter of QUERY.PRIVILEGE file, 184
process cleanup
role of lcp daemon in, 105
role of sbcs daemon in, 106
role of smm daemon in, 107
process ID (pid)
stopping process with, 150
process information (PI) tables, 117
446
process monitoring commands, 407

processes
clearing, 148
waiting for lock, 263
program variables, buffering, 107
PTRDISABLE, 311, 318
PTRDISABLE command
PTRENABLE, 311, 318
PTRENABLE command
Q
query privileges, 136
query records, storing, 107
QUERY.PRIVILEGE file
adding record to, 187
creating, 186
described, 183
editing dictionary for, 187
setting permissions for, 187
R
READBCKL command
summarized, 257
READBCKU command
summarized, 257
READFWDL command
summarized, 257
READFWDU command
summarized, 257
READL command
summarized, 258
read-only locks, 256
Index
READU command
summarized, 258
READVL command
summarized, 258
READVU command
summarized, 258
REBUILD.FILE command
summarized, 215
RECORD command
summarized, 214
record locks
clearing, 271
setting, 256
RECORDLOCKL command
summarized, 258
RECORDLOCKU command
summarized, 258
records
adding to QUERY.PRIVILEGE file, 187
deleting from file, 214
identifying group where key is hashed, 214
Recoverable File System (RFS)
checkpoint, 144
RELEASE command
summarized, 258
releasing
file lock, 257
record lock, 257, 271
semaphore lock, 259
shared memory, 115, 119
remote entries, 136
remote items
security for, 174
removing
VOC file entry, 170
repairing
corrupted file, 232

damaged group, 216, 235
dynamic file, 238
static file, 237
RESERVED.CHARS, 26
RESIZE command
summarized, 215
resizing
static file, 215
resource locks, 259
resuming
UniData processing after dbpause , 147
reviewing
backup procedures, 137
UniData security, 136
REVOKE UniData SQL command
customizing permissions with, 181
customizing table access with, 136
rm UNIX command, 163
R-type VOC records
defined, 174
S
SAVEDLISTS file
dictionary for, 161
savedlists file
dictionary for, 161
SAVEDLISTS subdirectory, 160
savedlists subdirectory, 160
sbcs (shared basic code server) daemon
creating shared memory structure, 115, 127
described, 105
global cataloging, 326
memory segment for, 131
447
Index
sbcs.log file, 110

SBCS_SHM_SIZ parameter, 127
SBCS_SHM_SIZE parameter, 106, 326
sbcsprogs command
described, 336
sbsc.errlog file, 110
schemas, creating, 136
SECURE setting as system default, 182
security
and UDSerial, 84
and UDTelnet, 60
checklist, 136
customizing default permissions , 165
remote item, 174
SETFILE command and, 177
UniQuery, 182
segment headers, 117
segments of shared memory
attaching, 105
described, 114
divided into global pages, 115
self-created, 127
select lists
storing, 107
selecting
block size for dynamic file, 197
minimum modulo for dynamic file, 196
split/merge type, 194
startup directory in UDTelnet, 74
semaphore
locks
clearing, 259
setting, 259
tracking, 105
448
semicolon
behavior in Windows NT, 18
sentences
reference for, 160
service
defined, 104
services
described, 105
monitoring, 109
SET.DEC command
SET.MONEY command
SET.THOUS command
SET.WIDEZERO command
SETFILE command
creating VOC entries with, 137
customizing security, 177
summarized, 214
SETLINE command
defining peripheral with, 132
SETOSPRINTER command
SETPTR, 290, 304, 318
modes, 305
options, 306
parameters, 304
spooler options, 307
SETPTR command
SETTAPE, 19, 344, 346, 348
parameters, 347
SETTAPE command
Index
setting
configuration parameter, 132
environment variable
PATH, 133
UDTBIN, 133
UDTHOME, 133
file and record locks, 257
lock on record/file, 256
permission for QUERY.PRIVILEGE file, 187
UNIX kernel parameter, 131
shared basic code server (sbcs) daemon , 105
shared locks, 256
shared memory
CI table, 117
creating CTL segment, 116
loading globally cataloged program into, 105
releasing, 115
sbcs (shared basic code server) daemon and , 127
segment
attaching, 105
self-created segment, 127
structure, 107, 117
table, 107
tuning, 124, 125
UniData and, 115
UNIX system and, 114
shared memory manager
See smm (shared memory manager) daemon
shared memory structures
assigning, 119
SHM_FREEPCT parameter, 121
SHM_GNPAGES parameter, 118, 121
SHM_GNTBLS parameter, 117, 118
SHM_GPAGESZ parameter, 121
SHM_LCINENTS parameter, 118
SHM_LMINRNTS parameter, 118
SHM_LPAGESZ parameter, 120

SHM_LPINENTS parameter, 118
SHM_MAX_SIZE parameter, 326
SHM_NFREES parameter, 121
shmmni UNIX kernel parameter, 117
shutdown operations
normal, 140
smm (shared memory manager) daemon
creating CTL segment, 118
creating shared memory segments, 119
creating shared memory structure, 115
described, 107
managing size of segment, 119
shared memory and, 115
smm.errlog file, 110
smm.log file
showud command and, 110
source code, UniBasic, 160
SP.ASSIGN, 318
SP.ASSIGN command
SP.CLOSE, 318
SP.EDIT, 318
SP.EDIT command
SP.KILL, 318
SP.OPEN, 318
SP.STATUS, 311, 318
SPLIT.LOAD factor, 193
split/merge types
changing for dynamic file, 215
KEYDATA, 194
KEYONLY, 194
selecting, 194
SPLIT_LOAD parameter, 194
449
Index
splitting
groups in dynamic file, 193
splitting threshold, 193
SPOOL, 318
spooler options
setting with SETPTR, 305
spooling
print jobs from Unidata, 290
SQL_UNIX_2_NT, 27
purpose, 53
starting
UniData, 143
STARTPTR, 311, 318
startud command
expected response to, 143
for normal startup, 140
startup directory
selecting at Telnet login time, 74, 76
startup operations, 140
startup, automatic, 143
static files
converting to dynamic, 136
described, 191
repairing corruption in, 237
stopping
UniData
emergency shutdown, 152
normal shutdown, 143
user process, 283
STOPPTR, 311, 318
stopud command
for emergency shutdown, 148
-f option with, 152
for normal shutdown, 140, 143
stopudt command
described, 149
450

removing process ID with, 150
summarized, 148, 283
storing
expression buffer, 107
intermediate results, 115
menu definition, 160
modulo table for dynamic file, 115
output from background process, 160
print file in _HOLD_ subdirectory, 160
query record, 107
select list, 107, 160
temporary information for BY.EXP sort, 160
UniBasic program, 160
UniBasic source and object code, 160
UniData SQL view specification , 160
SUPERCLEAR.LOCKS command
clearing semaphore lock with, 274
described, 270
SUPERRELEASE command
described, 271
releasing record lock with, 273
system performance
file overflow and, 191
system resources, clearing, 148
T
T.ATT, 19, 344, 348
T.ATT command
T.DET, 344, 351
T.DET command
Index
T.DUMP, 350
T.DUMP command
T.STATUS, 19, 344, 349
tape device
handling in Windows NT, 19
tape devices, defining for UniData , 132
tape use procedure, 348
TAR2FTP, 26
output, 42
purpose, 42
TERM command
terminal device, 19
definition in UniData NT, 19
terminal emulation
and UDTelnet, 61
terminated process cleanup
role of cleanupd daemon in, 108
role of lcp daemon in, 105
role of sbcs daemon in, 106
role of smm daemon in, 107
threshold, splitting, 193
TIMEOUT command
described, 284
/tmp directory, 130
troubleshooting
printers, 286
tuning
memory, 124, 125
UDTelnet parameters, 68
U
U_callbas, 374
memory allocation, 379
U_IGNLGN_LGTO option
effect on root access, 180

U_VERIFY_VKEY option
customizing UniData environment with, 172
UDSerial
and UDTelnet, 83
auto connection, 97
logon script, 96
port configuration, 89
requirements, 82
security, 84
terminal emulation, 84
udt daemon
error log for, 110
udt user processes, 105
udt.errlog file, 110
UDT.OPTIONS
setting in login paragraph, 178
UDT.OPTIONS 19
customizing UniData environment with, 172
UDT.OPTIONS 20
effect on root access, 180
UDT.OPTIONS 88, U_CALLC_CDECL, 356
UDT.OPTIONS command
UDTBIN environment variable, 133, 140
udtcallbasic, 374
allocating memory, 380
udtcallbasic_init, 374
udtconfig file, 194
location of, 132
reading when UniData started, 115
UDTelnet, 57
console options, 66
features, 60
requirements, 58
selecting a startup directory, 74
service options, 64
451
Index
user profiles, 69
udtermcap
and UDSerial, 84
udtermcap file
and UDTelnet, 61
UDTHOME environment variable
modifying, 341
setting, 133, 140
UniBasic
BP file and, 323
cataloging programs, 321
coding tips for performance, 390
compiled programs, 322
locks, tracking, 105
profiling, 392
program
shared memory structure for, 115
stored in BP file, 161
storing code in BP subdirectory , 160
storing in CTLG subdirectory, 160
setting lock on file or record, 256
source code, 322
variable
buffering, 115
UniData
account
clearing space in, 163
creating, 157
deleting, 162
described, 156
files in, 160
clearing process, 148
configuration file, 194
customizing default permissions , 165
master VOC (vocabulary) file, 171
pausing, 144
starting, 143
452
stopping, 143
system resources, clearing, 148
UniData accounts
backing up, 137
locating, 130
UniData configuration parameters
GRP_FREE_BLK, 197
KEYDATA_MERGE_LOAD, 194
KEYDATA_SPLIT_LOAD, 194
MAX_FLENGTH, 195
MAX_OBJ_SIZE, 127
NUSERS, 118
SBCS_SHM_SIZE, 106, 127, 326
SHM_FREEPCT, 121
SHM_GNPAGES, 118, 121
SHM_GNTBLS, 117, 118
SHM_GPAGESZ, 121
SHM_LCINENTS, 118
SHM_LMINENTS, 118
SHM_LPAGESZ, 120
SHM_LPINENTS, 118
SHM_MAX_SIZE, 326
SHM_NFREES, 121
UniData NT
and tape devices, 343
printing implementation, 290
UniData security
customizing VOC file, 170
recommended UNIX permissions, 168
remote items, 174
removing VOC entry, 170
SETFILE command, 177
UDT.OPTIONS 19 and, 172
UDT.OPTIONS 20 and, 180
UniData SQL
Index
permissions, 181
storing view specifications, 160
UniData Terminal Server (UDSerial), 82
UniData.LIB, 354, 383
UniQuery
field-level security, 182
UNIX accounts
creating, 133
UNIX kernel parameters
resetting, 131
shmmni, 117
UNIX_NT_CATASTROPHIC, 35
UNIX_NT_SUMMARY, 35
UNIX_NT_WARNING, 35
unloading
contents of damaged group, 216
UNLOCK command
summarized, 259
UPDATE.INDEX, 211
UPDATE.INDEX command
updatevoc command
updating
path names in Windows NT, 27
user processes (udt), 105
user profile
generated by UDTelnet, 75
USERNAME parameter of QUERY.PRIVILEGE
file, 184
users
adding, 133
clearing, 148, 149
U-type locks, 256
V
__V__VIEW file
VCATALOG command
verify2 command
described, 228
error messages from, 246
purpose of, 220
summarized, 216
verifying
UniBasic program version, 329
view specifications
for UniData SQL, 160
virtual memory pool, 116
VOC (vocabulary) file
component of UniData account, 156, 160
creating, 157
customizing, 159, 170
dictionary for, 161
limiting access to commands, 136
master, 171
removing entry from, 170
R-type record, 174
UniData account and, 133
VOC file
CALLC requirements, 356
E type entry, 356
W
WHAT command
WHERE command
displaying currrent account with, 163
WHO command
453
Index
summarized, 281
Windows NT account
defined, 156
WRITE command
summarized, 258
WRITEU command
summarized, 258
WRITEV command
summarized, 258
WRITEVU command
summarized, 258
454

Admn PDF

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Admn PDF

Caricato da

Copyright:

Formati disponibili

UniData

ii Administering UniData on Windows NT or Windows 2000

Chapter 1 - Introduction to UniData for Windows NT or

Chapter 2 - Migrating Applications to UniData for Windows NT

Administering UniData on Windows NT or Windows 2000

Chapter 3 - Managing and Using the UDTelnet Service .............57

Chapter 4 - Managing and Using the UDSerial Service ..............81

Chapter 5 - UniData and Services...............................................103

Chapter 6 - UniData and Memory................................................ 113

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

Chapter 8 - Starting, Stopping, and Pausing UniData ..............139

Administering UniData on Windows NT or Windows 2000

Chapter 9 - Managing UniData Accounts...................................155

Chapter 10 - Managing UniData Security...................................165

Chapter 11 - Managing UniData Files .........................................189

Administering UniData on Windows NT or Windows 2000

Detection and Repair Examples ..............................................................240

Chapter 12 - Managing UniData Locks.......................................253

Chapter 13 - Managing UniData Users .......................................275

Chapter 14 - Managing Printers in UniData ...............................285

Chapter 15 - Managing Cataloged Programs ............................321

Administering UniData on Windows NT or Windows 2000

Listing Programs in Use .........................................................................336

Chapter 16 - Managing and Using Tape Devices ......................343

Chapter 17 - CALLC and CallBasic ............................................353

Chapter 18 - Monitoring and Tuning UniData ............................387

Appendix A - UniData Configuration Parameters .....................413

Administering UniData on Windows NT or Windows 2000

Administering UniData on Windows NT or Windows 2000

Administering UniData on Windows NT or Windows 2000

Chapter 1 - Introduction to UniData for Windows NT or Windows 2000

Tasks performed at the operating system level

Modifying file permissions

Starting and stopping UniData

Backing up UniData files

Tasks performed within UniData

Creating and managing UniData accounts

Optimizing UniData configuration

Monitoring and accessing files, peripherals, and system resources

Administering UniData on Windows NT or Windows 2000

Recoverable File System (RFS)

Transaction Processing (TP)

(double quotation mark)

Administering UniData on Windows NT or Windows 2000

Chapter 1 - Introduction to UniData for Windows NT or Windows 2000

< (less than sign)

> (greater than sign)

Administering UniData on Windows NT or Windows 2000

Index Files and Index Log Files

Administering UniData on Windows NT or Windows 2000

Chapter 1 - Introduction to UniData for Windows NT or Windows 2000

Administering UniData on Windows NT or Windows 2000

Administering UniData on Windows NT or Windows 2000

Chapter 1 - Introduction to UniData for Windows NT or Windows 2000

Shell Command Differences

Administering UniData on Windows NT or Windows 2000

Administering UniData on Windows NT or Windows 2000

Chapter 1 - Introduction to UniData for Windows NT or Windows 2000

Administering UniData on Windows NT or Windows 2000

Notes About Terminal Devices and Tape Drives

Notes About Terminal Devices and Tape Drives

Administering UniData on Windows NT or Windows 2000

Chapter 1 - Introduction to UniData for Windows NT or Windows 2000