Chapter 6: Qdsrv: The QEF Server

This chapter covers qdsrv (the QEF server), its client programs, and its uses. All the provided services are described, but the emphasis is on the use of the path database to navigate the trees.

    % qef # being run on matt
    #{ @matt 2000/03/01 02:59:45
    qef: Time check failed
    	2000/03/01 02:59:59     gobo (qdsrv host)
    	2000/03/01 02:59:45     matt (local host)
    	14			difference
    #} E-1 matt@/m/qtree/linux2_0i/o8.4 2000/03/01 02:59:45(0)
    
    % qdmgt -t # check the time synchronization
    Time check failed
    	2000/03/01 03:06:20     gobo (server host)
    	2000/03/01 03:06:06     matt (local host)
    	14			difference

    % qtreeinf # show Q-Tree version info
    $QTREE: /m/qtree/8.4/linux2_0i
    Default $QTREE: /usr/qtree8.4

    0: /m/qtree/8.4/linux2_0i
      Real Dir: /m/qtree/8.4/linux2_0i
      # following is extracted from the relinfo file
      Qtree(full) 8.4.6(677) Linux-2.0.36-i686(linux2_0i)
		2000/03/24
	    dt on matt in /m/qtree/linux2_0i/o8.4 at
		02:27:24 EDT, 2000/03/24
      Using:
	    Tcl/tk 7.4(12) Linux-2.0.36-i686 2000/03/09
    
    % qef -V # get qef's version string
    Version: Qef (257) Qtree(8.4) 2000/02/27 07:02:20 
	Linux-2.0.34-i686
    
    % wot -vp qef # wot's is somewot like SCCS's what(1)
    Qef (179) Qtree(8.4) 2000/02/27 07:02:20 Linux-2.0.34-i686
    Libqdsrv (31) Qtree(8.4) 2000/01/02 05:49:37 Linux-2.0.34-i686
    Libdtree  8.4.1(233) Qtree(8.4) 2000/02/27 07:00:02 
	Linux-2.0.34-i686

    qtree:qef 8.4(179) Linux-2.0.34-i686 gobo
	/p/qtree/linux2_0i/o8.4/qef dt 2000/02/27 07:02:20

    % qdmgt vlist m\*.qtree
    matt.qtree = /m/qtree/8.4/linux2_0i
    mokey.qtree = //C/qtree8_4

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

    % qdid -s # bind current tree to my identifier
    Id 2: 59 guide 8.4 object dt gobo linux2_0i /p/guide/o
	/p/guide/s

    % qdmgt listids # list current path ids in use
    bruce: 0 path: 32
    root: 1 path: -1 # -1 means no path assigned
    dt: 2 path: 59

    % qd -i # chdir to path bound to id
    Using 59 guide 8.4 object dt gobo linux2_0i /p/guide/o
	/p/guide/s

Ideally, qdsrv should be started automatically on a machine accessible from every development machine see Appendix A.4: QDSRV Setup. The qdsrv program handles a single database that documents all trees on all projects; therefore it should be located on some machine accessible by all development platforms.

To determine if qdsrv is running, issue the command:

    % qdmgt -v
    # if qdsrv is running ...
    Qdsrv   8.4(162) - 2000/01/19 01:08:00 - Linux-2.0.34-i686
	    pid=455; uid=0; host=gobo; port=6631
	    Database: <qtree>/data/qdsrv.db

    # If qdsrv is not running ...
    qdmgt: connect failed  Connection refused
	    check that qdsrv is running  See errQdsrv1(x-qmisc)

If you do see a response similar to the latter one above, try running qdsrv yourself:

    % qdsrv
    qdsrv started: errors will be logged in
	<qtree>/data/qdsrv.log
    # or
    qdsrv: Current host (matt) not Server host (gobo)

    % traits QDSRV_HOST QDSRV_PORT
    QDSRV_HOST      gobo
    QDSRV_PORT      6631

The server qdsrv is run on some machine on the network attached to a TCP/IP port. The names of the host and the number of the port are specified by the above traits variables. An environment variable QDSRV_ID could be used to override the traits settings, but given the universal nature of the server, doing so is strictly a local temporary fix. The settings should be the same on all systems and arrangements should be made to ensure that qdsrv is always running on the named host.

