Chapter 3: Getting Started

This chapter covers the necessary user set up to use QEF. It also introduces the user's $HOME/.qtree (referred to as /.qtree) directory.

3.1) $QTREE, $PATH, and qd

An important feature of the QEF system is that it can be located anywhere. All internal references to a QEF file are resolved by searching the directories named by the environment variable $QTREE or the default setting, set when the QEF system was built. In most situations there will be a single directory that will be used and/or sufficient, so the special case of multiple QEF trees will be discussed later.

To use the QEF system and tools, the environment variable $QTREE needs to be set to the name of the directory containing the QEF installation.

set $QTREE

To set $QTREE use:

    % export QTREE=<qtree> # if using sh
    % setenv QTREE <qtree> # if using csh

The value of <qtree> is the name of the directory in which Q-Tree was installed. Your system administrator should have this information. Some organizations will have created a shell script called Lclqtree that should be available in the standard directories on all systems, thus one would set $QTREE using:

    % export QTREE=`Lclqtree`

To test the setting of $QTREE one can use it to invoke pathto to output its interpretation, as in:

    % $QTREE/bin/pathto qt
    <qtree>

Note:

Some sites may choose to store the QEF system under a system and release specific name, in particular one that incorporates the output of sysnm, as in fixed-dir/`sysnm`.

set $PATH

You will also need to add the $QTREE/bin directory to your $PATH. To set your $PATH use:

    % export PATH=$QTREE/bin:$PATH # if using sh
    % setenv PATH $QTREE/bin:$PATH # if using csh

The program pathclash may be used to look for any name conflicts in the new $PATH, for example:

    % pathclash | grep qtree
    pathto    <qtree>/bin /usr/local/bin

The normal pathclash output is the names of an executable files that appear in multiple $PATH directories followed by the space-separated list of their containing directories.

define qd

Chapter 6 describes qdsrv, the QEF server which maintains a database of paths. One of the qdsrv client programs is qds which queries the path database. To facilitate navigating the forest of trees that will be created, it is recommended that a user creates the qd alias or function:

    # if using csh
    alias qd 'set qdtmp=`qds -d \!*` && cd $qdtmp'

    # if using sh, ksh, or bash
    qd () {
    	qdtmp=$(qds -d $*) && cd $qdtmp ;
    }

The qd will then help the user chdir to a tree using a qds query, as in:

    % qd -o -pguide # chdir to guide's object tree
    Using 59 guide 9.1 object dt gobo linux2_0i /p/guide/o
	/p/guide/s

To help set aliases and shell functions, qfunc is provided. It has a database of aliases and functions, one of which is qd. To easily define the qd alias or function use:

    % eval `qfunc -c qd` # if using csh
    % eval `qfunc qd` # if not using csh

The definitions of $QTREE, $PATH, and qd should be done in your login script (e.g., .cshrc, .profile, .login) so that they are correctly set for all sessions. Better yet learn to use envset which has special help for setting $QTREE, $PATH, qd, etc.

qfunc also provides a definition of qdp which is like qd except it uses pushd instead of cd. If your shell does not support pushd, qfunc also provides pushd and popd functions implemented using pdirs. For a list of all the supported qfunc functions just use:

    % qfunc
    Ev        function to invoke envset for selected set
    Qf        function to eval qfunc for selected function
    cats      function to invoke cat on file(s) found using sls
    ...

3.2) Initializing Your $HOME/.qtree Directory

	The user's /.qtree (a.k.a. $HOME/.qtree) directory contains data files for a variety of *QEF* programs: qefgui creates /.qtree/Prefs and /.qtree/TreeSet on exit to contain the user's environment. go and josh create diagnostic files in /.qtree/goes/ and append audit lines to gomsgs in the same directories. the default directory for ct and pa is /.qtree/ctdir. josh's default jobfile is /.qtree/josh. envset's default file is /.qtree/envset.cf. For platforms on which the creation of /.qtree presents problems (e.g., VMS), an alternative directory may be used by setting $HOME_QTREE to its name. The dirsetup database dotqtree contains a prototype /.qtree directory.
create /.qtree	To initialize your own /.qtree directory use: % dirsetup -d dotqtree - mkdir /.qtree/ctdir; mode = 0777 - create /.qtree/README - create /.qtree/ctdir/README - create /.qtree/envset.cf - create /.qtree/goes/README - create /.qtree/goshow - create /.qtree/josh - create /.qtree/maproots If locating your .qtree directory in /.qtree is not possible, locate it as convenient and set $HOME_QTREE to the new location.
$HOME_ QTREE	To use a name other than ".qtree", use dirsetup's m flag as in: % dirsetup *-d -m.qtree=yourchoice* dotqtree** - mkdir /yourchoice/ctdir; mode = 0777 - create /yourchoice/README ... In such a case the environment variable $HOME_QTREE must be set to the name of the /.qtree directory to be used, as in: % export HOME_QTREE=$HOME/yourchoice
Summary	Given the setting of $QTREE, the addition of the <qtree>/bin to your $PATH, the definition of qd, the creation of your /.qtree directory, and the setting of $HOME_QTREE, if necessary, you are ready to use *QEF*.

c015.qh - 9.3 - 03/10/22