This version of Datatrieve is a complete kit. You do not need any previous versions of Datatrieve to install it.

To install VSI Datatrieve T7.4-3, you must be running one of the following versions of OpenVMS:

To check which version of VSI OpenVMS is currently installed on your system, use the SHOW SYSTEM command at the DCL prompt.

You must have Version 4.1 of Oracle CDD/Plus before you can install VSI Datatrieve. To check which version of CDD/Plus is currently installed on the system, use the following command:

$ DICTIONARY OPERATOR

The CDO banner gives the version of CDD/Plus currently installed on your system. For example:

Welcome to CDO Vl.0
The CDD/Plus V4.l User Interface
Type HELP for help
CDO>

The following optional products can be used along with VSI Datatrieve:

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.

When you install required and optional software products with Datatrieve, you should install these products in the following order:

You should check the following parameters to make sure they are sufficient for installing Datatrieve:

%VMSINSTAL-W-LOWQUOTA, One or more account quotas may be too low.

$ RUN SYS$SYSTEM:SYSGEN
SYSGEN> SET CLISYMTBL 250
SYSGEN> WRITE ACTIVE
SYSGEN> WRITE CURRENT

Before you install Datatrieve, you should perform the following tasks:

The following two sections explain these procedures.

$ SET PROCESS/PRIVILEGE=NOBYPASS
$ RUN SYS$SYSTEM:DMU
DMU> SHOW PROTECTION CDD$TOP

$ 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

$ SET PROCESS/PRIVILEGES=BYPASS
$ RUN SYS$SYSTEM:DMU
DMU> DELETE/PROTECTION/POSITION=l CDD$TOP
DMU> EXIT
$ SET PROCESS/PRIVILEGES=NOBYPASS

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]

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 different versions of Datatrieve. For example, the installation procedure could be run first to install VSI Datatrieve T7.4-3 with TDMS. You could then install VSI Datatrieve T7.4-3 a second time to support FMS. The resulting images and file names would be 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:

The installation procedure now asks if you want to install Datatrieve using default answers for all questions.

The installation procedure prompts you with the following question:

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

If you type Yes, the Datatrieve installation procedure automatically does the following:

If you type No, the installation procedure continues with the questions about 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 VSI Language-Sensitive Editor is not installed on your
    system. To have the VSI Language-Sensitive Editor support,
    you must:

        1.  Install the VSI Language-Sensitive Editor
        2.  Install or reinstall this product

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

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

If you enter Yes, the installation continues; however, you will not be able to use LSE with Datatrieve. If you enter the default value by entering 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:

        1.  Do a complete VSI DATATRIEVE installation including
            VSI DATATRIEVE support for LSE.
        2.  Do only VSI DATATRIEVE support for LSE without
            installing VSI DATATRIEVE.

* Select option [1]:

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.

Each installation of Datatrieve on a system can support only one of two forms management products. These products are:

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, VSI DATATRIEVE will
    be built without Forms Management support.

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

* Do you wish to continue with the installation [YES]?

If you type Yes 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, ''Specifying Suffixes for Multiple Installations of This Version of VSI Datatrieve'' for more information.

If you type No, 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:

    VSI DATATRIEVE can be built to support any one
    of these products, or, if desired, VSI 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 No. The installation procedure resumes with questions on suffixes and more than one installation of this version of Datatrieve.

If you do want forms support, enter Yes 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 that each installation of Datatrieve can support only one forms product. After you enter Yes 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 Yes 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 No, you receive a question about support for FMS.

If you type No 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 Yes or press the Return key, you have another opportunity to answer questions about forms. If you type No, the installation procedure aborts.

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 VSI 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

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

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

If you type No or press the Return key, the installation procedure continues with questions about retaining Datatrieve files (see Section 2.5.5, ''Deleting the Datatrieve Object Library'' for more information). At a later date, you can decide to install Datatrieve using file names other than the defaults by typing Yes in response to the previous question.

