Chapter 6: Qdsrv and Qhost: The QEF Servers

This chapter covers qdsrv (the QEF server), its client programs, and its uses, and the other QEF server qhost. 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/o9.1 2000/03/01 02:59:45(0)
    
    % qdmgt -t # check the time synchronization
    Time check failed
    	2000/03/01 03:06:20     gobo (qdsrv host)
    	2000/03/01 03:06:06     matt (local host)
    	14			difference

t

    % qtreeinf # show Q-Tree version info
    $QTREE: /m/qtree/linux2_0i/9.1
    Default $QTREE: /usr/qtree9.1

    0: /m/qtree/linux2_0i/9.1
      Real Dir: /m/qtree/linux2_0i/9.1
      # following is extracted from the relinfo file
      Qtree(full) 9.1.6(677) Linux-2.0.36-i686(linux2_0i)
		2000/03/24
	    dt on matt in /m/qtree/linux2_0i/o9.1 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(9.1) 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(9.1) 2000/02/27 07:02:20 Linux-2.0.34-i686
    Libqdsrv (31) Qtree(9.1) 2000/01/02 05:49:37 Linux-2.0.34-i686
    Libdtree  9.1.1(233) Qtree(9.1) 2000/02/27 07:00:02 
	Linux-2.0.34-i686

    qtree:qef 9.1(179) Linux-2.0.34-i686 gobo
	/p/qtree/linux2_0i/o9.1/qef dt 2000/02/27 07:02:20

Note:

mkvernum type strings can usually be added to a program or a library using the v flag on the corresponding commands, program, or library statement in the qeffile.

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

s

I

i

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

    % qdid -s # bind current tree to my identifier
    Id 2: 59 guide 9.1 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 9.1 object dt gobo linux2_0i /p/guide/o
	/p/guide/s

Message	Description
exstatid	reserve and retrieve a exstat slot identifier Used by qremote to reserve a slot which is passed to cush using cush's X flag.
exstatset id status	send the exit status for slot id Used by cush to send its argument command's exit status back to qremote.
exstatget id	Retrieve the exit status for slot id Used by qremote to retrieve the exit-status of a remote job run by cush.

See Chapter 11.2: Distributed Processing

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   9.1(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 the root user or 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 9.1  baseline dt  gobo  -       /p/guide/s
    59 guide 9.1  object  dt   gobo  linux2_0i /p/guide/o
	/p/guide/s
    63 guide 9.1  object  dt   matt  linux2_0i /m/guide/o
	/m/guide/s

    % qds -t object # guide object trees
    59 guide 9.1  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

Note:

o is equivalent to tobject, b is tbaseline.

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 9.1    object  dt	    gobo    linux2_0i.f
	    /p/qtree/linux2_0i/o9.1
	    /p/qtree/s9.1
    48 qtree 9.1    object  dt	    gobo    linux2_0i.p
	    /p/qtree/linux2_0i/o9.1p
	    /p/qtree/s9.1
    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.

Option	Description
-C[a]	show paths whose first directory contains the current directory `a' option checks all directories of a path.
-R[a]	show paths for the current directory's RootDir `a' option checks all directories of a path
-a	suppress default ambiguity resolution p. u. h. queries See below
-num	select path with index num
-c  config	select directories with given config field `.' is equivalent to the @System[Name] or `sysnm`
-h  host	select directories with given host field `.' is equivalent to the name of the current host
-p  project	select directories with given project field `.' is equivalent to the value of qvrs @Project
-r  revision	select directories with given revision field `.' is equivalent to the value of qvrs @Revision
-t  type	select directories with given type field
-u  user	select directories with given user field `.' is equivalent to the name of the current user
-b	equivalent to tbaseline
-m	equivalent to tmaster
-o	equivalent to tobject
-s	equivalent to tsource
-v	equivalent to tversion
-w	equivalent to tworking

Note:

The arguments for the [chprtu] flags can employ shell wild card pattern matching as in qd -clinux*.

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

Its primary purpose is to indicate to the client that its host is up and running. It also returns the system name, pathname of the Q-Tree, and the home directory for the user on the host. So:

    % qhost gobo
    gobo: fbsd4_9i /g/qtree/fbsd4_9i/9.1 /g/dt

qremote sends messages to check that hosts are available and to retrieve the Q-Tree path and the user's home directory.

Relevant qhost commands are:

    % qhost -S # Start the server on named host
    % qhost -R # Keep trying to start the server when
		# address was busy
    % qhost -q host # tell host's qhost to quit
    % qhost -v host # retrieve version of qhost run on host