Most interaction with the server is through a few specialized commands.

-t

Check the current hosts time against that of the qdsrv host.

-f

Freeze the database to allow manual editing limited to root and the owner of the database.

-r

Reload the database after freezing it.

-v

Retrieve the qdsrv version information and output it.

    <Index> <Project> <Release> <Type> <User>
	<Host> <Config> <RootPath> ...

as in:

    13 qtree 7.1 object dt sark linux /kent/u/qtree/o /u/qtree/s

The main purpose of qds is to provide a directory name that can be used as an argument to chdir or to pushd. The arguments to qds (or the alias qd) are used to select the path. For example:

    % qds -pguide -a -S # all paths for the guide project
    52 guide 8.4  baseline dt  gobo  -       /p/guide/s
    59 guide 8.4  object  dt   gobo  linux2_0i /p/guide/o
	/p/guide/s
    63 guide 8.4  object  dt   matt  linux2_0i /m/guide/o
	/m/guide/s

    % qds -t object # guide object trees
    59 guide 8.4  object  dt   gobo  linux2_0i /p/guide/o
	/p/guide/s
        # query automatically assumes the current project, user,
	# and host if doing so reduces number of paths matched

    % qds -o -d # output first directory only
    /p/guide/o/guide

If there are multiple matches, qds will apply the matches current project, current user, and current host to try to reduce the list to a single entry. These matches are equivalent to the flags -p, -u, and -h, each with the argument ".".

The -d flag forces the output to be a single directory. When -d is given and qds cannot reduce the list to a single directory, qds outputs the list to standard error, as in:

    % qds -d -o -pqtree
    The following multiple directories matched:
    32 qtree 8.4    object  dt	    gobo    linux2_0i.f
	    /p/qtree/linux2_0i/o8.4
	    /p/qtree/s8.4
    48 qtree 8.4    object  dt	    gobo    linux2_0i.p
	    /p/qtree/linux2_0i/o8.4p
	    /p/qtree/s8.4
    qds: Use the index in the first column to resolve ambiguity

Most of the time, a unique match can be found with just one or two flags. And after a few uses, you start to know the index values for the paths you commonly use you can also specify a path directly with the index, and this may be faster. For example, to go to the path with index 32:

    % cd $(qds -d -32)

Rather than frequently typing "cd $(qds -d ...)", we suggest you define a shell function or csh alias as follows:

    qd () {
	qdtmp=$(qds -d $*) && cd $qdtmp
    } # in sh, ksh or bash
    alias qd 'qdtmp=`qds -d \!*` && cd $qdtmp'# in csh

This text is also available in the qfunc database, thus can be used to set the function or alias:

    % eval $(qfunc qd) # in sh, bash, or ksh
    % eval `qfunc -c qd` # in csh

Once qd is defined, the command qd will cd to the appropriate directory in the selected path. If the selection does not result in a single path, qd will list the matching paths, including their indexes.

There are a number of special case qds flags in addition to the queries:

The -i may be followed by a decimal index indicating which root in the RootPath should be selected, thus typically yielding:

Often you will know the indices of the paths you use most commonly, but if not use qds as in:

    % qds -p <project name> -o

This command produces a list of the paths defined for the project. Then you can run:

    % qd -I -N

where N is the index of the path of interest. This changes directory to the project root and sets the identifier.

The above may seem formidable, however, in most instances it is sufficient to specify the -ttype argument (or one of the -[bmosvw] short cuts). This is because qds -d will try to reduce the number of matched patterns by applying -p., -u., and -h. queries in turn if they reduce the number of patterns matched (provided not all matches are eliminated).

qds -d and qd take an optional argument that specifies the sub-directory to be appended to the root of the selected path.

By default, if the selected path has the same @Project setting as the current directory, qds -d will append the current displacement (i.e., @Branch) to the target root. This facilitates changing from a project tree (e.g., the object tree) to the corresponding location in another of the project's trees (e.g., baseline tree).

If the corresponding directory does not exist in the target tree, sub-directories are removed until one that does exist is found.

If the target tree does not have the same @Project as the current value, qds -d will use the root of the target tree.

If an argument is specified, it is interpreted a sub-directory of the target directory, unless the argument begins with `/', in which case it is interpreted as a sub-directory of the target root. qds -d