Digital PDFs

AA-AJS6J-TE

December 1989

70 pages

Original

2.5MB

Document:	VAX DATATRIEVE Installation Guide (Ver 5.0)
Order Number:	AA-AJS6J-TE
Revision:	000
Pages:	70
Original Filename:

OCR Text

AA-AJ56J-TE

VAX DATATRIEVE
Installation Guide
December 1989
This manual describes the installation procedure for VAX DATATRIEVE.

Operating System and Version: VMS Version 5.1 or higher

digital equipment corporation
maynard, massachusetts

The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be used
or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is
not supplied by Digital Equipment Corporation or its affiliated companies.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(l)(ii) of the Rights in Technical Data and
Computer Software clause at DFARS 252.227-7013.
©Digital Equipment Corporation 1984, 1985, 1986, 1987, 1988, 1989.
All Rights Reserved.
Printed in U.S.A.
The postpaid Reader's Comments forms at the end of this document request your
critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
ACMS
ALL-IN-1
DATATRIEVE
DEC
DEC/CMS
DEC/MMS
DECforms
DECintact
DECmate
DECnet
DECUS
DECwindows
DECwriter
DIBOL

MASS BUS
PDP
P/OS
Professional
Rainbow
RALLY
Rdb/ELN
Rdb/VMS
ReGIS
RSTS

UNIBUS
VAX
VAX CDD/Plus
VAXFMS
VAXcluster
VAXstation
VIDA
VMS
VT

Work Processor

RSX

RT
TDMS
ULTRIX

The following are third-party trademarks:
IBM is a registered trademark of International Business Machines, Inc.
PostScript is a registered trademark of Adobe Systems, Inc.
ZK5292

This document was prepared using VAX DOCUMENT, Version 1.1

Contents
?reface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vii

1 Preinstallation Considerations
1.1
1.2
1.3
1.3.1
1.3.2
1.3.3
1 A

l.""t

Prerequisite Hardware ................................. .
VAX Licensing Management Facility (LMF) ................ .
Prerequisite Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Required Software Products .......................... .
Optional Software Products . . . . . . . . . . . . . . . . . . . . . . . . . . .
Order of Product Installation ......................... .

1-1
1-2
1-2
l-2
1-3
1-3

'tTAV-1
•• -~-- VVJ.J.i:)J.UCJ.a.t..J.VJ.J.i:)
..l---~=--- • • • • • • • , • • • • • • , • , • • • , , • • • • • • , • ,
Y~\,J.U>:)1.>Ca

1"'1---=

1.5
Preparing Your System and the Installing Account ........... .
1.5.1
Required Parameters ............................... .
1.5. l. l
Open File Limit (FILLM Parameter) ................ .
1.5. l .2
Enqueue Quota Limit (ENQLM Parameter) ........... .
1.5. l .3
Global Pages and Global Sections (GBLPAGES and
GBLSECTIONS Parameters) ...................... .
1.5.1.4
Command Line Interpreter Symbols Table (CLISYMTBL)
Limits ....................................... .
1.5.2
CDD/Plus Considerations ............................ .
1.5.2. l
Effect of Installation Procedure on Existing DTR$LIB
Directory ..................................... .
1.5.2.2
Required Privileges to CDD$TOP .................. .
1.5.3
Effect of Installation Procedure on the Logical
DTR$LIBRARY ................................... .
1.5.4
More than One Installation of this Version of
DATATRIEVE .................................... .

A
.-"'+

1-5
1-5
1-5
1-6
1-6

1-7
1-7
1-8
1-8

1-9
1-9

iii

2 VAX DATATRIEVE Installation Procedure
2.1
2.2

Starting the Installation Procedure ....................... .
Mounting the Distribution Medium ....................... .
2.3
Answering Questions About Release Notes ................. .
2.4
Answering Questions About the VAX Licensing Management
Facility (LMF) ....................................... .
2.5
Answering Questions During the DATATRIEVE Installation .... .
2.5. l
Installing DATATRIEVE with the Default Answers ........ .
2.5.2
Installing with Support for VAX Language-Sensitive Editor
(LSE) ........................................... .
2.5.3
Installing with Support for Forms Products .............. .
2.5.4
Specifying Suffixes for More than One Installation of this
Version of VAX DATATRIEVE ........................ .
2.5.5
Deleting the DATATRIEVE Object Library .............. .
2.5.6
Defining the DATATRIEVE Remote Server .............. .
2.5.7
Creating a DCL Command File for New Users ........... .
2.5.8
Installing Shared Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.9
Installing Plot Definitions and Optional Material . . . . . . . . . .
2.5.10
Deleting Obsolete Files ............................. .
2.6
Finishing the Installation .............................. .

2-1
2-~

2-L
2-L
2-t
2-t

2-i
2-~
2-~
2-1~

2-1~
2-1~

2-H
2-U
2-li
2-li

3 Postinstallation Considerations
3.1

3.2
3.3
3.4
3.4.1

3.4.2
3.5
3.6

Updating SYS$MANAGER:SYSTARTUP_V5.COM ........... .
VAXcluster Considerations .............................. .
Updating Process Command Tables ....................... .
DECnet Considerations ................................ .
Defining a DECnet Object ........................... .
Creating a Default DECnet Account for Distributed Access .. .
Maintaining User-Defined Functions ...................... .
Deleting Unused Files for DATATRIEVE DECwindows Support ..

3-i
3-1
3-~

3-~
3-~

3-~

3-t
3~

4 User Environment Test Packages
4.1

4.2
4.3
4.4

4.5
4.6

Invoking DATATRIEVE ................................ .
VAX DATATRIEVE UETP .............................. .
VAX DATATRIEVE Graphics UETP ....................... .
VAX DATATRIEVE and VAX DBMS UETP .... .' ............ .
VAX DATATRIEVE and VAX RdbNMS UETP ............... .
VAX DATATRIEVE and Forms UETP ..................... .

4-·
4-~

4-!
4~
4-~
4-1~

5 Maintaining VAX DATATRIEVE
5.1
5.2

Writing a Session Log to a File . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reporting Problems to Digital ........................... .

5-1

5-2

Preface
This manual describes how to install the DATATRIEVE software and use the
DATATRIEVE User Environment Test Packages (UETPs).
This manual does not contain any release note information. Printed release
notes for DATATRIEVE are found in the VAX DATATRIEVE Release Notes.
Release notes for DATATRIEVE are also shipped with the installation kit and
can be printed during the installation procedure.

Intended Audience
This manual is intended for persons responsible for installing and maintaining
DATATRIEVE software. To install the software, you should be familiar with
VMSINSTAL, the command procedure used to install software products
in the VMS environment. For information on VMSINSTAL, see the VMS
documentation.

Operating System Information
Information about the versions of the operating system and related software
that are compatible with this version of DATATRIEVE is included in the
DATATRIEVE media kit, in either this manual or the Before You Install VAX
DATATRIEVE 'Version 5.0 letter.
For information on the compatibility of other software products with this
version of DATATRIEVE, refer to the System Support Addendum (SSA) that
comes with the Software Product Description (SPD). You can use the SPD/SSA
to verify which versions of your operating system are compatible with this
version of DATATRIEVE.

vii

Structure
This manual consists of five chapters:
Chapter 1

Explains how to plan the installation and prepare your system.

Chapter 2

Explains the installation procedure and the questions asked during
installation.

Chapter 3

Identifies important postinstallation considerations.

Chapter 4

Describes the User Environment Test Packages (UETPs) and
provides instructions for running them.

Chapter 5

Explains how to report DATATRIEVE problems to Digital.

Related Documents
For further information on the topics covered in this manual, you can refer to
the following documentation:

• VAX DATATRIEVE Release Notes
Includes specific information about the current VAX DATATRIEVE release
and contains material added too late for publication in the other VAX
DATATRIEVE documentation.
• VAX DATATRIEVE Guide to Using Graphics
Introduces the use of DATATRIEVE graphics and contains the reference
material for creating DATATRIEVE plots.
• VAX DATATRIEVE Guide to Writing Reports
Explains how to use the VAX DATATRIEVE Report Writer.
• VAX DATATRIEVE Handbook
Describes how to create VAX DATATRIEVE applications. The manual
includes some tutorial information on describing data and creating
procedures.
• VAX DATATRIEVE User's Guide
Describes how to use VAX DATATRIEVE interactively. The manual
includes information on using VAX DATATRIEVE to manipulate data
and on using VAX DATATRIEVE with forms, relational databases,
and database management systems. It also describes how to improve
performance and how to work with remote data.
• VAX DATATRIEVE Quick Reference Guide
Contains quick-reference information about using VAX DATATRIEVE.

viii

• VAX DATATRIEVE Guide to Programming and Customizing
Explains how to use the VAX DATATRIEVE Call Interface. The manual
also describes how to create user-defined keywords and user-defined
functions to customize VAX DATATRIEVE and how to customize VAX
DA'.TATRIE\' ~ help and message texts.
• VAX DATATRIEVE Reference Manual
Contains reference information for DATATRIEVE.

Conventions
This section explains the conventions for the syntax and symbols used in this
manual:
Convention

Meaning

WORD

An uppercase word in a syntax format is a keyword. You must
include it in the statement if the clause is used.

word

A lowercase word in a syntax format indicates a syntax element
that you supply.

word

A bolded word indicates that a new term is being introduced.

[ ]

Brackets enclose optional clauses from which you can choose one
or none.

{ }

Braces enciose ciauses from which you must choose one
alternative.
This symbol indicates the RETURN key. Unless otherwise
indicated, end all user input lines in examples by pressing the
RETURN key.
This symbol indicates the TAB key.
This symbol tells you to press the CTRL (control) key and hold
it down while pressing a letter key. If you press CTRUZ, the
word Exit appears in reverse video; if you press CTRUY, the word
Interrupt appears in reverse video. Examples of video output in
this book do not include either word; instead the conventions Zand
Y are used.

!GOLD-xi

This symbol indicates that you press the GOLD key and then a
specified letter key consecutively.
These are double quotation marks.

These are single quotation marks.
A horizontal ellipsis in syntax formats means you can repeat the
previous item.
A horizontal ellipsis in examples means that information not
directly related to the example has been omitted.

Convention

Meaning

A vertical ellipsis in syntax formats means you can repeat the
syntax element from the preceding line.
A vertical ellipsis in examples means that information not directly
related to the example has been omitted.
Color

Color in examples shows user input.

References to Products
The VAX DATATRIEVE documentation to which this manual belongs often
refers to products by their abbreviated names:
• VAX CDD/Plus software is referred to as CDD/Plus.
• VAX DATATRIEVE software is referred to as DATATRIEVE.
• VAX Rdb/ELN software is referred to as Rdb/ELN.
• VAX RdbNMS software is referred to as RdbNMS.
• VAX TDMS software is referred to as TDMS.
• VIDA software is referred to as VIDA.
This manual uses the term relational database or relational source to refer to
all three of these products:
• VAX Rdb/ELN
• VAXRdbNMS
• VIDA

1
Preinstallation Considerations
This chapter includes important installation considerations that you must be
aware of before you install VAX DATATRIEVE Version 5.0. Read this chapter
carefully before you proceed to Chapter 2.
To prepare your system for installing VAX DATATRIEVE, you must perform
the following tasks:
• Verify that your system has enough memory and available disk space to
install and use DATATRIEVE.
• Register the Product Authorization Key (PAK) that is shipped with this
version of DATATRIEVE.
"tT--.!.L!__ LL-.L. ------- ____ ..1.. _ _ _

•

Vt::.LH.Y ll.l.li:lll ,YUU.l

1_ - -

.Ll_ -

- - - - - - - _ _._

______ ! -·-- -·

.Ll- -

- __ .J....! -

- - ,

i::i,Yi::illt::I.11 1.li:li::i Ult;; \;U!Tt;;\;I,, Vt;;n;1u11:::; Ul LHt;; UIJLIUHC::U

- _,

a.nu

