Appendix B: Q-Tree Maintenance Procedures

This appendix describes some of the procedures that are required to maintain the Q-Tree and QEF product.

The <qtree>/data/ directory is used to hold all the volatile files of the Q-Tree. With the exception of the last two sections, this chapter is about maintenance of the <qtree>/data/ files as described below.

The files and directories of this directory are described in x-qef items in the group *<Q>/data:

    % x-qef -L \*<Q>/data
    <Q>/data/company.cf : company information
    <Q>/data/mkvernum.db : mkvernum database
    <Q>/data/qdsrv.db : qdsrv database
    <Q>/data/qdsrv.log : qdsrv error and audit log
    <Q>/data/qremote/ : directory of remote host interfaces
    <Q>/data/quete/*.db : manual section index
    <Q>/data/traits.ext : host or site specific traits source
    <Q>/data/traits/host.tab : host specific binary traits file
    <Q>/data/roots.map : file of path to path name mappings
    <Q>/data/sysnames.tab : table of system names

The <qtree>/data/ files and directories are discussed in the following sections.

B.1) The Company Information File (company.cf)

<qtree>/data/company.cf contains some similar to the following:

    cset ORGANIZATION  Three Letter Acronym Inc.
    cset ORGABBREV  TLA
    cset ADDRESS  123 Any St.; City, State; Country; PostalCode
    cset TELEPHONE  (415) 555-1212
    cset TELEX		
    cset TELEFAX  (415) 555-1213
    cset SITEADDR  tla.com

This can simply be edited to set the company name, phone number, etc.

Note:

Some organizations include company.cf in the traits.ext using:

    include ^/company.cf  @# `^' replaced by directory
		@# of the containing file

so that the information is available via traits or within qvrs files.

B.2) The Traits Files (traits.ext & traits/*.tab)

The initial configuration of traits.ext is covered in Appendix A: QEF Installation Instructions. This file is used to specify system and host dependent settings of directory and tool names, and capability or facility flags. Note that any variables beginning with "_T_" and "_F_" are automatically imported by qvrs and qefpp. Also note that traits settings are often imported into qvrs files using the traits function. After any modification of the traits.ext file the command:

    % mktraits -u # update traits binary file

should be run to create the binary traits file <qtree>/data/traits/host.tab. This command will rebuild the traits binary file for the local host only. To ensure that the other binaries are updated, either removed them -- mktraits is run automatically if the binary file is needed -- or use mkalltraits for the affected hosts.

B.3) The Quete Databases (quete/*)

See Chapter 2.2 for a description of the use of quete and its databases. The quete database is stored in <qtree>/data/quete. The db.{dir,pag} files are the kdbm database mapping <type>/<host>/<directory> to the appropriate X.db index. The latter file consists of lines of the form:

    section file<tab>name - short description

These are the files "grep"ed by quete. To list the quete databases that apply to the current host use:

    % quete -DL
    /usr/man        H <qtree>/data/quete/usr.man.db
    /usr/X11R6/man  G <qtree>/data/quete/X11.db
    /usr/tcl/man    C <qtree>/data/quete/tcl.db
    ...

The `H' (host), `G' (global), and `C' (config) indicate the scope of the application of the database. For a list of all the databases and mappings, use:

    % cd `pathto qt/data/quete`
    % kdbm -K
    H:gobo:/usr/man  <qtree>/data/quete/usr.man.db
    G:/usr/X11R6/man  <qtree>/data/quete/X11.db
    C:Linux-2.0.34-i686:/usr/tcl/man  <qtree>/data/quete/tcl.db
    ...

To remove a database and its index use:

    % kdbm -D key # e.g., H:gobo:/usr/man
    % rm usr.man.db

To update an existing index for a directory, use:

    % mkquete -u man-directory

To create a new database and index, use:

    % mkquete -ktype man-directory # type is H,G,C,L,N

Note:

mkquete is setuid to the owner of the Q-Tree to allow anyone to update the database.

B.4) The Qdsrv Data Base (qdsrv.db)

This file contains the qdsrv paths and variables. It is maintained by qdsrv itself. qdsrv reads this file at startup and re-writes it any time there are significant changes. The comments at the beginning of the file itself describe the file and its contents. If the need should arise to edit this file, qdsrv should not be running or should be "frozen". To freeze the server run:

    % qdmgt -f

The file can then be edited using a conventional editor. Once the desired changes have been made, the qdsrv can be "thawed" using:

    % qdmgt -r

To check the validity of the paths in the database use qdchk. By default qdchk checks paths for the current host and the current user only. Flags can be specified to checks paths for specified or all users and/or hosts. Database entries for non-existent directories should be removed using:

    % qdmgt delete -number

Most other problems can be resolved by chdiring to the directory in question, correcting the root.vrs file using rootvrs or just running:

    % qdupd

Note:

rootvrs runs qdupd automatically.

B.5) The *.qtree Variables

In addition to path entries, the qdsrv.db contains variable settings. These settings can be viewed using:

    % qdmgt vlist
    gobo.qtree = /p/qtree/linux2_0i/9.1
    matt.qtree = /m/qtree/linux2_0i/9.1
    mokey.qtree = //C/qtree8_4
    kent.qtree = /u/qtree/linux1_2i/9.1

The only types of variables required for normal Q-Tree use are the "host.qtree" variables that are used by qremote (when building a command to be run on another host) and by mkalltraits (to get the names of hosts on which to run). If the location of the Q-Tree on a host changes, the associated variable should be changed as in:

    % qdmgt vset host.qtree qtree-dir

Entries for obsolete machines should be removed using:

    % qdmgt vdel host.qtree

Alternatively, if there are a lot of changes need to be made, the database can be edited using a conventional editor, but the server has to be frozen as described above. Variable lines look like:

    =variable_name value

B.6) The Qdsrv Log (qdsrv.log)

qdsrv appends errors and trace information to <qtree>/data/qdsrv.log. This includes messages at startup and any changes to paths in the database and any errors when loading databases. As such it will grow continuously.

This log should be examined occasionally looking for errors. The file should be reduced by removing lines at the beginning of the file when it reaches an excessive size.

B.7) The Mkvernum Log (mkvernum.db)

Every time mkvernum or its link vcc builds a version file that incorporates "^c", they send a mkvernum request to qdsrv. qdsrv will then increment the latest build count for the module and append a line similar to the following:

    module 9.1(1234) config host /directory user <date> <time>

to <qtree>/data/mkvernum.db. The number in parentheses is the build number and is incremented on each request for the module. Usually this number will be embedded in the delivered file in such a way that it can be recovered from a core dump or the file itself. This number and the module name can then be used in conjunction with this log to determine by whom, when, and where the module was built.

However, this file can very quickly become very large and should be culled occasionally. The following procedure should be followed to reduce the file to the last entry for each module, but saving the old records in a compressed form:

    % cd `pathto qt/data`
    % gunzip mkvernum.odb # if it gzipped form exists
    % qdmgt -f # freeze the server
    % vernumcomp -i - -o - -s mkvernum.odb # see below
    % qdmgt -r # resume the server
    % gzip mkvernum.odb

The vernumcomp reads its input file (`

' is equivalent to mkvernum.db), appends all read records to mkvernum.odb, and re-writes the last record for each module to the o output file (`

' equivalent to mkvernum.db). The above procedure thus reduces the active mkvernum.db to the most recent record for each module and appends old records to mkvernum.odb.

B.8) The Qremote Command Files (qremote/*)

The directories <qtree>/data/qremote and /.qtree/qremote contains the commands to run remote jobs on other hosts. The names of the files in these directories should be the name of the host for which they are providing the interface. For example, `bozo' contains the commands to run a command on the host `bozo'. These files are invoked by qremote using the command:

    /.qtree/qremote/host host command
    # or, if the above does not exist
    <qtree>/data/qremote/host host command

Given the above syntax, a file in this directory could be a link to or a copy of rsh or rcmd. However, qremote will execute rsh or rcmd directly if this directory or the user's /.qtree/qremote does not contain a file called host. Files should be created in this directory when a new host target that does not support the normal rsh syntax is added to the network.

Note:

<qtree>/data/qremote/README contains some of the above text and example commands for rshing to a VMS system.

B.9) The System Name Mapping File (sysnames.tab)

The <qtree>/data/sysnames.tab file is used by system, its link sysnm, qvrs, and a variety of other tools to map the system's uname srm fields (and sysinfo platform information if available) to names used within the Q-Tree.

Note:

See System(x-qvrs) for a description of the seven different system names. The manual section system(1) should be read for a definitive description of the syntax and semantics. The sysnames.tab(x-qef) item also contains a comprehensive description of the file and its fields.

Sometimes a new mapping will be required to support additional platforms. For example, if the release number is changed, a new mapping may be required. Care should be taken to ensure that the new mapping does not change the mapping for any previously supported platform.

B.10) File of Path to Path Mappings (roots.map)

The <qtree>/data/roots.map file is used to provide three different forms of path to path or symbol to path mappings as used by qvrs to map directories in @RootPath, to convert windows path names to their unix equivalents, or to convert symbolic names used by pathto to path names. roots.map provides conditionals to select mappings according to the name of the host or the configuration name. This file is shared by all users and all platforms that share the <qtree>/data/ directory.

Note:

Users can have their own /.qtree/roots.map file to provide their own mappings or to override those provided by the <qtree>/data/ version.

See roots.map(x-qmisc) for a description of the syntax and semantics for this file.

B.11) New User Setup and Localizing dotqtree Dirset

To introduce a new user to the QEF system, see Chapter 3: Getting Started.

Basically a new user will need to know how to set $QTREE, and $PATH, how to define qd, and how to set up their /.qtree directory -- see Chapter 3.2: Initializing Your $HOME/.qtree Directory. This is usually done by running:

    % dirsetup -d $HOME dotqtree

To ease the task of configuring the files created by the above, the dotqtree file can be modified to incorporate local changes. To do this:

    % upd -ic `dirsetup -f dotqtree` # back up current version
    - cp <qtree>/bin/Dirsetup.dir/dotqtree
		<qtree>/bin/Dirsetup.dir/dotqtree+1
    # create temporary work directory
    % cd $HOME; mkdir tmp; cd tmp
    % dirsetup dotqtree # extract dotqtree files
    - mkdir .qtree/ctdir; mode = 0777
    - create .qtree/README
    ...
    # edit .qtree/envset.cf and .qtree/roots.map as required; see
    # .qtree/envset.cf(x-qmisc) and .qtree/roots.map(x-qmisc)
    % dirsetup -R dotqtree > new # create new dirsetup file
    % dirsetup -d tmp ./new # test new file
    % cp ./new `dirsetup -f dotqtree` # install new version
    % cd ..; rm -rf tmp # optional clean up

B.12) The lib/sysvrs/`system -v`.vrs File

qvrs uses a file in <qtree>/lib/sysvrs to define various platform or system specific settings such as library mappings, standard optimization flags, capability options, etc. The name of the actual file used is the output of system v with .vrs appended. See <sysvrs>(x-qvrs). The current version can be viewed using the command:

    % qvrs -Ps

This file uses the qvrs function trait extensively to use settings from the <qtree>/data/traits/host.tab database so as to minimize the need to change the lib/ file. However, sometimes the sysvrs file does not provide the required settings and will have to be modified.

Note:

If a specific project requires extensive system dependent settings, it is recommended that those settings be put into a project/specific qvrs file as described by <psysvrs>(x-qvrs).

It should be appreciated that changes to the <qtree>/lib/sysvrs/`system v`.vrs file will affect every build on the system, thus should be done carefully.

Prior to modifying the sysvrs file a backup copy should be made.

    % cd `pathto qtlib/sysvrs` # chdir to appropriate directory
    % F=`system -v`.vrs # set $F to name of file of interest
    % upd -ic $F # make back up copy
    - cp linux2.vrs linux.vrs+1
    % ed $F # edit the file
    % qvrs -f # check that qvrs still works
    % qvrs # check settings

Note:

If the changes are to be discarded one can use upd to both remove the modified version and restore the old copy, as in:

    % upd - -r1 $F # - -i not necessary as existence
		# of $F+1 file implies it
    - rm linux2.vrs
    - mv linux2.vrs+1 linux2.vrs

B.13) Other Possible Changes

It is recommended changes to the Q-Tree outside of the data directory be avoided. However, there are a number of possible extensions. It should be understood that any changes made outside of the data directory may be lost if a Q-Tree update is installed unless measures are taken as described in Warning With Respect to Re-installation.

Other possible changes could be additions or modifications to the following classes of files:

bin/Bp.dir/* bp boiler plates

bin/Dirsetup.dir/* dirsetup databases

bin/Howto.dir/* howto files

bin/Qfunc.dir/* qfunc files

bin/Xdb.dir/*.xo x_db databases

lib/deps/*.dpo incls scanning F.S.A. files

lib/deps/deps.map depsmap suffix to file mapping table

lib/qsg/*.qsl qsg libraries

lib/touchdir/* touchfiles files -- should be temporary

lib/verlib/*.vf mkvernum templates

x040.qh - 9.3 - 03/10/22