MTHREADS

Section: User Commands (1)
Updated: LOCAL
Index Return to Main Contents

NAME

mthreads - threaded database manager for trn

SYNOPSIS

mthreads [-d[MM]] [-e[HHMM]] [-aDfknv] [hierarchy_list]

DESCRIPTION

Mthreads manages the thread files that are used by the trn(1) newsreader. ``Thread files'' are used to store information about the news articles and how they are all related to one another.

Mthreads needs to be run periodically --- either in single-pass mode out of cron, or in daemon mode out of the boot script --- to update the thread information whenever new news is received. A site that gets its news feed during the night and doesn't need local postings processed throughout the day can run mthreads in single-pass mode once a day. If more processing is needed, either run mthreads more often or run it in daemon mode. In daemon mode, a background process is forked off that wakes up every 10 minutes (by default) to check if the active file has been updated.

INSTALLATION

Mthreads in installed in the RNLIB directory chosen during configuration. When it is run for the first time, it will automatically create a file called active2 in the same directory. This file is essentially a copy of the active file that keeps the newsgroup totals from the last run in one place. It is also used to choose which groups are to be processed into thread files. All groups start out as ``unthreaded'' unless they are turned on with a command like:

: mthreads all

which would create thread file for all the groups. For testing purposes it is a good idea to start out small with a command like:

: mthreads news

which would thread only the news hierarchy. Thread processing can be turned on or off for individual groups or entire hierarchies by specifying the groups in a syntax very similar to that used in the sys file. For example, to turn on all of soc and talk except for talk.politics, and to turn off news.lists, use the following command once:

: mthreads soc,talk,!talk.politics,!news.lists

If mthreads complains that another mthreads process is already running, it can be killed with the command:

: mthreads -k

and then repeat the prior command after giving it a little time to die.

Once all the desired groups are turned on, it is not necessary to specify a hierarchy list for the normal functioning of mthreads. It can be used, however, to customize which new groups get turned on as they are created.

LOGGING

As mthreads executes, some status information (including error messages) is placed in the file mt.log in the RNLIB directory. This file will grow without bounds, and should be scanned periodically for errors, and trimmed in size when it grows too large. See the shell script mt.check for an mt.log maintainer that will send mail if it finds database errors.

OPTIONS

-a: is used to automatically turn on thread processing for new news groups as they are created. The default is to leave new groups unthreaded.
-D: specifies a debugging mode where only the groups mentioned on the command-line are processed --- all other groups are left unchanged. It also outputs each group's name into the log file before it is processed.
-d: is used to specify the daemon mode, where mthreads forks a background task that periodically wakes up and checks for an updated active file. The number of minutes to wait after the completion of the last pass can be specified after the '-d' option (e.g. -d20), otherwise it will default to 10 minutes.
-e: tells mthreads to run an enhanced expiration check on the database. Without this option, only articles below the minimum field in the active file are expired. With this option, all unexpired articles in the database are stat()'ed to see if they actually exist. In single-pass mode the -e option always affects the current pass --- use it once a day after expire has run. In daemon mode, the -e option will cause one pass a day to be the enhanced expire pass. By default, this is the first time mthreads wakes up after 12:30 am. If a different time is desired, it can be specified in the form HHMM (e.g. -e2359).
-f: is used to force mthreads to open each and every thread file to see which ones really need to be updated, not just the ones that differ in the active/active2 comparison. It will also remove any extraneous thread files from unthreaded groups (which should only occur if you manually change the active2 file). This option should only be used when manipulating the thread files in unorthodox ways.
-k: can be used to terminate the currently running mthreads, just as if it had received a terminate signal. When this option is specified, no other activity is performed.
-n: tells mthreads that no actual processing of thread files is to be performed. This can be used to just adjust which groups are to be processed, without actually doing any of the processing right away.
-s: tells mthreads to sleep one second before processing each article. This is useful if your NNTP server cannot handle mthreads running at full speed. For each additional -s specified, mthreads sleeps an additional second.
-v: selects additional levels of verbosity in the log file. The default (without -v) is to log mthread's startup, the totals for each pass, the inclusion of the enhanced expire option, and major database errors. Add one -v to get extra reference line problems logged into the file. Add a second and a third for even more (useless?) information. A fourth will cause mthreads to output each group's name into the log file before it is processed.
-z: tells mthreads to 'zap' any thread file it believes to be corrupt. This will allow the file to be regenerated from scratch on the next pass.
hierarchy_list: The hierarchy list is used to turn thread processing on or off for the listed groups. The groups are specified in a manner very similar to the news software's sys file: ``news'' matches all groups in news; ``!news'' excludes all groups in news; ``comp.all.ibm.pc,!comp.all.ibm.pc.all`` matches both comp.sys.ibm.pc and comp.binaries.ibm.pc, but not comp.binaries.ibm.pc.d.
The hierarchy_list is also used in conjunction with the debug flag to only process one or more groups for testing purposes.

OUTPUT

When mthreads is run in single-pass mode it generates a stream a status characters on stdout that present a visual display of what is happening. If single-pass mode is used for regular processing, this output can be redirected to /dev/null.

The output definitions:
       '.' = group's entry is up-to-date

       ':' = group processed -- no change

       '#' = group processed

       '-' = group processed -- is now empty

       'x' = group excluded in active

       'X' = group excluded in active2

       '*' = chdir failed (might be ok)

       '!' = write failed (is NOT ok)

       'e' = informational error

       'E' = database-affecting error -- please report!

CONFIGURATION

During the configuration of trn a choice was made about where to place the thread data files. They either exist as a .thread file in each group's spool directory, or they are a group.th file in a one-off directory structure on another drive. See the THREAD_DIR definition in config.h to review or change this definition.

REBUILDING

If the thread files are ever removed, also remove the file db.init in the RNLIB directory. This file contains the byte-order of the machine that generated the database, and needs to be removed to truly start from scratch. An easy way to get mthreads to remove all the files except for db.init is to specify the command:

: mthreads !all

This also turns off thread processing for all groups.

ERROR HANDLING

If the active2 file is removed or corrupted, it will be automatically rebuilt in the normal course of operation. The record of which groups should be threaded will be lost, however. Missing/corrupted thread files are automatically re-built.

EXAMPLES

Recommended commands to run on a regular basis are:

: mthreads -adve0630

to start up an mthreads daemon in verbose logging mode that automatically threads new groups and performs an extended expire at 6:30 am, or:

: mthreads -e >/dev/null

to run an mthreads single-pass with extended expire that leaves new groups unthreaded.

FILES

/usr/lib/news/active
$RNLIB/active2
$RNLIB/mt.log
$RNLIB/db.init
$RNLIB/LOCKmthreads
Lots of thread data files.

AUTHOR

Wayne Davison <davison@borland.com>

This document was created by man2html, using the manual pages.
Time: 06:35:44 GMT, December 12, 2024