required software you will be using with DATATRIEVE.
• Check your system and the installing account to ensure that parameters
and quotas are sufficient for installing and using DATATRIEVE.
This chapter tells you what actions to take to prepare your system for
installing VAX DATATRIEVE.

1. 1 Prerequisite Hardware
VAX DATATRIEVE runs on all VAX processors except the VAX-111725
processor. For a complete list of processors, see the VAX DATATRIEVE
Software Product Description.
To install this version of VAX DATATRIEVE, you must have 16,000 blocks of
storage available on the system disk. After installation, DATATRIEVE requires
a maximum of 11,000 blocks of disk space if you install all optional software
with DATATRIEVE. To check the number of blocks of storage available on the
system disk, use the SHOW DEVICES command at the DCL prompt.

Preinstallation Considerations

1-1

1.2 VAX Licensing Management Facility (LMF)
This version of VAX DATATRIEVE supports the License Management Facility
provided by VMS. See the VMS License Management Utility Manual for more
information.
You should register the information contained in the Product Authorization
Key (PAK) that is shipped with DATATRIEVE before you begin the installation.
You can register by using the VMS License command procedure using the
following command:
$ @SYS$UPDATE:VMSLICENSE

You can also use the LICENSE REGISTER command to register the
information contained in the PAK. Both methods are described in the VMS
License Management Utility Manual.
DATATRIEVE asks you early in the installation procedure whether or not you
have registered and loaded an authorization key. You can install this version of
DATATRIEVE without the authorization key information, but you cannot run
DATATRIEVE or the Installation Verification Procedure (IVP).

1.3 Prerequisite Software
You must have the correct versions of the optional and required software
products you will be using with DATATRIEVE. Install those products in the
order specified in Section 1.3.3.

1.3. 1 Required Software Products
This version of DATATRIEVE is a complete kit. You do not need any previous
versions of DATATRIEVE to install it.
VAX DATATRIEVE Version 5.0 will install and run only on Version 5.1 or
higher of the VMS operating system. If you have a VMS version lower than
5.1, you must install VMS Version 5.1 or higher before you can install VAX
DATATRIEVE. To check which version of VMS is currently installed on your
system, use the SHOW SYSTEM command at the DCL prompt.
You must have Version 4.1 of VAX CDD/Plus before you can install VAX
DATATRIEVE. To check which version of CDD/Plus is currently installed on
the system, use the following command:
$ DICTIONARY OPERATOR

1-2 Preinstallation Considerations

The CDO banner gives the version of CDD/Plus currently installed on your
system. For example:
Welcome to CDO Vl.O
The CDD/Plus V4.l User Interface
Type HELP for help
COO>

See the VAX CDD I Plus Installation Guide for more information.

1.3.2 Optional Software Products
The following optional products can be used along with VAX DATATRIEVE:
• DECwindows
• VAX.DBMS
• VAX Rdb/VMS
• VAX Rdb/ELN
• VAXTDMS
• VAXFMS
• VIDA
• VAX Language-Sensitive Editor (LSE)
Refer to the letter entitled Before You Install VAX DAT'AT'RIEVE to determine
which versions of these optional software products are compatible with
DATATRIEVE Version 5.0.
If an optional product is on the system but is not the version required by
DATATRIEVE, the installation procedure will not install the User Environment
Test Package (UETP) for that product. (Note that not all optional software
products have a UETP.)
If you want to ready domains that reside on a remote node of a PDP-11
system, you must have Version 3.2 or higher of the DATATRIEVE-11 software
installed on the remote node that you want to access.

1.3.3 Order of Product Installation
When you install required and optional software products with DATATRIEVE,
you should install these products in the following order:
• Optional DECwindows
If you plan to use DATATRIEVE with DECwindows, install DECwindows
before installing other required or optional software products. If you choose
to install DECwindows at a later date, you must reinstall DATATRIEVE to
take advantage of DECwindows features.

Preinstallation Considerations

1-3

• Optional LSE
If you plan to use LSE with DATATRIEVE, you should install LSE after
optionally installing DECwindows and before installing other required
or optional software products. However, if you choose to install LSE at
a later date, the DATATRIEVE installation procedure provides you with
the option of performing a modified DATATRIEVE installation to provide
DATATRIEVE support for LSE at that time.
• CDD/Plus
•

Optional forms products (TDMS, FMS)

• Optional database products (VAX DBMS, RdbNMS, Rdb/ELN, VIDA)
Install VAX DBMS, RdbNMS, Rdb/ELN, and VIDA before installing
DATATRIEVE to make sure the installation includes sample databases
and User Environment Test Packages. You do not have to install these
optional database products before DATATRIEVE to use the products with
DATATRIEVE.
• DATATRIEVE

