Professional Documents
Culture Documents
Admn PDF
Admn PDF
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.
Contents
SQL_UNIX_2_NT ....................................................................................53
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.
Audience
Administering UniData is intended for people whose responsibilities include the following:
10
Adding users
Creating directories
Customizing security
Managing files
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
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:
11
| (pipe sign)
* (asterisk)
/ (slash)
: (colon)
? (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.
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.
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
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
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
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 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
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
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
ALT.ECL.CMDS
ALT.BP.CMDS
RESERVED.CHARS
TAR2FTP
NT_CATALOG_MAP
26
Tool
Description
NT_UPDATE_PATHS
BUILD.FULL.PATH
SQL_UNIX_2_NT
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.
Screen Example
:SETFILE /usr/ud52/demo/NTMIGRATE NTMIGRATE
Establish the file pointer
Tree name
/usr/ud52/demo/NTMIGRATE
Voc name
NTMIGRATE
Dictionary name
/usr/ud52/demo/D_NTMIGRATE
Ok to establish pointer(Y/N) = Y
SETFILE completed.
:CT VOC NTMIGRATE
VOC:
NTMIGRATE:
DIR
/usr/ud52/demo/NTMIGRATE
/usr/ud52/demo/D_NTMIGRATE
:
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
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
...
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.
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
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
privilege................. access.. field..... grant_op grantor... grantee...
&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:
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.
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.
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
UNIX_NT_WARNING
UNIX_NT_SUMMARY
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.
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
CATASTROPHIC
NT_SCOUT
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
Screen Example
% more UNIX_NT_CATASTROPHIC
Info
-- The following LOCAL program files won't be checked
/PRODUCT_INFO/TERRIC/ACCOUNT/TESTPROGS
CATASTROPHIC
CATASTROPHIC
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.
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.
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
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.
1 records selected to list 0.
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
Placeholders (lines beginning with #) where you will add your UNIX login ID and
password
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.
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
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
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
See the UniData Commands Reference for information about these three commands.
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
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.
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
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'
compilation finished
Compiling Unibasic: BP\BASIC_STATIC in mode 'u'.
compilation finished
Compiling Unibasic: BP\TIMETEST1 in mode 'u'.
compilation finished
Compiling Unibasic: BP\TIMETEST2 in mode 'u'.
compilation finished
Now cataloging file BP
:
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
Screen Example
:SORT privilege ALL
SORT privilege ALL 12:51:47 Jun 15 1999 1
privilege................. access.. field..... grant_op grantor... grantee...
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
privilege................. access.. field..... grant_op grantor... grantee...
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
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.
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.
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.
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.
Overview of Features
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:
WYSE60
ADDS-VP
IN 9400
IN 9400B
You can add terminal definitions to udtermcap, or modify the definitions, if you desire.
Warning
Users cannot log in via the Serial Terminal service (UDSerial) unless UDTelnet is installed and
running.
61
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
Console
Users
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:
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.
Note
To review the information you capture, from the Start menu, select Programs, then
Administrative Tools, and then click Event Viewer.
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
67
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:
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
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
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.
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.
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
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.
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.
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
Chapter 4 - Managing
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
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
Overview of Features
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:
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
Overview of Features
85
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.
Note
To review the information you capture, from the Start menu, select Programs, then
Administrative Tools, and then click Event Viewer.
88
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.
91
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.
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:
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
The following example illustrates the Modem Options box using the initialization commands
above:
95
Logon Script
If you select the Logon Script tab, a dialog box similar to the following example appears:
Enter Delay
Enter the delay, in milliseconds, between each line of the login script in the Delay box.
96
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:
98
Description
None
CTS
DSR
Carrier
Always
99
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.
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
This chapter explains what services are, and describes services specific to UniData.
103
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
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.
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.
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
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.
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
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
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
udtno=1,pid=937,uid=1172,cwd=/home/claireg,Jun 12 12:44:46
110
111
112
This chapter describes how to configure, attach, and release shared memory.
113
114
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:
115
CTL
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
Description
GI
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.
PI (process
information) table
CT (counter table)
MI (memory
information) table
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
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
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.
119
Memory
virtual memory pool
CTL
shared
memory
pool
shared memory segment
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
SHM_GNPAGES
Description
SHM_FREEPCT
SHM_NFREES
121
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
NUSERS
SHM_LPINENTS
SHM_LMINENTS
SHM_LCINENTS
SHM_LPAGESZ
=
=
=
=
=
128
10
32
100
8
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
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)
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
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
2 (20% of 10)
2 (6% of 32)
2 (256K bytes)
0 (0K bytes)
256K bytes
Reminder
See the UniData Commands Reference for additional information about the parameters of the lstt
syntax.
126
Description
SBCS_SHM_SIZE
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.
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
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.
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:
UniData accountsIf your application uses more than one UniData account, locate
the account directories on separate drives to distribute load.
130
Configuration Procedure
See Chapter 6 - UniData and Memory, for information about estimating memory needs.
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.
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.
132
Configuration Procedure
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.
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.
134
Configuration Procedure
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.
135
Note
While you are in a UniData session, you cannot change environment variables for that session.
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.
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.
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
Configuration Procedure
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.
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
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.
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
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)
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
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.
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.
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:
BLOCK.PRINT, BLOCK.TERM
COMO
CONFIGURE.FILE, HASH.TEST
LIST.TRIGGER
DATE.FORMAT
BLIST, VCATALOG
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
145
TERM
WHAT
The following example illustrates the output from the dbpause command:
Screen Example
C:\UniData52\bin>dbpause
DBpause successful.
#
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
stopudt
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
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
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
udt
pts/1
Console
udt
pts/2
Console
C:\UniData52\Bin>stopudt 324
C:\UniData52\Bin>listuser
Licensed/Effective # of Users
16 / 16
UDTNO USRNBR
2
UID
USRNAME
USRTYPE
udt
Udt
Sql
Total
TTY
IP-ADDRESS
TIME
pts/2
Console
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.
Warning
Because deleteuser may execute the Terminate Process, it is particularly important that you verify
the pid carefully.
150
Additional Commands
Screen Example
% listuser
Licensed/Effective # of Users
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
Licensed/Effective # of Users
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.
151
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.
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
Chapter 9 - Managing
UniData Accounts
This chapter describes UniData accounts and describes procedures used to create, save, and clear
the accounts.
155
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
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:
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
CTLG
SAVEDLISTS
SAVEDLISTSL
_HOLD_
_PH_
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
VOC
__V__VIEW
privilege
160
File
Description
D_BP
D_CTLG
D_MENUFILE
D_SAVEDLISTS
D_VOC
D__HOLD_
D__PH_
D__REPORT_
D__SCREEN_
D___V__VIEW
D_SAVEDLISTSL
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
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
Chapter 10 - Managing
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
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
Customizing Permissions
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
udthome\sys\DICT.DICT
udthome\sys\VOC
167
Directory or File
Guidance
udthome\sys\CTLG
udthome\demo
udthome\sys\AE_BP
All users with access to AE (the line editor) need read and
write permissions.
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
Customizing Permissions
Directory or
File
Guidance
SAVEDLISTS
_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
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
CNAME
Changes a filename.
COPY
Copys records.
CREATE.FILE
Creates files.
CREATE.INDEX
DELETE
DELETE.CATALOG
DELETE.FILE
Deletes a file.
DELETE.INDEX
DISABLE.INDEX
ED
ENABLE.INDEX
MODIFY
PTRDISABLE
PTRENABLE
RESIZE
Resizes a file.
UPDATE.INDEX
Note
You can remove entries from the UniData master VOC file (located in udthome\sys) or from the
VOC files in one or more UniData accounts. The master VOC is installed as part 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
Administrators can execute
command
Others can execute command
ON
No VOC entry
OFF
No VOC entry
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
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
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
Screen Example
:SETFILE \USERS\SECURE\INVENTORY INVENTORY
Establish the file pointer
Tree name
\USERS\SECURE\INVENTORY
Voc name
INVENTORY
Dictionary name
\USERS\SECURE\D_INVENTORY
Ok to establish pointer(Y/N) = Y
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
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
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
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
182
ECL commands, such as CREATE.FILE, DELETE.FILE, and CNAME, do not update the
QUERY.PRIVILEGE table.
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.
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
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
FULLPATH
Virtual attribute formula that designates the full path of the file
affected by PRIV. This formula has the format
FIELD(@ID,*,2).
USERNAME
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
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
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:
185
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
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.
187
188
Chapter 11 - Managing
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
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
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
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
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.
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).
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).
194
MAX_FLENGTH
If (minimum modulo * block size) is larger than MAX_FLENGTH, the new file needs more than
one data part file.
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
Volume in drive C has no label.
Volume Serial Number is E476-B561
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.
196
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
Volume in drive C has no label.
Volume Serial Number is E476-B561
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\*
Volume in drive C has no label.
Volume Serial Number is E476-B561
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:05p
02:05p
4 File(s)
.
..
24,576 dat001
12,288 over001
36,864 bytes
Screen Example
:FILE.STAT SIZE.TEST
File name(Dynamic File)
= SIZE.TEST
Number of groups in file (modulo)
= 12
Dynamic hashing, hash type
= 0
Split/Merge type
= KEYONLY
Block size
= 2048
File has 3 groups in level one overflow.
Number of records
= 489
Total number of bytes
= 12590
Average number of records per group
Standard deviation from average
= 44.5
= 13.2
199
= 1144.5
= 459.4
=
=
=
=
=
in a record
in record ID
average
in a record
in a record
25.7
7.9
35.5
6
379
= 1
= 10
= 2.2
= 0.7
200
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
.
.
.
:FILE.STAT SIZE.TEST
File name(Dynamic File)
=
Number of groups in file (modulo)
=
Dynamic hashing, hash type
=
Split/Merge type
=
Block size
=
Number of records
=
Total number of bytes
=
.
.
.
File has 1 over files, 1 prime files
.
.
.
::!DIR SIZE.TEST
Volume in drive C has no label.
Volume Serial Number is E476-B561
list?(Y/N)Y
SIZE.TEST
10
0
KEYONLY
2048
0
0
Directory of C:\Informix\ud52\claireg\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
201
4 File(s)
47,104 bytes
2,841,068,032 bytes free
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.
Screen Example
:CLEAR.FILE SIZE.TEST
SIZE.TEST is cleared.
:FILE.STAT SIZE.TEST
File name(Dynamic File)
Number of groups in file (modulo)
Dynamic hashing, hash type
Split/Merge type
Block size
Number of records
Total number of bytes
=
=
=
=
=
=
=
SIZE.TEST
3
0
KEYONLY
2048
0
0
=
=
=
=
0.0
0.0
0.0
0.0
= 0.0
= 0
= 0
= 0
= 0
= 0.0
in a record
in a record
per record
prime files
:!DIR SIZE.TEST
202
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
204
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.
206
DIR-Type Files
Screen Example
:CT VOC MULTI1
VOC:
MULTI1:
LF
MULTI1
D_MULTI1
:!DIR MULTI1\*
Volume in drive D has no label.
Volume Serial Number is 4CD1-467F
Directory of D:\UniData\ACCOUNT\MULTI1
11/11/98
11/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.
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
Screen Example
:CT VOC MULTID
VOC:
MULTID:
LD
MULTID
D_MULTID
:!DIR MULTID\*
Volume in drive D has no label.
Volume Serial Number is 4CD1-467F
Directory of D:\UniData\ACCOUNT\MULTID
11/11/98
11/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
796,556,800 bytes free
Note
If a subdirectory of a multilevel directory file has the same name as the main directory, you can use
the main directory name to access the subdirectory. For instance, LIST MULTID is correct syntax
if the directory MULTID contains subdirectory MULTID.
209
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.
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.
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.
Screen Example
:!DIR/D
Volume in drive D has no label.
Volume Serial Number is 4CD1-467F
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
796,475,904 bytes free
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.
Screen Example
:!DIR ORDERS\*
Volume in drive D has no label.
Volume Serial Number is 4CD1-467F
Directory of D:\UniData\demo\ORDERS
11/11/98
11/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
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
RECORD
214
File-Handling Commands
Command
Description
FILE.STAT
GROUP.STAT
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
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
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
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
verify2
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.
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
Risk Factor
deleteuser
stopud -f
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
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.
Includes minimum statistics about the file. Does not work with the -ns
option.
-d2 | -D2
-d3 | -D3
-e | -E [filename]
-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
-h1 | -H1
-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]
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)
-s | -S count
If you specify the -d3 option, the guide utility displays the keys for the
smallest records. UniData displays the key in quotes. If the key is
truncated, it is followed by an asterisk (*). The -s count option controls
the number of records to appear in sorted order. The default value is three.
Large values result in a significantly slower analysis.
-s | -S [filename]
-ns | -NS
(no statistics)
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
GUIDE_ERRORS.LIS
GUIDE_STATS.LIS
GUIDE_BRIEF.LIS
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.
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
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
filename
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...
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
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
F-type
V-type
Value code for the attribute. S for singlevalues, M for multivalued or multisubvalued.
K-type
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:
The following table describes each parameter of the syntax.
Parameter
Description
[-Y | -y]
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 -------------------->
Number of groups checked: 3
file is in good status.
ORDERS
104448 (102 blocks)
101
0
1024
DYN.TEST
1
1
3
3
0
1024
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).
Number of groups checked: 101
1 key(s) are damaged.
file has something damaged.
230
231
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
The following table describes each parameter of the syntax.
Parameter
Description
filename
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]
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
Description
filename
group.no
[-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
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.
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
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
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
:
Screen Example
:!FIXFILE -DOUTFILE -F
**** Record Key='10037', Record length=126
**** Record Key='9983', Record length=98
**** Record Key='10018', Record length=94
**** Record Key='10094', Record length=105
**** Record Key='10075', Record length=103
**** Record Key='10056', Record length=111
.
.
.
**** Record Key='SELECT.ONLY', Record length=14
Record key
: 10037
Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10037a
Record key
: 9983
Corresponding file : D:\UniData\demo\CLIENTS_dir\3\9983a
Record key
: 10018
Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10018a
Record key
: 10094
Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10094a
Record key
: 10075
Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10075a
Record key
: 10056
Corresponding file : D:\UniData\demo\CLIENTS_dir\3\10056a
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
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.
No Errors
If there are no errors, proceed to step 5.
243
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
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.
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.
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.
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.
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
Screen Example
Group xx, block xx key area is corrupted,
keys xx
Group xx, block xx key area is corrupted,
Group xx, block xx key area is corrupted,
size xx number of keys xx
Group xx, block xx key area is corrupted,
247
These errors indicate that key area size or number of keys have been corrupted in a group header.
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
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.
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).
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.
Screen Example
Overflow file number too large
Primary file number too large
Screen Example
The next_block(xx) in overflow file header error
The next_block(xx) in free block (xx) is over filesize.
251
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)
Screen Example
level 2 overflow: file no in nextover (xx) error
opfile (xx) in group header(yy) error.
252
Chapter 12 - Managing
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
254
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.
256
Locking in UniBasic
Locking Commands
The following table lists UniBasic commands for setting and releasing locks.
Command
Description
FILELOCK
FILEUNLOCK
MATREADL
MATREADU
MATWRITE
MATWRITEU
READBCKL
Retrieves one record from a B+ tree based alternate key index and
places a read-only lock on the record. Each subsequent READBCKU
retrieves the previous record in the index.
READBCKU
Retrieves one record from a B+ tree based alternate key index and
places an exclusive lock on the record. Each subsequent READBCKU
retrieves the previous record in the index.
READFWDL
Retrieves one record from a B+ tree based alternate key index and
places a read-only lock on the record. Each subsequent READBCKU
retrieves the next record in the index.
READFWDU
Retrieves one record from a B+ tree based alternate key index and
places an exclusive lock on the record. Each subsequent READBCKU
retrieves the next record in the index.
UniBasic Commands for Locking Files and Records
257
Command
Description
READL
READU
READVL
READVU
RECORDLOCKL
RECORDLOCKU
RELEASE
WRITE
WRITEU
WRITEV
WRITEVU
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
LOCK
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
The following table describes each parameter of the syntax.
Parameter
Description
user_number
ALL
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
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
196 1049668 claireg Console
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
196 1049668 claireg Console
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
UID
UNAME
TTY
FILENAME
RECORD_ID
TIME
DATE
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
The following table describes each parameter of the syntax.
Parameter
Description
USERNAME user_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
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
RECORD_ID
OWNER
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
TIME
DATE
The next table describes the LIST.QUEUE display for the processes waiting for locks.
Column
Heading
Description
FILENAME
RECORD_ID
WAITING
UNBR
266
Listing Locks
Column
Heading
Description
UNO
TTY
TIME
DATE
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
RECORD_ID
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
UNBR
UNO
TTY
TIME
DATE
The following table describes the waiting information the LIST.QUEUE command displays then
you specify the DETAIL option.
Column
Heading
Description
FILENAME
RECORD_ID
INBRH
The high integer of the inode of the file holding the lock.
INBR
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
UNBR
UNO
TTY
TIME
DATE
269
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.
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]
The following table describes each parameter of the syntax.
Parameter
usrnbr
Description
The process ID (pid) that holds the lock. This number is
UNBR in the LIST.LOCKS display.
SUPERCLEAR.LOCKS Parameters
270
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
Screen Example
:LIST.LOCKS
UNO
UNBR UID UNAME
TTY FILENAME
1 15454 1172ump01 tyv1 semaphor
3 15692 1172ump01 tyv4 semaphor
:
:SUPERCLEAR.LOCKS 15692 -1
:LIST.LOCKS
UNO
UNBR UID UNAME
TTY FILENAME
1 15454 1172ump01 tyv1 semaphor
:
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
Description
usrnbr
[inbr devnum]
[record.id]
Note
If you execute SUPERRELEASE and specify only usrnbr, you release all record locks held by the
process ID corresponding to usrnbr.
The following example shows the effect of SUPERRELEASE:
Screen Example
:LIST.READU
UNO UNBR
UID
UNAME
TTY
1
376 1049668 claireg Console
2
394 1049668 claireg Console
:SUPERRELEASE 376
:LIST.READULIST.READU
UNO UNBR
UID
UNAME
TTY
2
394 1049668 claireg Console
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
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.
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
274
Chapter 13 - Managing
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
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
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
LISTUSER
listuser
MYSELF
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
:LISTUSER
Licensed/Effective # of Users
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
udt
pts/2
Console
udt
pts/3
Console
C:\UniData52\claireg>listuser
Licensed/Effective # of Users
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
udt
pts/2
Console
udt
pts/3
Console
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
Description
stopudt
deleteuser
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
Chapter 14 - Managing
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
Physical Configuration
Configure a print device as follows:
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 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.
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:
SPOOL commands
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
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).
290
291
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:
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:
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:
Reminder
Make sure the description reads Local Port.
294
Follow the instructions on the screen. Click Next when you have selected the manufacturer and
printer. A window similar the following appears:
295
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
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
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.
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
Scheduling
Sharing
Security
Device Settings
Note
Use caution modifying device settings. You can enter settings for a local printer that are
inconsistent with the underlying print device.
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.
301
Tip
To minimize editing, pick an existing form whose characteristics are similar to the new form you
are creating.
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:
303
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]
[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]
[options]
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
305
Description
BANNER [string]
BANNER UNIQUE
[string]
BRIEF
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.
DEVICE name
EJECT
NOEJECT
LNUM
NFMT or NOFMT
NHEAD or NOHEAD
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
PaperSource
Default paper source; must match an available paper source listed on the
Device Settings tab of the printers Properties Sheet.
Duplex
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
Prefix
Font
FontSize
307
Option
FontStyle
Description
Must be Regular, Italic, Bold, Underline, or StrikeOut. Default is Regular.
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.
LeftMargin
RightMargin
TopMargin
BottomMargin
Priority
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
OK to set parameters as displayed?(enter y/n) y
: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
OK to set parameters as displayed?(enter y/n) y
:
The default print device (printer unit 0) is now mapped to the local printer LETTER. If
you use the PRINT command or LPTR with no print unit specified, UniData directs your
print job to LETTER.
Use SETPTR unit to display the current settings for a print unit.
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
Screen Example
:SETPTR 0,,,,,3
Unit
0
Mode
3
Options are:
OK to set parameters as displayed?(enter y/n) Y
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
?
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
OK to set parameters as displayed?(enter y/n) Y
: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
OK to set parameters as displayed?(enter y/n) Y
: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
OK to set parameters as displayed?(enter y/n) Y
Invalid combination of spooler options 'Mode=RAW,Font=COURIER'
:
316
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
Description
SETPTR
SPOOL
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
SP.CLOSE
SP.ASSIGN
Sets characteristics of the default UniData print device, printer unit 0 (Pick
compatible syntax).
SP.EDIT
SP.KILL
Cancels a job.
SP.OPEN
SP.STATUS
LISTPTR
Displays the names of printers and the paths of devices associated with them.
LISTPEQS
318
Note
See the UniData Commands Reference for the syntax of these ECL commands.
319
320
Chapter 15 - Managing
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
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.
Reminder
See the UniData Commands Reference and Developing UniBasic Applications for information
about the BASIC command.
322
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
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.
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.
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).
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
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
31 @UDTHOME/SYS_BP SCHEMA
_LIST_USERS
71 @UDTHOME/SYS_BP SCHEMA
_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
.
.
.
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
root
root
root
root
root
92 06/03/99 06/08/99
root
root
root
root
SCHEMA_REMOVE_SC S
.
.
.
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.
Description
Name of the file containing the program (BP, for
instance).
VCATALOG Parameters
329
Parameter
Description
catalog.name
program.name
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'.
compilation finished
: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.
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
:
Description
path
userno...
Screen Example
:LISTUSER
Licensed/Effective # of Users
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
udt
pts/2
Console
udt
pts/3
Console
: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
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
Screen Example
C:\UniData52\sys>dir
Volume in drive C has no label.
Volume Serial Number is E476-B561
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
D_CTLGTB
CTLGTB
D_CTLG
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.
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.
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
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.
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
Chapter 16 - Managing
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
Description
SETTAPE
T.ATT
T.BAK
T.CHK
T.DET
T.DUMP
T.EOD
T.FWD
T.LOAD
T.RDLBL
T.READ
T.REW
T.SPACE
T.STATUS
T.UNLOAD
T.WEOF
344
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
RESIZET
REWIND
WEOF
WRITET
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
[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]
347
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.
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
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.
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
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.
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.
351
352
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
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
Note
When you use CALLC, your functions are executed by a udt process. They are not visible to the
end user at all.
Tip
Refer to your host operating system documentation and your hardware vendor if you have
questions about your development environment.
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.
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.
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 executes.
ON
CALLC executes
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.
357
Description
rtn
function
arg1,....argn
Valid data types for return values and arguments are listed in the following table.
Data Type
Description
CHAR
Signed byte.
INT
POINTER
SHORT
LONG
Long integer.
STRING
CHAR_PTR
INT_PTR
SHORT_PTR
LONG_PTR
DOUBLE
Double.
DOUBLE_PTR
Pointer to a double.
Data Types for CALLC
358
Data Type
Description
BSTRING
NONE
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
Attribute 2
Attribute 3
Attribute 4
Attribute 5
Attributes 6 - n
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
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.
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
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.
Notice the following points:
The EXPORTS statement is used to export the three functions that can be called from the
DLL.
The names of the functions you can call do not need to match the names of the source
files, provided they are correctly defined.
The UniBasic program EXAMPLE_CPP calls one of the three functions from callcpp_test.dll. A
segment of this program is shown in the next example:
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
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:
*
*/
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.
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
THE FIRST NUMBER IS: 4527 AND THE SECOND NUMBER IS: 4473
THE BIGGER ONE IS:4527
THE FIRST NUMBER IS: 4054 AND THE SECOND NUMBER IS: 4946
THE BIGGER ONE IS:4946
THE FIRST NUMBER IS: 3581 AND THE SECOND NUMBER IS: 5419
THE BIGGER ONE IS:5419
THE FIRST NUMBER IS: 3108 AND THE SECOND NUMBER IS: 5892
THE BIGGER ONE IS:5892
THE FIRST NUMBER IS: 2635 AND THE SECOND NUMBER IS: 6365
THE BIGGER ONE IS:6365
:
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.
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.
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){
printf("Return value from UniBasic subroutine is %s\n", rtn);
}
377
/* Free memory */
free(rtn);
#endif /* NT */
}
/* Close everything properly */
udtcallbasic_done(sts);
}
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);
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.
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.
Program Example
/* Allocate memory for return variable */
rtn = (char *)malloc(256);
printf("\nExecuting UniBasic subroutine using udtcallbasic()...\n");
/* Call the UniBasic subroutine using udtcallbasic. */
sts = udtcallbasic(rtn, "EXAMPLE", 2, args[0], args[1]);
if (sts == 0){
printf("Return value from UniBasic subroutine is %s\n", rtn);
}
/* Free memory */
free(rtn);
When you use the udtcallbasic function, your calling process is responsible for allocating and
freeing the memory for the return variables. If your process fails to free the memory, your
application is said to have a memory leak, which can cause significant performance degradation
over time.
Freeing Memory
When your process allocates the memory for the return variable, you can use free( ) to free it.
Notice that the program segment illustrates this technique as well:
Program Example
/* 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){
380
Sample Programs
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.
Program Example
SUBROUTINE EXAMPLE(RETNVAL,ARG1,ARG2)
PRINT "THE FIRST ARG IS ":ARG1
PRINT "THE SECOND ARG IS ":ARG2
RETNVAL="RETURN"
RETURN
END
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);
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
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.
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.
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'.
compilation finished
In D:\UniData\sys\CTLG\a\AE at line 995 EXAMPLE has been cataloged, do you want\
384
to overwrite(y/n)? Y
:
Note
Before proceeding further, be sure that both your C program and your UniBasic subroutine are
thoroughly tested.
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
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
Locate the most frequently accessed attributes near the beginning of a record.
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.
389
390
Use CASE statements instead of IF, THEN, ELSE structure whenever possible. Avoid
nested IF, THEN, ELSE.
Use GOSUB instead of external CALLs when appropriate; use CALL when multiple
programs access the same code.
Use A += B instead of A = A + B.
Use LOOP and REMOVE when extracting data sequentially from a string.
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 READ when you are accessing small records, and the data you want is near the
beginning of each record.
You are handling records with a large number of attributes, and you want to access
more than one attribute.
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.
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
cumsecs
seconds
calls
name
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
%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
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
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
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
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
DELETE
EXTRACT
FIELD
FIND
INDEX
INSERT
LOCATE
398
Field
Description
MATCHFIELD
MATPARSE
REMOVE
REPLACE
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
File Close
Level 1 Overflow
Level 2 Overflow
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.
400
Field
Description
Record Delete
Record Read
Record Write
TempFile Close
Tip
You can scroll through the list of Counters to see all values.
401
The following table describes the Counters you can monitor for UniData Index Statistics, and
presents some tuning recommendations.
Field
Description
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.
Number of times two nodes merge; this takes place when entries in one
or both nodes decrease.
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 Overflow
Read
402
Field
Index Overflow
Write
Description
Number of times UniData writes an overflow node.
Tip
You can scroll through the list of Counters to see all values.
403
The following table describes the Counters you can monitor for UniData Lock Statistics, and
indicates performance considerations.
Field
Display
Lock Failure
Record Lock
Record Unlock
Semaphore Lock
Semaphore Unlock
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.
Tip
You can scroll through the list of Counters to see all values.
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
EXECUTE Call
Global Call
GOSUB Call
Local Call
LOOP and
GOTO
PCPERFORM
Call
SLEEP
406
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
Local Call
(Not reported)
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
SYS_PV
413
Description
NFILES
NUSERS
WRITE_TO_CONSOLE
TMP
NVLMARK
FCNTL_ON
TOGGLE_NAP_TIME
NULL_FLAG
414
Parameter Name
Description
N_FILESYS
N_GLM_GLOBAL_BUCKET
N_GLM_SELF_BUCKET
GLM_MEM_ALLOC
GLM_MEM_SEGSZ
415
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.
Description
SBCS_SHM_SIZE
SHM_MAX_SIZE
SHM_ATT_ADD
SHM_LBA
SHM_MIN_NATT
416
Parameter Name
Description
SHM_GNTBLS
SHM_GNPAGES
SHM_GPAGESZ
SHM_LPINENTS
SHM_LMINENTS
SHM_LCINENTS
SHM_LPAGESZ
SHM_FREEPCT
SHM_NFREES
417
Description
AVG_TUPLE_LEN
EXPBLKSIZE
MAX_OBJ_SIZE
MIN_MEMORY_TEMP
Description
GRP_FREE_BLK
SHM_FIL_CNT
418
Parameter Name
Description
SPLIT_LOAD
MERGE_LOAD
KEYDATA_SPLIT_LOAD
KEYDATA_MERGE_LOAD
MAX_FLENGTH
419
Parameter Name
PART_TBL
Description
Path of a UNIX text file that directs UniData where to create
dynamic file part files.
Description
EFS_LCKTIME
TSTIMEOUT
Description
JRNL_MAX_PROCS
JRNL_MAX_FILES
420
Description
MAX_OPEN_FILE
MAX_OPEN_SEQF
MAX_OPEN_OSF
MAX_DSFILES
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
COMPACTOR_POLICY
VARMEM_PCT
Description
Number of semaphores per semaphore set.
Semaphore udtconfig File Parameters
422
Description
SETINDEX_BUFFER_ KEYS
SETINDEX_VALIDATE_KEY
Description
Number of nodes per bucket. If this parameter is inadequate
for an application, an out of memory message is displayed.
Description
Toggles system buffer on and off. If zero, system buffer is
off. Must be greater than zero for RFS.
423
The following parameters are related to open files with the Recoverable File System.
Parameter Name
Description
BPF_NFILES
N_PARTFILE
The following parameters are related to the active file table (AFT) used with the RFS.
Parameter Name
Description
N_AFT
N_AFT_SECTION
N_AFT_BUCKET
N_AFT_MLF_BUCKET
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
N_ARCH
ARCHIVE_TO_TAPE
ARCH_WRITE_SZ
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
N_TMQ
The following table describes parameters related to the before image and after image log files used
with RFS.
Parameter Name
Description
N_AIMG
N_BIMG
AIMG_BUFSZ
BIMG_BUFSZ
426
Parameter Name
Description
AIMG_MIN_BLKS
BIMG_MIN_BLKS
AIMG_FLUSH_BLKS
BIMG_FLUSH_BLKS
Description
CHKPNT_TIME
GRPCMT_TIME
LOG_OVRFLO
427
The following table describes the parameters related to the sync daemon.
Parameter Name
Description
N_SYNC
SYNC_TIME
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
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
CSTACKSZ
INIT_BREAKOFF
[0 | 1]
JRNL_PATH
429
Environment
Variable
Description
JRNL_RES_HOLD
LPREQ
MAX_CAPT_LEVEL
MAX_RETN_LEVEL
MAX_TRANS_
FIELD
MAX_TRANS_REL
NFA_LOG_DIR
NFA_LOG_LEVEL
NOCHKLPREQ
430
Environment
Variable
Description
RLBK_SECOND
SETINDEX_
BUFFER_
KEYS
SETINDEX_
VALIDATE_KEY
SGLISTNUM
SQL_TMP_MODULO
TABSTOPS
TMP
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.
Environment Variables for UniData (continued)
431
Environment
Variable
Description
UDT_SELECTSIZE
UDTBIN
UDTHOME
VFIELDSIZE
VOC_READONLY
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.
Environment Variables for UniData (continued)
432
Index
Symbols
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
not blocked by dbpause, 145
block size
changing, 136, 215
specifying
for dynamic file, 197
block usage messages, 246
BLOCK.PRINT command
not blocked by dbpause, 145
BLOCK.TERM command
not blocked by dbpause, 145
blocking UniData processing, 144
BP directory
defined, 160
dictionary for, 161
buffering
UniBasic variables, 115
BUILD.FULL.PATH, 27
BUILD.INDEX, 211
building
434
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
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
not blocked by dbpause, 145
reference for, 160
UniBasic locking, 257
COMO command
captured terminal input/output and, 160
not blocked by dbpause, 145
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
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
security considerations for, 171
counter table (CT), 117
CREATE.FILE command
security considerations for, 171
summarized, 214
CREATE.INDEX, 211
CREATE.INDEX command
security considerations for, 171
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
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
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
security considerations for, 171
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
E
E type VOC entry, 356, 359
ECL commands
not blocked by dppause, 145
ECLTYPE command
not blocked by dbpause, 145
ED command
security considerations for, 171
editing
dictionary for QUERY.PRIVILEGE file, 187
ENABLE.INDEX, 211
ENABLE.INDEX command
security considerations for, 171
ENABLE.USERSTATS, 407
environment variables
complete list of, 429
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
G
GCT
See global control tables (GCT)
Index
H
hash groups
identifying, 214
hash type
changing for static file, 215
default, 190
HASH.TEST command
not blocked by dbpause, 145
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
not blocked by dbpause, 145
_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
displaying list of, 148
ipc IDs, checking, 107
ipcstat command
described, 151
not blocked by dbpause, 145
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
not blocked by dbpause, 145
setting semaphore lock with, 259
LINE.DET command
setting semaphore lock with, 259
LIST.INDEX command
not blocked by dbpause, 145
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
semaphore
clearing, 274
displaying list of, 262
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
not blocked by dbpause, 145
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
component of UniData account, 160
dictionary for, 161
menus
definition, storing, 160
MERGE_LOAD parameter, 194
merging groups in dynamic file, 193
merging threshold, 193
message queues
displaying list of, 151
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
not blocked by dbpause, 145
mkdir UNIX command
creating directory for UniData account, 133, 157
MODIFY command
security considerations for, 171
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
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
QUERY.PRIVILEGE file, 187
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
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
displaying list of, 260
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
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
log and error log for, 110
memory segment for, 131
447
Index
448
semicolon
behavior in Windows NT, 18
sentences
reference for, 160
service
defined, 104
services
described, 105
monitoring, 109
SET.DEC command
not blocked by dbpause, 145
SET.MONEY command
not blocked by dbpause, 145
SET.THOUS command
not blocked by dbpause, 145
SET.WIDEZERO command
not blocked by dbpause, 145
SETFILE command
creating VOC entries with, 137
customizing security, 177
summarized, 214
SETLINE command
defining peripheral with, 132
SETOSPRINTER command
not blocked by dbpause, 146
SETPTR, 290, 304, 318
modes, 305
options, 306
parameters, 304
spooler options, 307
SETPTR command
defining peripheral with, 132
not blocked by dbpause, 146
SETTAPE, 19, 344, 346, 348
parameters, 347
SETTAPE command
defining peripheral with, 132
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
displaying list of, 151
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
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
shared memory and, 116
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
T
T.ATT, 19, 344, 348
T.ATT command
not blocked by dbpause, 145
setting semaphore lock with, 259
T.DET, 344, 351
T.DET command
setting semaphore lock with, 259
Index
T.DUMP, 350
T.DUMP command
not blocked by dbpause, 145
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
not blocked by dbpause, 146
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
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
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
shared memory and, 115
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
security considerations for, 171
updatevoc command
not blocked by dbpause, 145
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
component of UniData account, 160
VCATALOG command
not blocked by dbpause, 145
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
not blocked by dbpause, 146
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