If you type Yes, 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
    VSI DATATRIEVE installation, it is necessary to append a
    suffix to some of the file and image names. For each
    installation of this version of VSI 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, ''More Than One Installation of This Version of Datatrieve'' 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, ''Deleting Obsolete Files'' 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.

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 qualifier
    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 /VARIANT qualifier to invoke any other Datatrieve image using the DCL command DATATRIEVE.

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

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]?

If you do not want to keep the Datatrieve library on line, type No or press the Return key. Type Yes if you want to keep the library files.

You should keep the library on line if you anticipate having to relink this image of Datatrieve. If you do not keep the library files on line and later need to relink Datatrieve, you must reinstall this kit.

You have to relink Datatrieve if you:

If you keep the library on line, you may enter the following command to relink Datatrieve:

$ @DTR$LIBRARY:DTRBLDxx

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.

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, ''Creating a DCL Command File for New Users'' for more information).

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 number for DDMF is defined as 30 by the installation procedure. You receive the following question:

* Do you want DDMFxx.EXE to be used for distributed access [NO]?

Type Yes 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 Yes 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 No or press the Return key if these considerations do not apply to this installation of Datatrieve.

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]?

Your answer to this question is determined by one of the following situations:

If you answer Yes in either of these two situations, the NEWUSER.COM file is replaced. In addition:

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 Yes 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 OpenVMS username. For example, if the parent directory is CDD$TOP.DTR$USERS and user SMITH invokes NEWUSER, SMITH gets the following:

If you answer No 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.

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.

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 Yes or press the Return key if you want this image to be installed SHARED.

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 Yes or press the Return key if you want this image to be installed as SHARED.

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.

The following question is displayed:

* Do you wish to have the plot definitions [YES]?

Type Yes 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 VSI DATATRIEVE that can be tailored at the installed
    site.

* Do you want the optional material [NO]?

Type Yes if you want this material. The installation procedure loads these files in DTR$LIBRARY. If you do not want this material, type No or press the Return key.

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

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 VSI DATATRIEVE makes obsolete some files
    from previous versions of VSI DATATRIEVE.

* Do you want ALL the obsolete files deleted [YES]?

Answer Yes or press the Return key to delete obsolete files. If you answer No, 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.

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 various directories where they were created. No files are purged except those created in this installation. Type Yes or press the Return key to purge the files.

DECnet is normally installed on an OpenVMS system. Unless you install Datatrieve on an OpenVMS system without DECnet, the installation procedure automatically defines a DECnet object for the Datatrieve remote server.

However, if you install Datatrieve on an OpenVMS 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 DEFINE OBJECT DDMF NUMBER 30
$ NCP SET OBJECT DDMF NUMBER 30
$ NCP DEFINE OBJECT DDMF FILE DDMFxx.COM
$ NCP 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:

$!+
$!   VSI DATATRIEVE Start-up File
$!-

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

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 username and password from the node specification when accessing domains on your node.

If you wish to set up such a default DECnet account for distributed access, follow these steps:

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:

$ AUTH == "$AUTHORIZE"
$ NCP == "$NCP"
$ SET DEFAULT SYS$SYSTEM
$ AUTH
UAF>ADD DECNET DTR/OWNER="VSI
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:  VSI DATATRIEVE
Account:                          UIC:    [376,376] ([376,376])
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-OCT-1989 15:31:09

Object= DDMF

Number                   = 30
File id                  = DDMF.COM

NCP>DEFINE OBJECT DDMF USER DECNET DTR PASSWORD YACHTS
NCP>LIST OBJECT DDMF

Object Permanent Summary as of 31-OCT-1989 15:31:09

Object DDMF

Number                   = 30
File id                  = DDMF.COM
User id                  = DECNET DTR
Password                 = YACHTS

NCP>SET KNOWN OBJECTS ALL
NCP>EXIT
$

For more information on NCP and DECnet, refer to the relevant section in the VSI OpenVMS System Manager's Manual, Volume 2: Tuning, Monitoring, and Complex Systems.