1.4 VAXcluster Considerations
The following considerations pertain to VAXclusters:
• If you installed a version of DATATRIEVE lower than Version
3.2 on a VAXcluster, the installation procedure placed files in
SYS$SPECIFIC:[DTR]. Before installing any version of DATATRIEVE
higher than Version 3.1, you must delete the old files in SYS$SPECIFIC:[DT
and the SYS$SPECIFIC:[DTR] directory itself.

Follow these steps to delete the files and the directory:
Log in to a privileged account on the system on which the previous
version of DATATRIEVE was installed.
2

Delete all files from the directory as follows:
$DELETE SYS$SPECIFIC: [DTR]*.*;*

Delete the directory itself using the following command:
$DELETE SYS$SPECIFIC: [OOOOOO]DTR.DIR;*

• This installation procedure lets you install DATATRIEVE only on a
system-rooted device. Whether you are installing DATATRIEVE
on a VAXcluster or in a nonclustered environment, the installation
procedure places the files that it generates in SYS$COMMON, not in
SYS$SPECIFIC. The installation defines the logical name DTR$LIBRARY
as SYS$COMMON:[DTRJ.

1-4 Preinstallation Considerations

1.5 Preparing Your System and the Installing Account
This section tells you which characteristics of your system and installing
account need to be checked before you install DATATRIEVE. These
characteristics include process quotas, access control privileges to CDD$TOP,
and system parameters. Instructions are given for checking and modifying the
relevant characteristics of your system and installing account.

1.5. 1 Required Parameters
You should check the following parameters to make sure they are sufficient for
installing DATATRIEVE:
• Open file limit (FILLM parameter)
• Enqueue quota limit (ENQLM parameter)
• Global pages and global sections (GBLPAGES and GBLSECTIONS
parameters)
• Command line interpreter symbol table (CLIS'YMTBL parameter)
1.5.1. l Open File Limit (FILLM Parameter) For the DATATRIEVE
installation procedure to run successfully, the account used to install
DATATRIEVE should have a minimum open file limit (FILLM parameter)
of 30. To check the current open file limit, use the SHOW PROCESS/QUOTAS
command at the DCL prompt. In addition; check the documentation of
products layered on DATATRIEVE to see if the open file limit should be further
increased.

If the open file limit is too low, VMSINSTAL generates the following message
at the beginning of the installation:
%VMSINSTAL-W-LOWQUOTA, One or more account quotas may be too low.

The installation continues, but the Installation Verification Procedure (IVP)
that runs as part of this installation may fail.
Users running DATATRIEVE should also have an open file limit of 30. Users
running large applications that open many files may need this value increased
further through the Authorize Utility.
Users who exceed their open file limit may see a meaningless display on
their screen when they start DATATRIEVE. They may receive a message
without further explanation, such as "quota exceeded" or "ACP file access
failed." (In addition, note that users who are close to or exceed their disk
quota limit generate the %SYSTEM-F-ABORT message when they try to
invoke DATATRIEVE. This error occurs because DATATRIEVE tries to open a
workfile and cannot. Users with default disks mounted read-only receive the
same error message.)

Preinstallation Considerations

1-5

1.5.1.2 Enqueue Quota Limit (ENQLM Parameter) You may need to be
concerned with the overall number of locks in the system and the enqueue
quota limit (ENQLM parameter) assigned to individual users. To check the
current enqueue quota, use the SHOW PROCESS/QUOTAS command at the
DCL prompt.

An ENQLM of about 200 locks is sufficient for most activities, including

running the DATATRIEVE User Environment Test Packages (UETPs).
However, users running applications that access large databases may require
more than 200 locks. If such users do not have more than 200 locks, they
receive a quota exceeded message from the VMS system. This message does
not mention the ENQLM parameter or locks. You can change the ENQLM by
using the Authorize Utility.
Rdb/VMS, in particular, uses many locks and may require raising the ENQLM
in the following circumstances:
•

If the account you use to install DATATRIEVE has an ENQLM under

500, the installation cannot build the sample Rdb/VMS database. The
installation continues without building the sample database. To include
the sample Rdb/VMS database, you must reinstall DATATRIEVE using an
account with an ENQLM of 500 or more.
• To use the RdbNMS demo, you need an account with an ENQLM of 600.
• You may receive the quota exceeded message when using DATATRIEVE
with RdbNMS. To continue, finish unnecessary databases or selected
parts of the database using the FINISH command or exit and reenter
DATATRIEVE. If you still receive the quota exceeded message, have your
system manager raise your account enqueue quota limit.
1.5.1.3 Global Pages and Global Sections (GBLPAGES and GBLSECTIONS
Parameters) If you plan to install various DATATRIEVE images as SHARED,

you need sufficient global pages and global sections. The installation procedure
asks you about four images: DDMFxx, DTR32xx, DTRSHRxx, and DTRMSGS.
(The xx at the end of the file name refers to the optional suffix that you can
specify in the installation procedure. See Section 2.5.4 for more information.)
You do not have to install all of these images; you need sufficient global pages
and global sections only for those you do wish to install.
DATATRIEVE automatically installs two images as SHARED: DTRHELP and
DTR$CDDTSHR. You need sufficient global pages and global sections for these
images.
The following table indicates the requirements for the GBLPAGES and
GBLSECTIONS parameters for the image files that are part of this version of
DATATRIEVE.

1-6 Preinstallation Considerations

File

Global Sections

Global Pages

DDMFxx
DTR32xx

1
1

DTRSHRxx

952

DTRMSGS

105

DTRHELP

DTR$CDDTSHR

61
791

143
204

To display the current GBLSECTIONS and GBLPAGES parameters, you can
use the SHOW GBLSECTIONS and SHOW GBLPAGES commands of the
System Generation Utility (SYSGEN). Note, however, that to modify these
parameters, you should use the AUTOGEN Utility.
If the global pages and global sections already on your system are not

sufficient, you will need to modify the parameters before installing
DATATRIEVE. To modify these parameters, follow the instructions in the
VMS documentation on system management that refers to MODPARAMS.DAT
and AUTOGEN.
1.5. 1.4 Command Line Interpreter Symbols Table (CLISYMTBL) Limits The
DATATRIEVE installation procedure creates a number of DCL symbols. To
ensure that your system can accommodate the number of symbols created at
installation time, set the CLISYMTBL limit to at least 250.

To check the current CLISYMTBL limit, use the SHOW CLISYMTBL command
while in SYSGEN. To modify this parameter, run SYSGEN as follows:
$ RUN SYS$SYSTEM:SYSGEN
SYSGEN> SET CLISYMTBL 250
SYSGEN> WRITE ACTIVE
SYSGEN> WRITE CURRENT

You will receive a message indicating that the system has been modified.
You can then exit SYSGEN. For more information on SYSGEN, see the VMS
documentation on system management.
If you do increase the CLISYMTBL limit to 250, you may reduce it to the

normal level after the installation is completed.

1.5.2

COD /Plus Considerations

Before you install DATATRIEVE, you should perform the following tasks:
• Check the contents of the dictionary directory CDD$TOP.DTR$LIB for user
definitions and subdirectories. Back these up if they exist.
• Make sure the installation procedure has all access privileges to CDD$TOP.
The next two sections explain these procedures.

Preinstallation Considerations

1-7

1.5.2. 1 Effect of Installation Procedure on Existing DTR$LIB Directory
The directory CDD$TOP.DTR$LIB is reserved for use by Digital. The
installation procedure builds, or rebuilds, this directory each time you install
DATATRIEVE. The directory should contain only directories that contain
definitions for the plots and sample domains, records, and tables that are
shipped with the product. Users should not create any dictionary objects or
directories that have DTR$LIB as part of their path names.

When the installation procedure rebuilds DTR$LIB, it deletes the existing
DTR$LIB hierarchy. Therefore, you should check that DATATRIEVE users
have not placed their own definitions either in DTR$LIB or in any part of its
substructure. Extract user definitions you want to save and redefine them in
another directory.
1.5.2.2 Required Privileges to CDD$TOP Because the installation procedure
builds or rebuilds DTR$LIB, the procedure must have all access control
privileges to CDD$TOP. You can check these privileges with the following
command sequence:
$ SET PROCESS/PRIVILEGE=NOBYPASS
$ RUN SYS$SYSTEM:DMU
DMU> SHOW PROTECTION CDD$TOP

The resulting privileges list should include the following:
CONTROL

GLOBAL_DELETE

DTR_EXTEND

HISTORY

DTR_MODIFY

LOCAL_DELETE

DTR_READ

PASS_THRU

DTR_WRITE

SEE

EXTEND

UPDATE

FORWARD

After checking the privileges list, type EXIT and press the RETURN key to
return to DCL command level.
If any of the required privileges are not available or if they are denied or
banished, you must change the access control list (ACL) entry to provide all
privileges for the duration of the installation. One way you can do this is to
enter the following sequence of commands:
$ SET PROCESS/PRIVILEGES=BYPASS
$ RUN SYS$SYSTEM:DMU
DMU> SET PROTECTION/GRANT=ALL/UIC=[l,4]DMU> /POSITION=l CDD$TOP
DMU> EXIT
$ SET PROCESS/PRIVILEGES=NOBYPASS

1-8 Preinstallation Considerations

If you are using an account other than [1,4] for the installation, replace [1,4]

with the UIC of that account.
After the installation procedure is complete, you can remove the ACL entry
with the following command sequence:
$ SET PROCESS/PRIVILEGES=BYPASS
$ RUN SYS$SYSTEM:DMU

DMU> DELETE/PROTECTION/POSITION=l CDD$TOP
DMU> EXIT
$ SET PROCESS/PRIVILEGES=NOBYPASS

For your convenience during future installations of DATATRIEVE, you might
want to create command files containing these two sequences of commands.
Note that the command procedure VMSINSTAL removes BYPASS privilege.
Therefore, you cannot give yourself BYPASS privilege as a substitute for these
sequences.

1.5.3 Effect of Installation Procedure on the Logical
DTR$LIBRARY
The installation defines the logical DTR$LIBRARY as SYS$COMMON:[DTR].
If the installation fails, DTR$LIBRARY may be left deassigned, and you must
redefine it. To redefine the logical, use either the ASSIGN command or the
DEFINE command, as follows:

~ ( ASSIGN/SYSTEM
SYS$COMMON: [DTR] DTR$LIBRARY
DEFINE/SYSTEM DTR$LIBRARY SYS$COMMON: [DTR]
~$

'.5.4 More than One Installation of this Version of DATATRIEVE
You can install this version of DATATRIEVE a number of times to produce
different sets of images and files. Note, however, that you cannot install
multiple versions of DATATRIEVE, such as both Version 4.2 and Version
5.0. For example, the installation procedure could be run first to install
DATATRIEVE Version 5.0 with TDMS. You can install DATATRIEVE Version
5.0 a second time to support FMS. The resulting images and file names
are differentiated by a suffix added to the default names. The installation
procedure prompts you to choose this suffix.
The suffix you specify will be given to the following files created during
installation. The two letters xx at the end of a file name stand for the 1- to
26-character suffix you specify:
• SYS$SHARE:DTRSHRxx.EXE
• SYS$SYSTEM:DTR32xx.EXE
• SYS$SYSTEM:DDMFxx.COM
• SYS$SYSTEM:DDMFxx.EXE

Preinstallation Considerations

1-9

• DTR$LIBRARY:DTRBLDxx.COM
• DTR$LIBRARY:DTRLIBxx.OLB
• DTR$LIBRARY:DTRFNDxx.MAR
• DTR$LIBRARY:DTRFNDxx.OBJ
• DTR$LIBRARY:DTRFUNxx.OLB
•

SYS$STARTUP:DTRSTUPxx.COM

Note that the installation procedure does not append the xx suffix to all images
and files. See the restrictions regarding the DTR$LIB:TERMSERVE.OLB file
in the release notes for more information.

1-10 Preinstallation Considerations

2
VAX DATATRIEVE Installation Procedure
Before you install DATATRIEVE Version 5.0, make sure that your system
meets all requirements listed in the previous chapter.
Your Version 5.0 installation kit consists of one magnetic tape or disk pack.
This medium makes obsolete the distribution media for any lower version of
DATATRIEVE.
The installation procedure is described in the sections that follow. Note that as
the procedure progresses, the installation command procedure sends questions
to your screen to guide you through the installation process. The sections that
follow explain these questions in detail.
After you answer questions from the installation procedure, installation of
DATATRIEVE takes approximately 10 to 30 minutes.

2.1

Starting the Installation Procedure
Log in under a privileged account, such as the system manager's account.
Invoke the command procedure VMSINSTAL. In the command line, include
the name of the device on which the distribution medium is to be mounted.
Be sure to type a colon after the device name. Include the qualifier OPTIONS
N if you want to print or display release notes during the installation. (See
Section 2.3 for more information.) If you do not want to print or display release
notes, do not include OPTIONS N.
The following example shows how to install DATATRIEVE Version 5.0 with
the OPTIONS N qualifier on device MTAO. Be sure to replace MTAO with the
name of the specific device you are using:
$ @SYS$UPDATE:VMSINSTAL DTR050 MTAO: OPTIONS N

VAX DATATRIEVE Installation Procedure

2-1

Note that you can specify the AUTOANSWERBACK option when you invoke
VMSINSTAL. This option creates the file SYS$UPDATE:DTR050.ANS, which
contains the installation questions and your responses. This file can then
be used in subsequent installations. (The VMS documentation on software
installation contains more information about VMSINSTAL.)
The AUTOANSWERBACK option is not recommended for DATATRIEVE
installations. Questions asked during the DATATRIEVE installation are
based on the system environment. The system environment at the time of the
original installation determines which questions the installation procedure
will ask. When you proceed with a subsequent installation, the questions
change according to changes in the system environment. Thus, if you specify
AUTOANSWERBACK during the original installation, you probably will not
receive the appropriate questions during the subsequent installation.
The installation procedure prompts you for input at various times. Whenever
you are prompted for input, you can type a question mark(?) symbol for help.
Most installation prompts include a default response in brackets. To enter the
default bracketed response, you can either explicitly enter that response or
press the RETURN key.
Before the installation procedure begins, VMSINSTAL checks if you are logged
in to the system account. If not, you receive this warning message:
%VMSINSTALL-W-NOTSYSTEM, You are not logged in to the system account.

In addition, before the installation procedure begins, VMSINSTAL checks
for active processes on the system. If your DECnet network is running, you
receive this warning message:
%VMSINSTAL-W-DECNET, Your DECnet network is up and running.

If there are still users on the system, you receive this warning message with a

list of process names:
%VMSINSTAL-W-ACTIVE, The following processes are still active:

The list of the process names is followed by this question:
* Do you want to continue anyway? [NO]

If you want to stop the installation process to get all users off the system, enter

N or press the RETURN key.
At the start of the VMSINSTAL procedure, you need to answer the following
question:
*Are you satisfied with the backup of your system disk [YES]?

2-2

VAX DATATRIEVE Installation Procedure

After you have performed the necessary backup, enter Y or press the RETURN
key. If you reply with N, the installation stops.

2.2 Mounting the Distribution Medium
VMSINSTAL displays the following message:
Please mount the first volume of the set on MTAO:

* Are you ready?

Type Y after you mount the distribution medium.
The installation procedure then checks if the following necessary conditions for
the installation have been fulfilled:
• The target of the installation is SYS$COMMON on the system-rooted
device.
• A compatible version of VMS is installed.
• At least 16,000 blocks are available on the system disk.
• A compatible version of CDD1Plus is installed on the system.
• The installation procedure has ACL access rights to CDD$TOP.
If any of these conditions has not been fulfilled, the installation procedure
displays a message describing the problem. After satisfying the requirement,
you can rerun the installation procedure by invoking the command procedure
VMSINSTAL again.
Note Systems that do not have DECnet cannot support the DATATRIEVE remote

server. On such systems, the installation procedure next displays a message
noting that it cannot define a DECnet object for the remote server. If you later
install DECnet, you will then need to define a DECnet object for the remote
server. See Section 3.4 for more information.
This ends the initial series of questions generated by VMSINSTAL. If you have
successfully completed this portion of the installation, a message similar to the
following is displayed:
The following products will be processed:
DTR V5.0
Beginning installation of DTR V5.0 at 8:15
VMSINSTAL-I-RESTORE, Restoring product saveset A ...

The installation continues with questions about release notes.

VAX DATATRIEVE Installation Procedure

2-3

2.3 Answering Questions About Release Notes
If you specified the qualifier OPTIONS Nat the beginning of the installation,

the procedure offers these options regarding DATATRIEVE Version 5.0 online
release notes:
Release Notes Options:
1.
2.
3.
4.
5.

Display release notes
Print release notes
Both 1 and 2
Copy release notes to SYS$HELP
Do not display, print or copy release notes

* Select option [2]:

Enter the number corresponding to the option you choose. If you enter option
2 or 3, the procedure prompts you for the printer queue name. It then prints a
message showing that the job has been queued for printing.
*Queue name [SYS$PRINT]:
Job DTROXX (queue YOURSYS_DQS$PRINT, entry 1248) started on
YOURSYS_DQS$PRINT

The procedure now asks if you want to continue the installation.
*Do you want to continue the installation [N]?

If you want to continue, enter Y.
If you selected one of the print options, you must wait until the release notes
finish printing before you enter the N or press the RETURN key. If you did not

select a print option and wish to exit, enter N or press the RETURN key.

2.4 Answering Questions About the VAX Licensing
Management Facility (LMF)
DATATRIEVE Version 5.0 supports the License Management Facility provided
by VMS. The installation procedure asks whether you have registered and
loaded a Product Authorization Key (PAK) as required.
Product:

DTR or DTR-USER

Producer:

DEC

Version:

5.0

Release Date:

27-0CT-1989

* Does this product have an authorization key registered and loaded?

2-4

VAX DATATRIEVE Installation Procedure

If you answer Y or YES, the procedure continues. If you answer N or NO, you
receive the following message:
You have not registered the LMF authorization key as required.
The DATATRIEVE installation will continue. However, you
cannot run the product until you register the licer1se authorization
key.
When the DATATRIEVE installation is completed, please register the
authorization key using the following command:
$ @SYS$UPDATE:VMSLICENSE
The IVP cannot be run until the authorization key is registered.
However, the IVP command file will be put in the same directory
as the UETPs.
Once you register the authorization key, you may
run the IVP by entering DATATRIEVE and issuing the following
command:
DTR> @SYS$COMMON: [SYSTEST.DTR]DTR$IVP.DTR

The installation continues with a series of DATATRIEVE-specific questions.

2.5 Answering Questions During the DATATRIEVE Installation
The installation procedure asks you a number of questions concerning default
installation, forms management products, multiple DATATRIEVE installations,
and DATATRIEVE files. The following sections give examples of these
questions.

2.5. l

Installing DATATRIEVE with the Default Answers

The installation procedure now ;:1Sks if yo1_1_ WB_nt to in.stf!ll DATATRIEVE using
default answers for all questions.
Note While this question may simplify the installation procedure, it may not be

appropriate for your situation. For example, if your system supports more than
one installation of this version of DATATRIEVE, you should not select the
default installation option. Read the summary of the default responses that
follows the question before you choose this option.
The installation procedure prompts you with the following question:
·~

*Do you want to use default answers for all questions [No]?

If you type Y, the DATATRIEVE installation procedure automatically does the
following:
•

Performs a complete installation of DATATRIEVE; it will not allow a
partial installation to provide DATATRIEVE support for LSE.

•

Checks your system for a forms management product. If DATATRIEVE
does not find a forms product, the automatic installation procedure provides
no forms management support.

VAX DATATRIEVE Installation Procedure

2-5

If a forms product already exists on the system, DATATRIEVE:

Supplies FMS support, if only FMS is on the system
Supplies TDMS support, if only TDMS is on the system
Supplies only TDMS support, if both FMS and TDMS are found on the
system
• Does not prompt you for the unique 1- to 26-character suffix that identifies
the DTR32xx.EXE image of this installation. Note that if you have already
installed this version of DATATRIEVE and did not supply a suffix during
that installation, you will need a suffix to differentiate the image of that
prior installation from the image currently being installed. In such a case,
the default installation procedure is not appropriate.
• Does not prompt you for the default image to be used with the
DATATRIEVE DCL command and DCL help. The default image will
be DTR32.
• Does not supply the DATATRIEVE object library in DTR$LIBRARY. (This
means that you will not be able to relink this image of DATATRIEVE.)
• Checks if the DATATRIEVE remote server has been defined by a previous
installation of DATATRIEVE. The DATATRIEVE remote server is called
the Distributed Data Manipulation Facility (DDMF).
When the installation procedure checks for a previously defined DDMF:
If there is no remote server or if the remote server is obsolete, the
DDMF files from this installation become the remote server for
DATATRIEVE.
If there is a current remote server already on the system, the
default installation procedure uses that as the remote server for
this installation of DATATRIEVE.

• Checks if there is a current version of NEWUSER.COM available.
When the installation procedure checks NEWUSER.COM:
If NEWUSER.COM is not current, DATATRIEVE automatically
replaces the NEWUSER. COM file.
If the NEWUSER.COM is current, DATATRIEVE does not replace the
new user file.

• Checks the status of the DCL help for DATATRIEVE. If DCL help is
unavailable or out-of-date, DATATRIEVE automatically updates DCL help.
• Installs DTRSHR.EXE, DTRMSGS.EXE, DTR32.EXE, and DDMF.EXE (if
applicable) as SHARED.
• Installs DTRHELP and DTR$CDDTSHR as SHARED.

2-6

VAX DATATRIEVE lnstailation Procedure

•

Supplies the plot definitions for the current version.

•

Does not supply the optional text and message files, sample programs, and
callable programming aids that can be tailored at the installed site.

Deletes all obsolete files.

•

Purges files replaced by this installation.

If you type N, the installation procedure continues with the questions about
LSE.

2.5.2

Installing with Support for VAX Language-Sensitive Editor
(LSE)

To use LSE with DATATRIEVE, LSE must already be installed on your system.
If LSE is not already installed on your system, you see the following message
on your screen:
**************************************************************
The VAX Language-Sensitive Editor is not installed on your
system. To have the VAX Language-Sensitive Editor support,
you must:
1.
2.

Install the VAX Language-Sensitive Editor
Install or reinstall this product

**************************************************************
*Do you want to continue the installation [No]?

If you enter Y or YES, the installation continues; however, you will not be able
to use LS~ with DA'.l'ATHrnVK lf you enter the default value by entering N,
NO, or by pressing the RETURN key, the installation aborts, giving you the
opportunity to install LSE on your system. Once LSE is installed, you can
begin the DATATRIEVE installation procedure from the beginning. If LSE is
already installed on your system, you will be prompted with the following:
LSE is installed on your system.
You now have the following options:

Do a complete VAX DATATRIEVE installation including
VAX DATATRIEVE support for LSE.

Do only VAX DATATRIEVE support for LSE without
installing VAX DATATRIEVE.

Select option [1]:

VN< DATATRIEVE Installation Procedure

2-7

If you want to install a new version of DATATRIEVE (including LSE support),
select option 1. If you want only to provide DATATRIEVE support for LSE
(without installing a new version of DATATRIEVE), select option 2. If you

select option 2, this installation will terminate after DATATRIEVE support for
LSE is provided.

2.5.3

Installing with Support for Forms Products

Each installation of DATATRIEVE on a system can support only one of two
forms management products. These products are:
• TDMS (Terminal Data Management System)
• FMS (Forms Management System)
A series of questions determines which product DATATRIEVE will support for
the image currently being installed.
The installation procedure checks which forms management products are on
the system. If no forms products are found (or only lower versions of TDMS
or FMS not supported by DATATRIEVE are found), the installation procedure
displays the following message:
**************************************************************
No Forms Management product has been found on this
system. If desired, the installation may be aborted
at this point to install a Forms Management product.
If the installation continues, VAX DATATRIEVE will
be built without Forms Management support.
**************************************************************
*Do you wish to continue with the installation [YES]?

If you type Y or press the RETURN key, the installation continues with

the series of questions about more than one installation of this version of
DATATRIEVE. (See Section 2.5.4 for more information.)
If you type N, the installation aborts, giving you an opportunity to install a

forms product on your system.
If one or more forms products are found, you receive a listing of the products

on your system, followed by a message and question similar to the following:
VAX DATATRIEVE can be built to support any one
of these products, or, if desired, VAX DATATRIEVE
can be built without support of any of these Forms
Management products.
*Do you want DATATRIEVE to support one of these products [YES]?

If you do not want forms support, enter N. The installation procedure resumes

with questions on suffixes and more than one installation of this version of
DATATRIEVE.

2-8

VAX DATATRIEVE Installation Procedure

If you do want forms support, enter Y or press the RETURN key. Then, for

each forms product on the system, you are asked if you want DATATRIEVE to
support this forms product. Remember each installation of DATATRIEVE can
support only one forms product. After you enter Y to specify support for one
forms product; you do not receive questions about the other forms products,
For example, if you have both TDMS and FMS on the system, you receive the
following question first:
*Do you wish to have TDMS Forms Management support [YES]?

If you type Y or press the RETURN key, the DATATRIEVE image being

installed will support TDMS. Then the installation procedure moves .on to a
series of questions on suffixes and more than one installation of this version of
DATATRIEVE.
If you type N, you receive a question about support for FMS.
If you type N after each question in the series, you receive the following

message:
There are no other Forms Management products on this
system. If desired, the installation may be aborted
at this point to install a Forms Management product.
If the installation continues, the questions pertaining
to the selection of a Forms Management product will
be asked again.
*Do you wish to continue with the installation [YES]?

If you type Y or press the RETURN key, you have another opportunity to
answer questions about forms. If you type N, the installation procedure aborts.

2.5.4 Specifying Suffixes for More than One Installation of this
Version of VAX DATATRIEVE
The installation procedure asks whether you intend to complete more than one
installation of this version of DATATRIEVE on your system, as follows:
It is possible to do more than one installation of this
version of VAX DATATRIEVE. More than one installation of a
single version may be desirable for a number of reasons
including:
o

Use of multiple forms management products

Use of multiple foreign language translations of VAX
DATATRIEVE (such as French or German)

*Do you plan to install this version more than once [NO]?

VAX DATATRIEVE Installation Procedure

2-9

If you type N or press the RETURN key, the installation procedure continues
with questions about retaining DATATRIEVE files. (See Section 2.5.5 for more
information.) At a later date, you can decide to install DATATRIEVE using
file names other than the defaults by typing Yin response to the previous
question.
If you type Y, the installation procedure displays messages requesting that you
specify a suffix for the image you are installing and the default image for the
DCL command DATATRIEVE.

The following message and question about the suffix are displayed:
To differentiate the files and images produced by this
installation from those produced by some other
VAX DATATRIEVE installation, it is necessary to append a
suffix to some of the file and image names. For each
installation of this version of VAX DATATRIEVE, this suffix
should be unique. This suffix can be 1 to 26 characters.
*What is the suffix you intend to use for this installation [none]?

Only one set of DATATRIEVE images and files can use the default file names
that have no suffix. (See Section 1.5.4 for a list of these images and files.) If
you install this version of DATATRIEVE a second or subsequent time, you
should identify the subsequent image and file names by a unique suffix. This
step allows you to later identify which version of DATATRIEVE you want to
run.
For example, on the first run through the installation procedure, you could
respond to the question about the suffix by pressing the RETURN key. The
result is that each of the DATATRIEVE file names includes no suffix. To run
the image produced by this procedure, type:
$ RUN SYS$SYSTEM:DTR32

During the second or subsequent installation of this version of DATATRIEVE,
for example, you might use TDMS as the forms product supported by this
image. You could uniquely identify the files and images by responding with
TDMS for the suffix. To run the image produced by this procedure, type the
following line:
$ RUN SYS$SYSTEM:DTR32TDMS

If you specify the same suffix for a later installation, the later image
supersedes the previous image installed with the same suffix. If you choose to
purge files during the installation, those earlier images will be deleted. See
Section 2.5.10 for more information.

For the remainder of this manual, the two letters xx at the end of a file name
stand for the 1- to 26-character suffix you specify.

2-10

VAX DATATRIEVE Installation Procedure

You can invoke DATATRIEVE with either the RUN command or the DCL
command DATATRIEVE. The installation procedure allows you to choose which
DTR32 image will be executed by default by the DATATRIEVE command. The
following message and question are displayed:
The DATATRIEVE DCL command allows you to choose which DTR32 image
to execute by means of the /VARIANT qualifier. You may now choose
an image to be executed by default, when the /VARIANT qualifer
is not specified on the DATATRIEVE command. This default image
will be the image referenced by DCL HELP.
DTR32, DTR32xx

* Which of the above images should be the default [DTR32xx] :

The installation procedure checks which DATATRIEVE images are on the
system. All existing image names, plus the name of the image you are
currently installing, are listed. The current image name is provided as the
default response to the question.
Only one DATATRIEVE image can be chosen as the default for the DCL
command DATATRIEVE. You must use the NARIANT qualifier to invoke any
other DATATRIEVE image using the DCL command DATATRIE\lE.
For example, on the first run through the installation procedure, you could
respond to both the question about the suffix and the question about the DCL
default by pressing the RETURN key. The result is that the image name is
DTR32 and that image is the default when you invoke DATATRIEVE using the
DCL command DATATRIEVE as follows:
$ DATATRIEVE

During the second or subsequent installation of this version of DATATRIEVE,
you might choose TDMS as the suffix. You might then choose DTR32 as the
default image name with the DCL command DATATRIEVE. You can use the
DCL command DATATRIEVE to invoke the DTR32TDMS image as follows:
$ DATATRIEVE/VARIANT=TDMS

If, however, you choose DTR32TDMS as the default with the DATATRIEVE
DCL command, you must use the VARIANT qualifier to invoke the DTR32
image as follows:
$ DATATRIEVE/VARIANT

VAX DATATRIEVE Installation Procedure

2-11

2.5.5

Deleting the DATATRIEVE Object Library

The installation procedure asks whether you want to keep the DATATRIEVE
object library on disk in DTR$LIBRARY. The following question is displayed:
*Do you wish to leave the DATATRIEVE library on line [NO]?

~f5:5,,

If you do not want to keep the DATATRIEVE library on line, type N or press

the RETURN key. Type Y if you want to keep the library files.
u should keep the library on line if you anticipate having to relink this
mage of DATATRIEVE. If you do not keep the library files on line and later
ed to relink DATATRIEVE, you must reinstall this kit.
You have to relink DATATRIEVE if you:
• Add a user-defined function
• Customize the text file DTRTEXT.MAR

---->7- Install or patch a new version of CDD/Plus
• Install a new version of the VAX Run-Time Library
• Install a new version of FMS
If you keep the library on line, you may enter the following command to relink

DATATRIEVE:
~$

... ~/

@DTR$LIBRARY:DTRBLDxx

2.5.6 Defining the DATATRIEVE Remote Server
The installation procedure checks if the DATATRIEVE remote server has
been defined by previous installations of DATATRIEVE. The remote server for
DATATRIEVE is called the Distributed Data Manipulation Facility (DDMF).
Although there can be several shareable images of DATATRIEVE installed on
the same system, there can be only one remote server for each system.
Note You do not receive the question discussed in this section if you are installing

DATATRIEVE on a VMS system without DECnet. If you later install DECnet,
you then need to define a DECnet object for the remote server. See Section 3.4
for more information on defining a DECnet object.
If no remote server has been defined previously or if a previously-defined

remote server is obsolete, the DDMF files from this installation become
the remote server for DATATRIEVE on the system. You do not receive a
question about the remote server, and the installation procedure continues with
questions about the file for new users. See Section 2.5. 7 for more information.

2-12 VAX DATATRiEVE instaiiation Procedure

However, if an up-to-date remote server has already been defined (by
a previous installation of this DATATRIEVE release, for example), the
installation procedure asks if the remote server established by the current
installation should be the remote server for the system. The DECnet object
the following question:
*Do you want DDMFxx.EXE to be used for distributed access [NO]?

Type Y if you want the remote server (DDMF) established by the current
installation to be the remote server for your system. You might want to type Y
if this image will contain options that users on remote systems need to access
frequently, for example, user-defined functions that PDP-11 users need to
access. In such cases, it is more efficient to make the remote server file for this
image the remote server for your system.
Type N or press the RETURN key if these considerations do not apply to this
installation of DATATRIEVE.

2.5.7

Creating a DCL Command File for New Users

The installation procedure continues with questions about the new user
file. The new user file, NEWUSER.COM, helps new users get started with
DATATRIEVE. It provides the necessary files to perform the examples in the
DATATRIEVE documentation set. The NEWUSER.COM file is installed in
DTR$LIBRARY. Users can invoke the NEWUSER command file by entering:
$ @DTR$LIBRARY: NEWUSER

There are three questions associated with the NEWUSER.COM file; however,
you may not be asked all three. To determine which questions you will
be asked, the installation procedure checks if your system has a current
NEWUSER.COM in DTR$LIBRARY.
If the installation procedure does not find a NEWUSER.COM file, you will

not be asked the first question. The procedure automatically installs the
NEWUSER.COM file on your system. This might occur if you are installing
DATATRIEVE for the first time. The installation procedure continues with the
two remaining questions in this section that allow you to specify information
about parent directories for users of NEWUSER.COM.
If the installation procedure finds a NEWUSER.COM file from a previous

installation of DATATRIEVE, you receive the following question:
*Do you want to replace the NEWUSER file [NO]?

VIV<. DATATRIEVE Installation Procedure 2-13

Your answer to this question is determined by one of the following situations:
• If you have not installed DATATRIEVE since Version 3.4, you must type Y
to use the NEWUSER.COM file. If you type N, the NEWUSER.COM file is

not replaced; therefore:
You will not be able to use the NEWUSER.COM file because new user
files before Version 4.0 are not compatible with Version 5.0.
You will not be prompted with the two remaining questions in this
section.
• If you have already installed DATATRIEVE Version 4.0 or higher, you can
answer either Nor Y. If you type N, the NEWUSER.COM is not replaced;

however:
A DTR32xx.EXE image from a previous installation of DATATRIEVE
(Version 4.0 or higher) may be used for NEWUSER.COM.
The installation procedure will not prompt you for the two remaining
questions in this section.
If you answer Y in either of these two situations, the NEWUSER.COM file is

replaced. In addition:
• The DTR32xx.EXE image from this installation of Version 5.0 is used for
NEWUSER.COM.
• The installation procedure continues with the two remaining questions in
this section that deal with CDD/Plus directories.
If you have chosen to replace NEWUSER.COM or if NEWUSER.COM is
automatically installed, the installation procedure asks the following two
questions concerning the CDD/Plus DMU format directories for new user files.
These questions allow you to determine the way new user directories are
established and the name of the parent CDD/Plus directory for new user files.

The installation procedure prompts you with the following question:
*Do you want NEWUSER to create CDD/Plus directories for new users [YES]?

Answer Y or press the RETURN key if you want to create CDD/Plus
directories. A new user of DATATRIEVE can then invoke the file
DTR$LIBRARY:NEWUSER.COM after the installation. NEWUSER creates
a CDD/Plus directory for the new user if one does not already exist. The
directory is created in the DMU format dictionary, since the contents must
be stored in DMU format. The directory is comprised of the parent directory
specified in the next question and the new user's VMS user name. For
example, if the parent directory is CDD$TOP.DTR$USERS and user SMITH
invokes NEWUSER, SMITH gets the following:
• A logical CDD$DEFAULT directory, CDD$TOP.DTR$USERS.SMITH

2-14 VAX DATATRiEVE Installation Procedure

• Several CDD/Plus DMU format entries, such as YACHTS and FAMILIES,
in the CDD$DEFAULT directory
• A number of data files, such as YACHT.DAT and FAMILY.DAT, in user
SMITH's default VMS directory
If you answer N to this question, NEWUSER does not create a CDD/Plus
directory for the new user. NEWUSER loads the sample domain and record
definitions in the node defined by the logical name CDD$DEFAULT. If the new
user has not defined this logical name, NEWUSER issues an error message
and terminates the procedure.
Note If you answer N to this question, ensure that users who want the new user files

define the logical name CDD$DEFAULT to point to a DMU format dictionary
directory with a path name beginning with CDD$TOP.
If you indicate that you want NEWUSER to create CDD/Plus directories
for new users, you are asked to name the parent CDD/Plus directory. The
following question is displayed:

* What would you like the parent dictionary directory
to be [CDD$TOP.DTR$USERS]?

If you want the parent directory to be CDD$TOP.DTR$USERS, press the
RETURN key. Otherwise, enter some other full CDD/Plus directory path
name. If your path name does not begin with CDD$TOP, you receive an
informational message and are prompted again for the full path name.

2.5.8

Installing Shared Images

DATATRIEVE runs most efficiently when all its executable images are
installed as shareable images. The installation procedure lets you choose
not to do so, however. The installation procedure prompts you with the
following question. Note that the file SYS$STARTUP:DTRSTUPxx.COM is
built according to your responses.
*Do you want DTRSHRxx.EXE and DTRMSGS.EXE to be installed SHARED [YES]?

For best performance, the images DTRSHRxx.EXE and DTRMSGS.EXE should
be installed as SHARED. Type Y or press the RETURN key if you want these
images to be installed as SHARED.
The second question about shareable images refers to DTR32xx.EXE. For best
performance, this should also be installed as SHARED.
*Do you want DTR32xx.EXE to be installed SHARED [YES]?

Type Y or press the RETURN key if you want this image to be installed
SHARED.

VN< DATATRIEVE Installation Procedure

2-15

For best performance in environments where you anticipate extensive use of
the distributed features of DATATRIEVE, the image DDMFxx.EXE should
also be installed as SHARED. If the DDMF from this installation is to be the
remote server, you receive the following question:
*Do you want DDMFxx.EXE to be installed SHARED [YES]?

Type Y or press the RETURN key if you want this image to be installed as
SHARED.
Note You do not receive the question about DDMFxx.EXE if you are installing

DATATRIEVE on a system that does not have DECnet. If you later install
DECnet, see Section 3.4 for instructions on running the DDMFxx.EXE image as
SHARED.

2.5.9

Installing Plot Definitions and Optional Material

The installation procedure continues with a question about plot definitions for
DATATRIEVE graphics. DATATRIEVE contains graphics features you can use
with a VT125, VT240, VT330, or VT340 terminal or on a workstation. To use
these features, you must request plot definitions during installation.
Note If this is your first installation of DATATRIEVE since Version 3.4, you must

answer Y to the following question. The plot definitions were modified with
Version 4.0. Plot definitions provided with DATATRIEVE installations prior to
Version 4. 0 are not compatible with DATATRIEVE Version 5. 0.
The following question is displayed:
*Do you wish to have the plot definitions [YES]?

Type Y or press the RETURN key if you want the installation procedure to
include plot definitions. The plot definitions are installed in a CDD/Plus DMU
dictionary, in CDD$TOP.DTR$LIB.PLOTS. They replace the plot definitions of
lower versions.
The next question pertains to components of DATATRIEVE that can be
tailored at the installation site. This material includes the DATATRIEVE text
and message files, as well as sample programs and callable DATATRIEVE
programming aids that are the basis for many examples in the DATATRIEVE
documentation.
The following message and question are displayed:
Some optional material is available with this kit including the
components of VAX DATATRIEVE that can be tailored at the installed
site.
*Do you want the optional material [NO]?

Type Y if you want this material. The installation procedure loads these files in
DTR$LIBRA..."l:{Y. If you do not want this material, type N or press the RETURN
key.

2-16 VAX DATATRIEVE Installation Procedure

After you respond to this question, the installation procedure continues
with a question about deleting obsolete files from previous installations of
DATATRIEVE.

2.5. l 0 Deleting Obsolete Files
If any prior releases of DATATRIEVE are installed on your system, some
files you are currently using have been made obsolete with this version of
DATATRIEVE.

The following message is displayed:
This version of VAX DATATRIEVE makes obsolete some files
from previous versions of VAX DATATRIEVE.
*Do you want ALL the obsolete files deleted [YES]?

Answer Y or press the RETURN key to delete obsolete files. If you answer N,
all obsolete files are retained in the system directories where they reside. All
files created and deleted by this installation procedure are listed in the file
DTR$LIBRARY:DTRnnn.DAT. (For example, for Version 5.0 of DATATRIEVE,
the file DTR$LIBRARY:DTR050.DAT contains the listing for this installation.)
Following installation, you can edit a copy of DTRnnn.DAT to create a
command file that deletes any of the listed files that you do not wish to
keep. After you respond to this question, the installation procedure asks the
following:
*Do you want to purge files replaced by this installation [YES]?

If you wish, you can have all files that were created by this installation
procedure purged in the variums directories where they were created. No
files are purged except those created in this installation. Type Y or press the
RETURN key to purge the files.

2.6 Finishing the Installation
If you did not request the default installation, the following message is
displayed:
All questions regarding the installation have now been asked.
The installation of VAX DATATRIEVE will now continue for
10 minutes to 30 minutes.

VAX DATATRIEVE Installation Procedure

2-17

If this release of DATATRIEVE includes changes to the sample functions, the
installation procedure displays the following message:
An existing DTRFNDxx.MAR has been found
on the system, but its version does not
match the current level for this installation.
The existing DTRFNDxx.MAR and DTRFUNxx.OLB
have been respectively renamed to
DTR$LIBRARY:DTRFNDxx.OLD and
DTR$LIBRARY:DTRFUNxx.OLD.

See Section 3.5 for more information on maintaining user-defined functions.
See the VAX DATATRIEVE Release Notes for Version 5.0 for information on
changes to the operation of the function library.
During installation, you should receive the following message:
During the installation, a file called
DTRSTUPxx.COM has been added to SYS$STARTUP:
The site-dependent startup file, SYS$MANAGER:SYSTARTUP_V5.COM,
should have the following line added:
$ @SYS$STARTUP:DTRSTUPxx.COM

Be sure to update SYS$MANAGER:SYSTARTUP_V5.COM after installation.
The installation procedure next displays information about User Environment
Test Packages (UETPs). The installation provides up to five UETPs, depending
on the optional products already on the system (TDMS, FMS, VAX DBMS,
RdbNMS, and so on) and your responses to the questions about forms products
and plots. Besides a general test of DATATRIEVE, there are also UETPs for
plots, forms, RdbNMS, and VAX DBMS.
The installation displays a message showing how to invoke each UETP it
provides:
*************************************************************
VAX DATATRIEVE User Environment Test Packages (UETPs)
have been provided and can be run after the installation is
complete. They are invoked from VAX DATATRIEVE as follows:
DTR>
DTR>
DTR>
DTR>
DTR>

@sys$common: [systest.dtr]dtr
@sys$common:[systest.dtr]plots
@sys$common: [systest.dtr]dbms
@sys$common: [systest.dtr]rdb
@sys$common: [systest.dtr]forms

The general test
The plots test
The VAX DBMS test
The Rdb/VMS test
The Forms test

*************************************************************

The file type for the UETP files in the directory SYS$COMMON:[SYSTEST.DTR]
is .DTR.
Chapter 4 discusses the test packages.

2-18

VAX DATATRIEVE lnstaliation Procedure

The installation procedure now runs the general IVP test and displays the
following message:
Executing IVP for:

VAX DATATRJ:EVE

VS.a

Running the general IVP test ...
Test completed successfully
*************************************
VAX DATATRIEVE VS.a
IVP COMPLETED SUCCESSFULLY
*************************************
IVP completed for:

VAX DATATRIEVE VS.a

Note The PAK must be registered before either the NP or any of the UETPs can be

run. If you answered no to the following question, the NP will not be run at
this time:
* Does this product have an authorization key registered and loaded?
If the account you are using to install DATATRIEVE has an ENQLM quota
under 500, the installation procedure displays the following information:
Your ENQLM quota is less than saa; this will be too low for the sample
Rdb/VMS database to be restored. Reinstall VAX DATATRIEVE to build
that database after increasing your ENQLM.

If your system has RdbNMS and has an ENQLM over 500, the installation
procedure now builds the sample RdbNMS database. The procedure displays
the following message as the procedure builds the database:

VAX DATATRIEVE Installation Procedure

2-19

Restoring VAX DATATRIEVE demonstration RDB/VMS database
Exported by Rdb/VMS V3.0A-0 Export/Import utility
A component of Rdb/VMS V3.0A-0
Previous name was dtr$library:personnel.rdb
It was logically exported on 27-FEB-1989 09:48
Database NUMBER OF USERS is 50
Database NUMBER OF VAXCLUSTER NODES is 16
Database NUMBER OF DBR BUFFERS is 20
Database SNAPSHOT is ENABLED
Database SNAPSHOT is IMMEDIATE
Database BUFFER SIZE is 6 blocks
Database NUMBER OF BUFFERS is 20
IMPORTing relation COLLEGES
IMPORTing relation DEGREES
IMPORTing relation DEPARTMENTS
IMPORTing relation EMPLOYEES
IMPORTing relation JOBS
IMPORTing relation JOB HISTORY
IMPORTing relation SALARY HISTORY
IMPORTing relation WORK STATUS
Installation of DTR V5.0 completed at 17:24

Note You might receive one or more DECnet error messages during this part of the

installation procedure. You can ignore these messages.
When the installation procedure is finished, control returns to the command
procedure VMSINSTAL.

2-20 VAX DATATRIEVE Installation Procedure

3
Postinstallation Considerations

(! ~~~~:~:~m~oP!f~~~id~~::"-· concerning DECnet, relational databases, V&X DBMS databases, and
user-defined functions.

3.1

Updating SYS$MANAGER:SYSTARTUP_VS.COM
During installation, a file called DTRSTUPxx.COM was added to
SYS$STARTUP. Note that xx represents the 1- to 26-character suffix you
specify during installation. After installation, you must update the sitedependent startup file SYS$MANAGER:SYSTARTUP_V5.COM by adding the
following line:
$ @SYS$STJ'""RTUP: DTRSTUPx~~. COM

3.2 VAXcluster Considerations
If you are installing DATATRIEVE on a VAXcluster, the shareable image
created by this installation of DATATRIEVE is available only from the node
where the installation is done. Therefore, after the installation is complete, you
should repeat the following steps on each of the other nodes in the VAXcluster
where DATATRIEVE will be used:

Issue the LICENSE LOAD command to activate the VMS license.
2

Execute the DATATRIEVE startup command file as follows:
$

@SYS$STARTUP: DTRSTUPxx. COM

Install the new version of DCLTABLES.EXE that has been updated to
include the DCL command DATATRIEVE. Install the file as follows:
$ INSTALL
INSTAL> REPLACE SYS$SHARE:DCLTABLES

Postinstallation Considerations 3-1

The second step is not necessary if you plan to reboot the entire VAXcluster
after the installation is complete.

3.3 Updating Process Command Tables
The DATATRIEVE Version 5.0 installation creates a new version of
DCLTABLES.EXE including the DCL command DATATRIEVE. To use the
DCL command DATATRIEVE, users must log out of their processes and log
back in to update their process command tables.

3.4 DECnet Considerations
This section describes what you need to do to run the DATATRIEVE remote
server if DECnet is installed after DATATRIEVE on a VMS system. It
also describes how to create a default DECnet account for remote users of
DATATRIEVE on your system.

3.4. 1 Defining a DECnet Object
DECnet is normally installed on a VMS system. Unless you install
DATATRIEVE on a VMS system without DECnet, the installation procedure
automatically defines a DECnet object for the DATATRIEVE remote server.
However, if you install DATATRIEVE on a VMS system that does not have
DECnet, the installation procedure cannot use the DECnet Network Control
Program (NCP) utility to define a DECnet object.
This section describes how to use NCP to define a DECnet object for the remote
server if DECnet is installed on your system after DATATRIEVE is installed.
The remote server for DATATRIEVE is called the Distributed Data
Manipulation Facility (DDMF). The installation procedure creates two files,
DDMFxx.EXE and DDMFxx.COM, in SYS$SYSTEM. To define a DECnet
object for DDMFxx.EXE and assign it an object number of 30, type the
following commands:
$
$
$
$
$

NCP
NCP
NCP
NCP
NCP

"$NCP"
DEFINE OBJECT DDMF NUMBER 30
SET OBJECT DDMF NUMBER 30
DEFINE OBJECT DDMF FILE DDMFxx.COM
SET OBJECT DDMF FILE DDMFxx.COM

For best performance in environments where you anticipate extensive use of
the distributed features of DATATRIEVE, you should run the remote server as
SHARED. To run the image DDMFxx.EXE as a SHARED image, edit the file
SYS$STARTUP:DTRSTUPxx.COM. This file begins with the following lines:
$!+
$!
$!-

VAX DATATRIEVE Start-up File

3-2 Postinstallation Considerations

Check the file for the following line and add it if it is not already there:
$ DTR$INSTALL := $SYS$SYSTEM:INSTALL/COMMAND_MODE

You will see a dollar sign and the word exit at the end of the file. Enter the
following text on the line above $ exit:
ADD/OPEN/SHARED SYS$SYSTEM:DDMFxx.EXE

3.4.2

Creating a Default DECnet Account for Distributed
Access

The installation procedure defines a DECnet object called DDMF and assigns
it the number 30. After the installation, you may want to create a default
DECnet account, such as DECNET_DTR, for this DECnet object. Remote users
can then omit the user name and password from the node specification when
accessing domains on your node.
Note This section applies to systems on which DECnet was installed before

DATATRIEVE. If DATATRIEVE is installed on a VMS system that does
not have DECnet, you cannot define a default DECnet account. If DECnet is
later installed, you must define a DECnet object (see Section 3.4.1) before you
can create a default DECnet account.
If you wish to set up such a default DECnet account for distributed access,
follow these steps:

Add an entr; to the user authorization file (UAF) on your system for
DECNET_DTR. Specify the same file limits and quotas as you would for
any other DATATRIEVE user.
2

Invoke NCP to associate DDMF (known object 30) with the default DECnet
account DECNET_DTR. Use the DEFINE OBJECT command in NCP to
modify the object parameters for DDMF in the permanent database on
your system.

You can use the following sample session as a model for your own system. Note
that for security reasons, you should use a different password than the one
provided.

Postinstallation Considerations 3-3

$ auth == "$authorize"
$ ncp == "$ncp"
$ set default sys$system
$ auth
UAF>ADD DECNET DTR/OWNER="VAX
DATATRIEVE"/PASSWORD=choose_your_password
user record successfully added
UAF>MODIFY DECNET_DTR/DEVICE=SYS$SYSDEVICE/DIRECTORY=[DECNET_DTR]
user record(s) updated
UAF>MODIFY DECNET_DTR/UIC=[376,376]
user record(s) updated
UAF>MODIFY DECNET_DTR/FILLM=30/ENQLM=200 !or 500 for Rdb/VMS users
user record(s) updated
UAF>MODIFY DECNET_DTR/WSDEFAULT=350/WSQUOTA=350
user record(s) updated
UAF>MODIFY DECNET_DTR/FLAGS=(DISCTLY, DEFCLI, LOCKPWD, CAPTIVE)
UAF>SHOW DECNET DTR
Username: DECNET DTR
Owner: VAX DATATRIEVE
Account:
[376, 376) ( [376, 376))
UIC:
CLI:
DCL
Tables: DCLTABLES
Default: SYS$SYSDEVICE: [DECNET_DTR]
LGICMD:
LOGIN
Login Flags: Disctly Defcli Lockpwd Captive
Primary days:
Mon Tue Wed Thu Fri
Secondary days:
Sat Sun
No access restrictions
Expiration:
(none)
Pwdminimum:
6
Login Fails: 0
Pwdlifetime:
180 00:00
Pwdchange:
(pre-expired)
Last Login: (none) (interactive),
(none) (non-interactive)
Maxjobs:
0 Fillm:
30 Bytlm:
4096
Maxacctjobs:
0 Shrfillm:
0 Pbytlm:
0
Maxdetach:
0 BIOlm:
18 JTquota:
1024
Prclm:
2 DIOlm:
18 WSdef:
350
Prio:
4 ASTlm:
24 WSquo:
350
Queprio:
0 TQElm:
10 WSextent:
1000
CPU:
(none) Enqlm:
500 Pgflquo:
10000
Authorized Privileges:
TMPMBX NETMBX
Default Privileges:
TMPMBX NETMBX
UAF>EXIT
SYSUAF.DAT modified
$ CREATE/DIR/OWN= [376,376] SYS$SYSDEVICE: [DECNET_DTR]
$ ncp
NCP> LIST OBJECT DDMF
Object Permanent Summary as of

31-0CT-1989 15:31:09

Object = DDMF
Number
File id

3-4

Postinstallation Considerations

30
DDMF.COM

NCP>DEFINE OBJECT DDMF USER DECNET DTR PASSWORD YACHTS
NCP>LIST OBJECT DDMF
Object Permanent Summary as of
Object

31-0CT-1989 15:31:09

DDMF

Number
File id
User id
Password

30
DDMF.COM
DECNET DTR
YACHTS

NCP>SET KNOWN OBJECTS ALL
NCP>EXIT
$

For more information on NCP and DECnet, see the VMS documentation on
networking.

3.5 Maintaining User-Defined Functions
If this is your first installation of VAX DATATRIEVE since Version 4.1, and

if your site maintains site-specific or user-defined functions, then you should
complete the following steps to reenable user-defined functions.
After an initial installation of DATATRIEVE Version 4.2 or higher,
DATATRIEVE will always use the DTRFNDxx.MAR and DTRFUNxx.OLB
files that are on the system. You will no longer have to re-create and relink
DATATRIEVE as described in this section.
Transfer the user-defined function definitions from DTRFNDxx. OLD
(renamed during installation) to DTRFNDxx.MAR. To do this, edit
DTRFNDxx.MAH. and add the appropriate definitions. (Merely renaming
the old file does not enable user-defined functions in the file. They must be
transferred to DTRFNDxx.MAR.)

Assemble DTRFNDxx.MAR with the MACRO command:
$ MACRO DTR$LIBRARY:DTRFNDxx.MAR

This command creates the object file DTRFNDxx.OBJ.
3

Replace the object module in the function library with the newly created
object file:
$ LIBRARY/REPLACE DTR$LIBRARY:DTRFUNxx DTRFNDxx

Skip to the next step if the user-defined functions for your site consist
only of calls to Run-Time Library routines. However, if your site has
user-defined functions that call their own routines, there is an additional
step before relinking DATATRIEVE. The object files for those functions
routines must be inserted into the new version of the function library.

Postinstallation Considerations 3-5

There are two ways to do this:
• If the object files (.OBJ files) for the routines are still available, insert

them directly into the function library:
$ LIBRARY/INSERT _$
DTR$LIBRARY:DTRFUNxx.OLB filename.OBJ

•

If the object files for the routines are not available, extract the modules

from the old function library before inserting them into the new:
$ LIBRARY/EXTRACT=module-name/OUTPUT=filename.OBJ $
DTR$LIBRARY:DTRFUNxx.OLD
$ LIBRARY/INSERT _$
DTR$LIBRARY:DTRFUNxx.OLB filename.OBJ

Relink DATATRIEVE:
$ @DTR$LIBRARY:DTRBLDxx

Note If your site maintains no user-defined functions, you may choose to delete the

.OLD files.

3.6 Deleting Unused Files for DATATRIEVE DECwindows
Support
If the DATATRIEVE DECwindows interface is not required at your site,

you can delete the following files after the DATATRIEVE installation has
successfully completed:
• SYS$SYSROOT:[SYSEXE]DTRHELP.EXE
• SYS$SYSROOT:[SYSLIB]DTR$CDDTSHR.EXE
• SYS$SYSROOT:[SYSHLP]DTRDECW$HELP.HLB
• SYS$SYSROOT:[SYSLIB]VAX_DATATRIEVE.UID
• SYS$SYSROOT:[DTR]REMOTE_DECTERM.COM
If you delete any of the DATATRIEVE DECwindows files, ensure that you

delete all of the listed files.
After the DATATRIEVE DECwindows interface files are deleted, remove all
references to these files from each of your SYS$STARTUP:DTRSTUPxx.COM
files.

3-6 Postinstallation Considerations

4
User Environment Test Packages
Five User Environment Test Packages (UETPs), which show examples and
test product interfaces, are provided with DATATRIEVE. You can run the
UETPs after you install DATATRIEVE. The following UETPs are provided
\vith DATATRIEVE:
• DATATRIEVE
• DATATRIEVE graphics capability
• DATATRIEVE and VAX DBMS interface
• DATATRIEVE and RdbNMS interface
• DATATRIEVE and FMS or TDMS interface
Appendix B of the VAX DATATRIEVE User's Guide includes the data
definitions and procedures used in the UETPs.
Note You must run the DATATRIEVE UETP before running any other UETP. The

DATATRIEVE UETP creates data definitions used by the other UETPs.

4.1

Invoking DATATRIEVE
To run the UETPs; you must first invoke DATATRIEVE in one of the following
ways:
• Use the DCL command RUN as follows:
$ RUN SYS$SYSTEM:DTR32xx.EXE

The xx represents the 1- to 26-character optional suffix added to an image
of DATATRIEVE at installation.

User Environment Test Packages 4-1

• Use a symbol you have defined to represent the RUN command. For
example:
$ DTR32

• Use the DCL command DATATRIEVE, as follows:
$ DATATRIEVE

The DCL command DATATRIEVE is useful if you are working in a
DECwindows environment. You should not run the UETPs using the
DATATRIEVE DECwindows interface, as you may get unexpected results.
By using the DATATRIEVE command to invoke DATATRIEVE, you
can specify the /INTERFACE=CHARACTER_CELL qualifier to invoke
DATATRIEVE without the DECwindows interface.
If you have installed more than one DATATRIEVE image, you can specify
the NARIANT=image-suffix qualifier to run the image of DATATRIEVE
you want to test.
To invoke DATATRIEVE using these qualifiers, enter the following
command:
$ DATATRIEVE /INTERFACE=CHARACTER_CELL/VARIANT=xx

The characters xx represent the 1- to 26-character suffix added at
installation to identify a particular image of DATATRIEVE Version 5.0.
At the DTR> prom pt, enter the command to execute the UETP you want
to run. The UETPs and the commands to invoke them are described in the
following sections.

4.2 VAX DATATRIEVE UETP
To run the DATATRIEVE UETP, invoke DATATRIEVE as described in
Section 4.1 and type the following command:
DTR> @SYS$GOMMON: [SYSTEST.DTR]DTR

The DATATRIEVE UETP is approximately 20 pages long, so the entire UETP
is not repeated here.
You respond to prompts during the DATATRIEVE UETP. The parts of the
UETP that require a response are included here along with suggested
responses. The responses you enter are printed in colored ink.
Note The DATATRIEVE UETP suggests at one point that you use LP: to print a

report directly to a line printer. The LP: option may not work unless LP is
defined as the system printer.

4-2 User Environment Test Packages

TEST STORE
PLEASE SUPPLY THE FOLLOWING VALUES:
MANUFACTURER:
HINKLEY
MODEL:
BERMUDA 40
RIG:
YAWL
* LENGTH-OVER-ALL:
140
LENGTH-OVER-ALL:
40
DISPLACEMENT:
20000
BEAM:
12
82000 AND XX/100
* PRICE:
PRICE:
$82,000
CONFIRM:
N
Values marked with "*" will generate an error and be reprompted
STORE YACHTS :VERIFY
Enter MANUFACTURER: HINKLEY
Enter MODEL: BERMUDA 40
Enter RIG: YAWL
Enter LENGTH OVER ALL: 140
Validation error for field LENGTH OVER ALL.
Re-enter LENGTH-OVER-ALL: 40
Enter DISPLACEMENT: 20000
Enter BEAM: 12
Enter PRICE: 82000 AND XX/100
Non-digit in string "82000 AND XX/100", ignoring character(s).
Re-enter PRICE: $82,000
LENGTH
r"l't'Tr."n

VVJ..:Jl.\.

MANUFACTURER

MODEL

RIG

ALL

WEIGHT BEAM

HINKLEY
BERMUDA 40 YAWL
40
20,000
DISPLAY: IF RECORD IS OK, CONFIRM WITH Y
Enter CONFIRM: N
Invoke report

(suggest

TT:

PRICE
$82,000

as output file)

:LOA-REPORT
Enter FILE: TT

At this point, a report is displayed on the screen. When the report finishes, the
UETP continues:
Invoke report (suggest

LP:

as output file)

:LOA-REPORT
Enter FILE: LP:

User Environment Test Packaoes 4-3

At this point, the procedure sends a report to the line printer and the UETP
continues:
READY YACHTS MODIFY
! RESPOND WITH 47

(or any two digit value)

MODIFY BEAM
Enter BEAM: 4 7
PRINT TYPE,BEAM
MANUFACTURER
METALMAST

MODEL
GALAXY

BEAM
47

! RESPOND WITH 48 (or any two digit value)

MODIFY ALL BEAM
Enter BEAM: 48
PRINT ALL BEAM
BEAM
48
48
48
48
48

Respond each time with 0 (please)
FOR CURRENT PRINT TYPE THEN MODIFY BEAM
MANUFACTURER

MODEL

METALMAST
GALAXY
Enter BEAM: 0
O'DAY
32
Enter BEAM: 0
RYDER
s. CROSS
Enter BEAM: 0
TA CHIAO
FANTASIA
Enter BEAM: 0
SEAWIND I I
WRIGHT
Enter BEAM: 0
SET ABORT
READY YACHTS READ
PRINT ALL

(continued on next page)

4-4 User Environment Test Packages

MANUFACTURER

MODEL

RIG

LENGTH
OVER
ALL
DISPLACEMENT BEAM

METALMAST
O'DAY
RYDER
TA CHIAO
WRIGHT

GALAXY
32
s. CROSS
FANTASIA
SEAWIND II

SLOOP
SLOOP
SLOOP
SLOOP
SLOOP

32
32
31
35
32

9,500
11, 000
13,600

231200
14,900

00
00
00
00
00

PRICE

$29:500
$32,500
$34,480

The installation is successful if you receive the following message at the end of
the UETP:
The VAX DATATRIEVE User Environment Test
Package has completed successfully.

4.3 VAX DATATRIEVE Graphics UETP
You must run the DATATRIEVE graphics UETP on a VT125, VT240, VT330,
or VT340 terminal, or a workstation. To run the UETP, invoke DATATRIEVE
as described in Section 4.1 and type the following command:
DTR> @SYS$COMMON: [SYSTEST.DTR]PLOTS

The DATATRIEVE graphics UETP does not require any input from you. There
are pauses between plots. The DATATRIEVE graphics UETP displays the
results of using the following piot statements:
• PLOT WOMBAT - A picture of a wombat
•

PLOT DATE_Y -A scattergraph with dates along the horizontal axis

• PLOT SHADE -The previous scattergraph with shading
• PLOT DATE_Y - A scattergraph with dates along the horizontal axis
• PLOT CONNECT-The previous scattergraph with the points connected
• PLOT DATE_LOGY - A scattergraph with dates along the horizontal axis
and a logarithmic scale for the vertical axis
• PLOT LR - The previous scattergraph with a linear regression line
• PLOT STACKED_BAR - A bar chart with stacked bars and a legend
• PLOT MULTI_BAR-A bar chart with multiple bars and a legend
• PLOT X_Y - A scattergraph
• PLOT TITLE -The previous scattergraph with a title
• PLOT LIMITS_Y - The previous X_Y scattergraph with maximum and
minimum limits imposed on the Y axis

User Environment Test Packages 4-5

•

PLOT LIMITS_X-The previous X_Y scattergraph with maximum and
minimum limits imposed on the X axis

• PLOT REFERENCE_Y -The previous X_Y scattergraph with a solid
reference line on the Y axis
• PLOT REFERENCE_X - The previous X_Y scattergraph with a solid
reference line on the X axis
•

PLOT LR -The previous scattergraph with a linear regression line

• PLOT X_LOGY - A scattergraph with a logarithmic scale for the vertical
axis
• PLOT HISTO - A histogram
• PLOT PIE - A pie chart (with default title heading)
• PLOT TITLE (pie) -The previous pie chart with a multiline title
• PLOT BAR - A bar chart using builder and price
• PLOT SORT_BAR -The previous bar chart with the bars sorted by
descending height
• PLOT BAR - A bar chart using type and price
When the DATATRIEVE graphics UETP finishes, you see this message:
! End of User Environment Test Package for Datatrieve graphics

EXIT

4.4 VAX DATATRIEVE and VAX DBMS UETP
To run the DATATRIEVE and VAX DBMS UETP, invoke DATATRIEVE as
described in Section 4.1 and type the following command:
DTR> @SYS$COMMON: [SYSTEST.DTR]DBMS

The DATATRIEVE and VAX DBMS UETP is long, so the entire UETP is not
repeated here.
You respond to prompts during the DATATRIEVE and VAX DBMS UETP. The
parts of the UETP that require answers are included here with the suggested
responses printed in colored ink.

4-6 User Environment Test Packages

SELECT
PRINT
Part
Number

------Part Description------ St

TI-6789-01

RK HOUSING

! Respond with 123

Unit
Price

Unit
Cost

$300

$190

(or any three digit value)

MODIFY PART PRICE
Enter PART PRICE: 123
PRINT PART_ID, PART PRICE
Part
Number

Unit
Price

TI-6789-01

$123

! Respond with 321

(or any three digit value)

MODIFY ALL PART PRICE
Enter PART_PRICE: 321
PRINT ALL PART PRICE
Unit
Price
$321
$321
$321
$321
$321
Respond each time with 0 (Please)
FOR CURRENT
PRINT PART ID THEN MODIFY PART PRICE
Part
Number
TI-6789-01
Enter PART PRICE:
BR-8901-23
Enter PART PRICE:
TE-2345-67
Enter PART PRICE:
TE-2178-90
Enter PART PRICE:
TI-1334-56
Enter PART PRICE:
PRINT ALL

0
0

(continued on next page)

User Environment Test Packages 4-7

Part
Number

------Part Description------ St

Unit
Price

Unit
Cost

TI-6789-01

RK HOUSING

$190

BR-8901-23

LA36

$750

TE-2345-67

RP05

$1,900

TE-2178-90

RK06

$1,100

TI-1334-56

RP HOUSING

$300

If the DATATRIEVE and VAX DBMS UETP runs successfully, you see the
following message:
End of DATATRIEVE/DBMS User Environment Test Package

4.5 VAX DATATRIEVE and VAX Rdb/VMS UETP
To run the DATATRIEVE and RdbNMS UETP, invoke DATATRIEVE as
described in Section 4.1 and type the following command:
DTR> @SYS$COMMON: [SYSTEST.DTR]Rdb

The DATATRIEVE and RdbNMS UETP is 12 pages long, so the entire UETP
is not repeated here.
You respond to prompts during the DATATRIEVE and RdbNMS UETP. The
parts of the UETP that require answers are included here with the suggested
responses printed in colored ink.
Test Store
Please supply the following values:
WAGE CLASS :
JOB TITLE :
MINIMUM SALARY:
MAXIMUM SALARY:

4
ANYTHING
12000
123000

STORE JOBS USING
BEGIN
JOB CODE = "XXXX"
WAGE- CLASS = *.WAGE- CLASS
JOB TITLE= *.JOB TITLE
MINIMUM SALARY
*.MINIMUM SALARY
MAXIMUM SALARY
*.MAXIMUM SALARY
END

(continued on next page)

4-8 User Environment Test Packages

Enter WAGE CLASS: 4
Enter JOB TITLE: ANYTHING
Enter MINIMUM SALARY: 12000
Enter MAXIMUM SALARY: 123000
STORE JOBS USING
BEGIN
JOB CODE = "YYYY"
WAGE CLASS = 2
JOB TITLE = "FILE CLERK"
MINIMUM SALARY
8000
MAXIMUM SALARY = 20000
END
PRINT JOBS WITH JOB CODE
JOB WAGE
CODE CLASS

xx xx

yyyy

"XXXX", "YYYY"

JOB
TITLE

MINIMUM
SALARY

ANYTHING
FILE CLERK

MAXIMUM
SALARY

$12,000.00 $123,000.00
$8000.00 $20,000.00

! Test Erase

FOR JOBS WITH JOB CODE = "XXXX" ERASE
PRINT JOBS WITH JOB CODE = "XXXX"
FIND JOBS WITH JOB CODE
[l record found]
PRINT ALL
JOB WAGE
CODE CLASS
yyyy

= "YYYY"

JOB
TITLE
FILE CLERK

SELECT LAST
ERASE
PRINT JOBS WITH JOB CODE

MINIMUM
SALARY

MAXIMUM
SALARY

$8,000.00

$20,000.00

"YYYY"

! Test Update

FIND EMPLOYEES WITH EMPLOYEE ID
[ 1 record found]
SELECT

"00168"

(continued on next page)

User Environment Test Packages 4-9

PRINT EMPLOYEE_ID, LAST_NAME, STREET, TOWN, STATE
EMPLOYEE

LAST
NAME

00168

Nash

STREET

TOWN

87 West Rd.

STATE

Meadows

Change this employee's address
Please supply the following value:
STREET:

8 FLINT POND

MODIFY STREET
Enter STREET: 8 FLINT POND
PRINT EMPLOYEE_ID, LAST_NAME, STREET, TOWN, STATE
EMPLOYEE

LAST
NAME

00168

Nash

STREET
8 FLINT POND

TOWN
Meadows

STATE

Don't really want to do this; rollback this change
ROLLBACK
ROLLBACK executed; collection CURRENT automatically released.
PRINT EMPLOYEE_ID, LAST_NAME, STREET, TOWN, STATE OF EMPLOYEES WITH
EMPLOYEE ID = "00168"
EMPLOYEE

LAST
NAME

00168

Nash

STREET

87 West Rd.

FIND ALL EMPLOYEES WITH STATE
[8 records found]
PRINT ALL STATE

TOWN
Meadows

STATE
NH

"MA"

STATE
MA
MA
MA
MA
MA
MA
MA
MA

(continued on next page)

4-10

User Environment Test Packages

Respond with VT {or another two-character state abbreviation)
MODIFY ALL STATE
Enter STATE: VT
PRINT ALL STATE
STATE
VT
VT
VT
VT
VT
VT
VT
VT
! Move them back to MA

FOR CURRENT
MODIFY USING STP.TE
PRINT ALL STATE

"M.l\"

STATE
MA
MA
MA
MA
MA
MA
~..1.Z'....

If the DATATRIEVE and RdbNMS UETP runs successfully, you see the
following message:
! End of DATATRIEVE/Rdb User Environment Test Package

ROLLBACK
ROLLBACK executed; collection CURRENT automatically released.
FINISH ALL
DTR>

User Environment Test Packaoes 4-11

4.6 VAX DATATRIEVE and Forms UETP
You need a VT52-, VTlOO-, VT200-, or VT300-family terminal or a workstation
to run the DATATRIEVE and forms UETP.
If DATATRIEVE was installed with support for TDMS or FMS, you can run
the forms UETP to test the forms interface.

To run the forms UETP, set your VMS default to a directory that contains
YACHT.DAT and OWNER.DAT. Be sure that you have WRITE access (W) to
these files. You can copy YACHT.DAT and OWNER.DAT from the directory
DTR$LIBRARY if you do not have them in your directory. Then invoke
DATATRIEVE as described in Section 4.1 and type the following command:
DTR> @SYS$COMMON: [SYSTEST.DTR]FORMS

When DATATRIEVE uses a form to print records, the screen clears before
the first record is printed. The DATATRIEVE and forms UETP asks you to
enter a character and press RETURN before each statement, causing the forms
product to erase the screen.
The following is a summary of the DATATRIEVE and forms UETP:
The UETP sends instructions to your screen and waits for you to enter
a character and press RETURN. After you respond, the UETP defines
three domains that use the forms product: YACHTS, SAILBOATS,
and FAMILIES. The definitions use forms libraries that are located in
DTR$LIBRARY.

The UETP readies YACHTS and prints a few records without using the
forms product. Then the UETP sends more instructions to your screen and
waits for you to enter a character and press RETURN. After you respond,
the UETP prints a record using the forms product. Press RETURN after
the forms product displays the record.

The UETP sends instructions to your screen and waits for you to enter a
character and press RETURN. After you respond, the UETP prints several
records using the forms product. Press RETURN after the forms product
displays each record.

The UETP tests the STORE statement. The UETP sends instructions to
your screen and waits for you to enter a character and press RETURN.
After you respond, the forms product puts a form on the screen for you
to fill in. To move the cursor from one field to another, use the TAB and
BACK SPACE keys. The TAB key moves the cursor to the next field; the
BACK SPACE key moves the cursor back to the previous field. Help is also
available for some fields if you have trouble entering an acceptable value.
Position the cursor on that field and press the HELP key. After you fill in
the form, press RETURN.

4-12 User Environment Test Packages

The UETP tests the MODIFY statement controlling the DISPLAY_FORM
statement. The UETP sends instructions to your screen and waits for you
to enter a character and press RETURN. After you respond, the forms
product displays the first record for you to modify. Use the TAB and BACK
SPACE keys to move from one field to another. Modify only the BEANI
field in each record. Any other modifications are not written to the data
file. After you modify each record, press RETURN.

The UETP tests the PRINT statement again, using the SAILBOATS
view domain. The UETP waits for you to enter a character and press
RETURN before each PRINT statement. After the forms product displays
the SAILBOAT records, the UETP sends the following message to your
screen:
End of DATATRIEVE/Forms User Environment Test Package

User Environment Test Packages 4-13

5
Maintaining VAX DATATRIEVE
This chapter explains the procedures to follow if problems arise after you
install DATATRIEVE. The sections that follow explain how to write a session
log to a file and how to report a problem to the Customer Support Center.

5. 1 Writing a Session Log to a File
Often a session log file contains information vital to tracking down the cause
of an error. Sometimes this information can help you determine the cause of
an error and correct it or work around it. Session logs are also a useful tool for
the Customer Support Center (CSC), and should be used if you call the CSC,
submit an SPR to Digital, or both.
You can usa tha OPEN cummand tu create a log file of yom~ DATATRIE'VE
session in your VMS directory. After you execute a command file, you can close
this file with a close command and exit DATATRIEVE to print it. A session log
is useful to troubleshoot a long command file or one that produces much output
when your screen often does not accommodate all the lines you need to see at
one time. In the following example, PROBLEMS.LOG is the log file name, but
you can choose any valid VMS file specification you want:
DTR> OPEN PROBLEMS.LOG
DTR> SET VERIFY
DTR> @MYFILE

DTR> CLOSE
! Do not enter the file name following CLOSE.
DTR> SET NO VERIFY
DTR> EXIT
$ PRINT/QUEUE=SYS$PRINT PROBLEMS.LOG

Maintaining VAX DATATRIEVE 5-1

During your log session, if you make calls to other products or if you use a
command like the DATATRIEVE CDO command to request information from
another product, that information is not written to the file specified by the
OPEN command. A print-out of your log session displays your DATATRIEVE
commands but does not include the output generated by the other product.

5.2 Reporting Problems to Digital
Make sure you know your access number before you call the Customer Support
Center (CSC), and use the access number to identify yourself when you call.
Treat the access number and the telephone numbers of the CSC confidentially.
You should designate CSC contact people in your organization, and only these
people should know the CSC access numbers.
The contact people you designate can speak directly with a CSC team
specialist. The CSC will call the contact people directly to deliver a solution,
request more information, or confirm a solution previously delivered.
The CSC will be able to respond faster and more accurately if you have
complete information available when you call. Preparing a statement of the
problem and thinking through the sequence of events that led to its occurrence
can eliminate the need for calls from the CSC to gather more information. The
specialist can focus immediately on isolating and analyzing the problem, rather
than on defining it.
The following list of questions helps you collect supporting information that is
often overlooked, but is essential to understanding a problem in its context.
Try to write down an answer to each question and have the list of answers
ready when you call the CSC.
l

What version of DATATRIEVE are you running?

What versions of the VMS operating system, CDD/Plus, other prerequisite
software, and any optional software are you running? Are these the most
current versions available?

In what environment or under what conditions does the problem occur:
interactive, network, callable, loaded, or single-user system?

Have any changes occurred with the DATATRIEVE software or its usage
that might correlate with the incidence of the problem such as:
• Installing new prerequisite or optional software?
• Upgrading existing software?

5-2

Maintaining VAX DATATRiEVE

Have any changes occurred with your application, such as data, system
parameters, or changes in the procedures?

Can you reproduce the problem with a short example? This will help the
CSC team specialist in reproducing the problem.

Maintaining VAX DATATRIEVE 5-3

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040
before placing your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using
a 1200- or 2400-baud modem. If you need assistance using the Electronic Store,
call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Puerto Rico

809-754-7575

Local Digital subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International

Local Digital subsidiary or
approved distributor

Internal1

SSB Order Processing - WMO/E15
or
Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

1 For internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader's Comments

VAX DATATRIEVE
installation Guide
AA-Aj56j-TE

Please use this postage-paid form to comment on this manual. If you require a written
reply to a software problem and are eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

I \Vould like to see more/less

What I like best about this manual is
What I like least about this manual is

I found the following errors in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

I am using Version ___ of the software this manual describes.
Name/Title
Dept.
Company

Date

Mailing Address
Phone

)o Not Tear - Fold Here and Tape

I
I
I
I
I

---------------------------------------1
No Postage
Necessary
if Mailed
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POST AGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35
110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ... 11 II 1 II111 1II11 .. 1.11.1 .. 1.1. I 1.. 1. 1••• 1.11 ••I
Do ~ot Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I
I
I
I
I
I
I
I
I
I
I
I

Reader's Comments

VAX DATATRIEVE
Installation Guide
AA-AJ56J-TE

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

D
D
D
D
D
0
D
D

I would like to see more/less
What I like best about this manual is
What I like least about this manual is

I found the following errors in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

I am using Version ___ of the software this manual describes.
Name/Title
Dept.
Company

Date

Mailing Address
Phone

)o Not Tear - Fold Here and Tape

I
I
I
I
I

---------------------------------------1
No Postage
Necessary
if Mailed
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POST AGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35
110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 ... •II 1111 I1 II. I.. 1.1 .. 1••1. 1••• 1.11 .. I
Do Not Tear - Fold Here

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I